Skip to content

Local build

This repository includes docker-compose configuration for running the project in local Docker containers, and a fabfile for provisioning and managing this.

Dependencies

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.

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

Running the local build for the first time

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 git@github.com:TateMedia/tate-wagtail.git
export BUILD_ENV=dev
cd tate-wagtail
fab build
fab start
fab sh

Then within the SSH session:

dj migrate
dj createcachetable
dj createsuperuser
dj create_structural_pages
djrun

If any of the above fail, you may need to update the project dependencies:

poetry install  # If new dependencies have been added, otherwise...
poetry update   # This may take ~140s

The site should be available on the host machine at: http://127.0.0.1:8000/

Frontend tooling

Here are the common commands:

# Install front-end dependencies.
npm install
# Start the Webpack build in watch mode with live-reload on port 3000.
npm run start
# 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. Running fab start will start a frontend container. Use fab sh --service frontend in a separate terminal to SSH into the container. Then run npm commands within this new SSH session. exit once you’re done.
  • Or run npm commands from a terminal on your local machine. (Note: this way is generally preferred now, as the containerised method doesn't work too well with browsersync) Create a .env file in the project root (see .env.example) with FRONTEND=local. fab start will no longer start a frontend container.

Background Tasks (Celery)

In a second SSH session, run the following command to initialise the Celery worker for background tasks: 

./rootfs/app/start-celery.sh

This needs to be performed in a second session, as both djrun and celery worker are never-ending commands.

A second SSH session can be easily created by opening a second terminal and running fab sh again.

Installing python packages

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

Common tasks

Here are other commands you may need – view everything available with fab -l:

fab start                     # Start the development environment
fab stop                      # Stop the development environment
fab restart                   # Restart the development environment
fab destroy                   # Destroy development environment containers (database will lost!)
fab dellar-restore            # Restore the database from a snapshot in the db container
fab dellar-snapshot           # Snapshot the database, files will be stored in the db container
fab psql                      # Connect to the local postgres DB using psql
fab prod.get-shell-variables   # Get shell variables required for SSH session. Requires Azure CLI.
fab prod.open-shell            # Starts SSH session to App Service instance in Azure. Requires Azure CLI.
fab prod.pull-data             # Copies a **live** database from Azure to the local `db` container.
fab prod.pull-media            # Retrieve media files from Azure. Requires Azure CLI.
fab prod.sync-media            # Use `azcopy sync` to sync media files from Azure.

Visee site set-up

Visee (visee.tate.org.uk) is the internal sub-site used by the Visitor Experience team in Tate Britain and Tate Modern. To configure your local build to run the site, do the following:

  1. In the admin area, go to Settings > Sites and edit the Visee site. Change the hostname to 'visee.localhost' and the port to 8000:

Visee configuration page

  1. Also check the 'Serve pages from all sites' box on the main Site Settings page:

Site settings page

Now when you start the Django server, it should serve the Visee site at visee.localhost:8000.