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:
poetry run 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.
There are a number of other commands to help with development using the fabric script. To see them all, run:
fab -l
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/ONSdigital/dis-wagtail-alpha
cd dis-wagtail-alpha
fab build
fab migrate
fab start
This will start the containers in the background, but not Django. To do this, connect to the web container with fab sh
and run honcho start
to start both Django and the scheduler in the foreground.
If you only want to run Django, run honcho start web
or ./manage.py runserver 0.0.0.0:8000
.
Then, connect to the running container again (fab sh
) and:
dj createcachetable
dj createsuperuser
The site should be available on the host machine at: http://127.0.0.1:8000/
Upon first starting the container, the static files may not exist, or may be out of date. To resolve this, simply run make load-design-system-templates
.
Here are the common commands:
# Install front-end dependencies.
npm install
# Start the Webpack build in watch mode, without live-reload.
npm run start
# Start the Webpack server build on port 3000 only with live-reload.
npm run start:reload
# Do a one-off Webpack development build.
npm run build
# Do a one-off Webpack production build.
npm run build:prod
There are two ways to run the frontend tooling:
- In Docker. This is the default, most portable and secure, but much slower on macOS.
- Or run npm commands from a terminal on your local machine. Create a
.env
file in the project root (see.env.example
) withFRONTEND=local
.
Python packages can be installed using poetry
in the web container:
fab sh
poetry add wagtail-guide
To reset installed dependencies back to how they are in the poetry.lock
file:
fab sh
poetry install --no-root
If you wish to install extra packages in your local environment, to aid with debugging:
fab sh-root
apt-get update
apt-get install <package> # eg. apt-get install vim
Then, exit the terminal and connect again using fab sh
.
If you run fab build
, or the container is rebuilt for some other reason, these packages will need re-installing.
If a package is always needed (eg a Python package requires a system dependency), this should be added to the Dockerfile
.
Translations are stored in ons_alpha/locale/
.
When updating translated strings, run make messages
to update the *.po
files, which can then be handled to translators. These generated files should be committed to the repository.
When new translations are added to the *.po
files, run make compile-messages
. These generated files should be committed to the repository.
See Django's documentation for further details.
This project uses poetry
for dependency management and make
for common development tasks.
Ensure you have the following installed:
- Python: Version specified in
.python-version
. We recommend using pyenv for managing Python versions. - Poetry: This is used to manage package dependencies and virtual environments.
-
Clone the repository:
git clone https://github.com/ONSdigital/dis-wagtail-alpha.git cd dis-wagtail-alpha
-
Install dependencies:
poetry install
This project uses Ruff
, pylint
, and black
for linting and formatting Python code and djhtml
for HTML linting.
-
To check linting issues:
make lint
-
To format the code:
make format