conference-website/README.md

# Blender Conference

## Requirements

* Python 3.10
* [virtualenv](https://pypi.org/project/virtualenv/)
* [PostgreSQL](https://www.postgresql.org/download/)

Recommended for local development:

* [virtualenvwrapper](https://pypi.org/project/virtualenvwrapper/)

`virtualenvwrapper` adds commands for naming, creating, listing, activating and deactivating
Python `virtualenv`s, which makes it much easier to work on various Python projects.

If you prefer not to use it, any other way of creating a `virtualenv`
or [venv](https://docs.python.org/3.10/library/venv.html) will do.

## Development quick start

* Checkout the `main` branch
* `mkvirtualenv -a `pwd` blender-conference -p /usr/bin/python3.10`
* `pip3 install 'poetry==1.4.2'`
* `poetry install`
* `git submodule update --init`

### Environment

We use `python-dotenv` to manage application settings. By default, the application can run locally
without any configuration. For development (or production) overrides, create a .env file at the root
of the repo that looks like:

```
# Development settings
DEBUG=True
CONN_MAX_AGE=600
```

### Setup database

Blender Conference requires [PostgreSQL](https://www.postgresql.org/download/) set up and running.

If you have the `createuser` and `createdb` utilities:

    createuser conference -P
    createdb -O conference conference

Alternatively, to create a new Blender Conference database, run this as the PostgreSQL root user:

    CREATE USER conference CREATEDB PASSWORD 'conference';
    CREATE DATABASE conference OWNER conference;
    \c conference
    CREATE SCHEMA conference;
    GRANT ALL ON schema conference TO conference;

In case of production, omit `CREATEDB` and make sure that both `postgres` and `conference` users have secure hard to guess passwords set. You can change the password using:

    ALTER ROLE conference WITH PASSWORD 'new_password';

Create a `DATABASE_URL` value in the `.env` file  that looks like:

    DATABASE_URL=postgres://conference:conference@localhost:5432/conference

#### Load production snapshot (recommended) or start with an empty database

    1. `docker exec --user postgres -i postgres psql conference < conference_prod_dump`
    or
    2. `manage.py migrate`

### Create superuser

    echo "from django.contrib.auth import get_user_model; User = get_user_model(); User.objects.create_superuser('admin', 'admin@blender.org', 'password')" | ./manage.py shell

### Create system user

Conference uses a special system user to log various changes via admin `LogEntry`.

In order for this to work locally, `SYSTEM_USER_ID` must be set in the settings.
The following will create a user and print out its ID, which you can then copy-paste into your `settings.py`:

    echo "from django.contrib.auth import get_user_model; User = get_user_model(); print(User.objects.create_user('system', 'system@blender.org', 'password').id)" | ./manage.py shell

### Start development server

Setup application to run on port 8009:

    manage.py runserver 8009

### Setup OAuth application in Blender ID

Create an OAuth2 app with the following configuration:

    * Confidential
    * Authorization Code
    * Use http://conference.local:8009/oauth/authorized as redirect url
    * Skip authorization

You can always bypass Blender ID by logging in via the admin portal:

    * URL: `http://conference.local:8009/admin/`
    * User: `admin`
    * Password: `password`


## Running tests

Tests can be run by issuing `./test.sh` in the repository root directory.


## Update BWA (`assets_shared/`)

For updating the base styling provided by [Blender Web Assets](https://developer.blender.org/diffusion/BWA/), navigate to `assets_shared/` and pull latest changes:

    cd assets_shared/
    git checkout master && git pull
    cd ..

**N.B.:** because project's static assets depend on BWA SASS modules, and "compiling" those can fail due to, e.g., incorrect font paths or missing files, always check that `collectstatic` works before committing this kind of update:

    ./manage.py collectstatic  --noinput

After making sure everything looks as expected, commit the updated submodule reference:

    git add assets_shared
    # add and commit the rest of the changes


## Panel setup

* The panel is available at `/<edition>/panel`


## Deploy to production

In order to put commits in production, they need to be moved from the `master` branch into the
`production` branch:

    git checkout production && git merge --ff-only master

Use `./deploy.sh quick|full` to deploy to production. If you added or updated a package, you must
run `full` to update the base Docker image and ensure the presence of new or updated packages.
Otherwise, `quick` simply collects the latest version of the code and assets.


## Update requirements.txt

For deployments not requiring Poetry, we use requirements.txt. That file is updated by manually
running:

    poetry export --without-hashes --without-urls | awk '{ print $1 }' FS=';' > requirements.txt


## Media and Static Files configuration

By default, we use Django's default static files configuration. However, in case of deployment to
platforms that do not support serving static files, it is possible to configure S3 compatible
storage for media, and enable WhiteNoise to serve static assets.

This can be done by adding declaring the following env variables:

```
AWS_STORAGE_BUCKET_NAME=''
AWS_S3_REGION_NAME=''
AWS_S3_ENDPOINT_URL=''
AWS_ACCESS_KEY_ID=''
AWS_SECRET_ACCESS_KEY=''

MEDIA_ROOT='media'
MEDIA_URL='${AWS_S3_ENDPOINT_URL}/'
STORAGE_DEFAULT='storages.backends.s3.S3Storage'

USE_WHITENOISE=True
```

## Custom Looks

Use the `HAS_OVERRIDES_APP=True` setting to register an optional 'overrides' app which whill
override templates and static (useful to fully customize the look of the website).