This project contains technical documentation written in Markdown in the /docs
folder. This covers:
- continuous integration
- deployment
- git branching
- project conventions
You can view it using mkdocs
by running:
mkdocs serve
The documentation will be available at: http://localhost:8001/
This repository includes docker-compose
configuration for running the project in local Docker containers,
and a fabfile for provisioning and managing this.
The following are required to run the local environment. The minimum versions specified are confirmed to be working: if you have older versions already installed they may work, but are not guaranteed to do so.
- Docker, version 19.0.0 or up
- Docker Desktop for Mac installer
- Docker Engine for Linux installers
- Docker Compose, version 1.24.0 or up
- Install instructions (Linux-only: Compose is already installed for Mac users as part of Docker Desktop.)
- Fabric, version 2.4.0 or up
- Python, version 3.6.9 or up
Note that on Mac OS, if you have an older version of fabric installed, you may need to uninstall the old one and then install the new version with pip3:
pip uninstall fabric
pip3 install fabric
You can manage different python versions by setting up pyenv
: https://realpython.com/intro-to-pyenv/
If you are using Docker Desktop, ensure the Resources:File Sharing settings allow the cloned directory to be mounted in the web container (avoiding mounting
OCI runtime failures at the end of the build step).
Starting a local build can be done by running:
git clone https://github.com/UKGovernmentBEIS/BRE_DigitalRegulationNavigator_Alpha.git drn-alpha
cd drn-alpha
fab build
fab start
fab sh
Then within the SSH session:
./manage.py migrate
./manage.py createcachetable
./manage.py createsuperuser
./manage.py runserver 0:8000
The site should be available on the host machine at: http://127.0.0.1:8000/.
To set any custom configuration, copy settings/local.py.example
to settings/local.py
There are 2 ways to run the frontend tooling:
After starting the containers as above and running ./manage.py runserver 0:8000
, in a new
terminal session run fab npm start
. This will start the frontend container and the site will
be available on port :3000 using browsersync. E.G localhost:3000
.
To run the FE tooling locally. Create a .env
file in the project root (see .env.example) and add FRONTEND=local
.
Running fab start
will now run the frontend container and you can start npm locally instead
There are a number of other commands to help with development using the fabric script. To see them all, run:
fab -l
Frontend npm packages can be installed locally with npm, then added to the frontend container with fabric like so:
npm install promise
fab npm install
Python packages can be installed using poetry in the web container:
fab sh-root
poetry install notifications-python-client
After adding or updating packages, run poetry export --extras gunicorn --without-hashes --output requirements.txt
for GOV.UK PaaS
To set environment variables in GOV.UK PaaS, use cf set-env APP_NAME VARIABLE VALUE
.
Key variables: COMPANIES_HOUSE_API_KEY
, NOTIFY_KEY
, NOTIFY_EMAIL_TEMPLATE_ID
. If you have not yet done so,
generate a random long value for SECRET_KEY
and set it as well.
To enable HTTP Authentication, set BASIC_AUTH_LOGIN
, BASIC_AUTH_PASSWORD
.
For further variables, see settings/base.py
(search for env.get
)
A manual deployment workflow would looks somethiong like
# build static assets
nvm use
npm install
npm run build:prod
# ensure requirements.txt is up to date
poetry export --extras gunicorn --without-hashes --output requirements.txt
# Login (note --sso is used if you have enabled SSO). Select sandbox for the environment
cf login -a api.london.cloud.service.gov.uk --sso
# push to GovPaaS. See https://docs.cloud.service.gov.uk/deploying_apps.html#deploy-a-django-app for more
cf push