Welcome to the ge-web wiki!

The ge-web application aims to replicate the most important features of the Girl Effect mobi sites with as little custom code as possible. These sites are built on Wagtail. Any custom code that has been written follows the Wagtail tutorial and examples from the documentation as much as possible. Please familiarise yourself with Wagtail development processes before undertaking work on this project https://docs.wagtail.org/en/stable/

NB!!!

This code repository and the Dockerhub repository it builds to are Public. Never commit credentials or other sensitive information.

Development

Development follows standard Python and Wagtail practices. We expect any development to be done in a Virtual Environment managed with Pip (we use ve for the environment name). Sqlite3 is the expected database engine for local development. This comes pre-installed with Linux and MacOS but this tutorial can be used if necessary https://www.tutorialspoint.com/sqlite/sqlite_installation.htm

Dependency library versions are specified in requirements.txt and development dependencies are specified in requirements-dev.txt. Whenever changes are made to the installed libraries these files must be updated because the Dockerfile uses them to setup the production environment.

Setup your local development environment using the steps below:

python3 -m venv ve
source ve/bin/activate 
pip3 install -r requirements.txt
pip3 install -r requirements-dev.txt
./manage.py migrate
./manage.py createsuperuser
./manage.py runserver

We strongly recommend doing peer code reviews. Create a new branch for any active development and then open a Pull Request in order to review it (and allow tests to run) before merging it into Main.

Front End Development

Requirements and instructions for Local dev are here

Static files are stored in the container, therefore ./manage.py collectstatic is run during the Docker build rather than at runtime.

Testing

We encourage unit tests to be written for any custom functionality. Standard Django testing frameworks are used to run unit tests on the code. Github Actions automatically runs the tests on any new commits (https://github.com/girleffect/ge-web/blob/main/.github/workflows/test.yml)

Run tests locally with:

./manage.py test --settings=geweb.settings.base

Github Actions also runs linting tools in the test workflow to encourage good quality code and the test run will fail if the code doesn't meet generally accepted standards.

Black, Flake8 and Isort are run with:

black --check .
flake8 . --count --show-source --statistics
isort -c .

Deployment

New commits made to the Main branch on GitHub will automatically be available on Divio (the hosting platform) and can be deployed to the testing or live environments. They will also trigger Github Actions to automatically build a new Docker image and push it to Dockerhub.

The Dockerfile is based on the one in the Wagtail project template https://github.com/wagtail/wagtail/blob/main/wagtail/project_template/Dockerfile Adjustments have been made to run Nginx in the same Docker container in front of the application. These include some configuration changes to Gunicorn, additional user management to ensure the applications are run with the correct user, and a startup script to make changes based on environment variables and run the application.

Running Nginx in front of a Django application is common practice, so that static and media files can be served directly and quickly. Nginx is used for this instead of Whitenoise because Nginx also handles the buffering of requests to the synchronous gunicorn workers ( https://docs.gunicorn.org/en/latest/design.html#choosing-a-worker-type). The Nginx configuration also sets some proxy headers and handles a number of redirects for us: www site domains and alternate/old domains.

The startup script allows Django migrations to be run at startup based on the RUN_MIGRATIONS environment variable. In Divio the applications are configured to run migrations as a release command instead. Running migrations when a container starts up allows deployments to be done at the push of a button but it could complicate the rollback process if something goes wrong. For this reason we strongly encourage deploying to a testing environment first and doing a database backup before any deployment that includes database migrations.

Configuration settings and secrets are pulled into the Django settings file from environment variables.

Important Environment variables required by this project:

• DATABASE_URL
• ALLOWED_HOSTS
• SECRET_KEY
• DJANGO_SETTINGS_MODULE
• PORT The port that the Docker container should listen on. This must be set to 8000 (it is sometimes necessary to set this explicitly in env vars because some container orchestration systems might overwrite it)
• SOCIAL_AUTH_GOOGLE_OAUTH2_KEY and SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET

Outstanding:

• HomePage, SectionPage, ArticlePage descriptions
• Themes explanation
• Forms documentation
• Comments documentation
• Media settings for S3 storage