Deploying CantusDB locally for development - DDMAL/CantusDB GitHub Wiki

This page explains how to deploy Cantus Database for local development.

Set-up

  • Install Docker (ensure Compose > v2) and clone the CantusDB repo.
  • Put the dev_env file (which can be found on the CantusDB Resources page on the DDMAL wiki) under config/envs/. Note that this file should NOT be committed to the repo (it is included in .gitignore).
  • Check that the value of the PROJECT_ENVIRONMENT variable is DEVELOPMENT.
    • (The project is configured to turn on the Django Debug Toolbar and display tracebacks in the browser in case of errors when PROJECT_ENVIRONMENT is set to DEVELOPMENT)
  • Two versions of docker-compose.yml exist in the repository: docker-compose.yml and docker-compose.yml.development. If you use the Dev Containers extension in VSCode for local development, you'll want to replace the contents of docker-compose.yml with docker-compose.yml.development. Otherwise, you can use docker-compose.yml.
  • Duplicate config/nginx/conf.d/cantusdb.conf.development and rename it to cantusdb.conf.

Building containers

  • Ensure Docker is running.
  • If you're using VS Code as your editor, you can put the devcontainer.json file (see the CantusDB Resources page on the DDMAL wiki) under CantusDB/.devcontainer/. Open the repo in VS Code and then follow VS Code's prompts to install Remote-Containers extension and then, as prompted, Reopen in Container.
  • Otherwise:
    • run docker compose build to build containers.
    • run docker compose up to run containers (add the -d flag to run them in the background).
  • At this point, you should be able to visit the app to verify everything is working. At any point, if the Docker container is running, you should be able to navigate to a page like localhost/feasts/ in your browser and view the CantusDB app.
  • During an initial run of the Docker containers, you may find an error in the postgres container: initdb: error: directory "/var/lib/postgresql/data" exists but is not empty. In this case, you can remove the line beginning COPY in postgres/Dockerfile, and then re-build and re-run the containers. The database will now be initialized, and you can add the line back to postgres/Dockerfile and subsequent builds will work.

Using development dependencies

CantusDB makes use of a few python dependencies for code formatting, linting, and type checking (e.g. black, pylint, etc.) that can be useful in development. If you are using Dev Containers, no additional steps are needed. If you are not using Dev Containers, you will want these dependencies installed on your host machine. The Managing python dependencies page details how to install these dependencies with poetry.

Loading initial data

If you are starting development or otherwise want to sync your local database with the production CantusDB contents, you'll need to populate your local deployment with data. See the Populating the database section for instructions. Note that in order to SSH into production or staging, the system administrator will need to create a user for you. As of 17 Feb 2026, you should contact Lucas, Liam, or Andrew in that order.

Collecting Static Files

  • In the situation where you visit the app in the browser and the formatting looks wrong or images aren't loading, you may need to collect static files: in the django container, run python manage.py collectstatic. This command prompts django to find static files like images and style sheets and copy them into the database where they will be made accessible to a browser requesting these resources. (This step may not always be necessary, but there's no harm in running it again even if the app is already set up properly)

Setting up Git Hooks

If you are planning on contributing to CantusDB, note that we keep our codebase formatted to be compliant with Black. It is recommended that you set up a git hook to ensure your code is compliant. To do this, you must:

  • In your local copy of the repository, navigate to /.git/hooks/ and create a file called pre-commit. To this file, add the following code:
black --check .

With this file in place, any time you try to git commit, Black will run and prevent the commit from occurring if it finds a non-compliant file in the current working directory. If this occurs, you can either fix the error yourself, or run black . to make Black format any non-compliant files itself.

Populating next_chant and is_last_chant_in_feast fields

Depending on whether these scripts were run before fixtures were created, the populate_next_chant and populate_is_last_chant_in_feast may need to be run. See Data migration from the old cantus to the new cantus for further information