torchbox / wagtail-torchbox

Wagtail build of Torchbox.com

Torchbox.com on Wagtail

This is the main Torchbox.com website. The careers section of this site can be found at torchbox/careers.

Project Setup

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.

• 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
  • Install instructions
• 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/

Required Permissions

Ask in the Heroku channel for staging access permissions: heroku access:add <your email address> --app torchbox-staging

Make sure you've updated Heroku to the latest version (with heroku update) or you will be denied access.

Ask another developer for permissions to clone and make merge requests to the GitHub repository.

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 https://github.com/torchbox/wagtail-torchbox.git
cd wagtail-torchbox
fab build

Then, to pull staging data from Heroku,

fab heroku-login

Use your Heroku API key as your password. You can find this in your heroku account details page.

fab pull-staging-data

You can also pull images from the site with fab pull-staging-images, note this is a lot of data.

Now run

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/

Frontend Development

To automatically have CSS, JS and other file changes compile and refresh in the browser during local development, you'll have to run the frontend build tools.

There are 2 ways to run the frontend tooling:

Locally

Open a new terminal window while keeping the server running in the background, and run the following commands.

nvm use
npm install
npm start

The site should now be accessible with livereload at http://localhost:3000.

Note that fnm is a faster version of nvm which behaves in the same way. See the repository for installation instructions.

Within the Frontend Docker Container

After starting the containers as above and running ./manage.py runserver 0:8000, open a new terminal session and run fab npm start.

The site should now be accessible with livereload at http://localhost:3000.

Front-end assets

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

Installing Python Packages

Python packages can be installed using poetry in the web container:

fab sh-root
poetry install wagtail-guide

Deployments

Merges to master and staging will automatically trigger a deployment to the production and staging sites, respectively.

How To Reset the Docker Containers

If you have issues related to working on the project previously, consider running fab destroy to get rid of all old containers and databases, starting the build afresh.

fab stop will switch off the containers without harming their data, ready for future reuse.

On MacOS you can restart docker desktop if old docker instances don't want to quit.

On Linux, you can identify the running Docker processes with

docker ps

Then run docker container stop <container_id> to stop a container, or docker container kill <container_id> to get rid of the container and its database.

Other Fab Commands

There are a number of other commands to help with development using the fabric script. To see them all, run:

fab -l