-
Notifications
You must be signed in to change notification settings - Fork 6
Deploying CantusDB locally for development
This page explains how to deploy Cantus Database for local development.
- Install Docker (ensure Compose > v2) and clone the CantusDB repo.
- Put the
dev_env
file (which can be found on theCantusDB Resources
page on the DDMAL wiki) underconfig/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 isDEVELOPMENT
.- (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 toDEVELOPMENT
)
- (The project is configured to turn on the Django Debug Toolbar and display tracebacks in the browser in case of errors when
- Two versions of
docker-compose.yml
exist in the repository:docker-compose.yml
anddocker-compose.yml.development
. If you use the Dev Containers extension in VSCode for local development, you'll want to replace the contents ofdocker-compose.yml
withdocker-compose.yml.development
. Otherwise, you can usedocker-compose.yml
. - Duplicate
config/nginx/conf.d/cantusdb.conf.development
and rename it tocantusdb.conf
.
- Ensure Docker is running.
- If you're using VS Code as your editor, you can put the
devcontainer.json
file (see theCantusDB Resources
page on the DDMAL wiki) underCantusDB/.devcontainer/
. Open the repo in VS Code and then follow VS Code's prompts to installRemote-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).
- run
- 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
localhost
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 beginningCOPY
inpostgres/Dockerfile
, and then re-build and re-run the containers. The database will now be initialized, and you can add the line back topostgres/Dockerfile
and subsequent builds will work.
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. A developer wishing to make use of these dependencies will want them installed in the environment in which they are coding, viz. outside the django
application container. The Managing python dependencies page details how to install these dependencies with poetry.
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.
- 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)
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 calledpre-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.
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