Setup#

Prerequisites#

CODA is designed to run in Docker containers. Therefore, Docker is mandatory to run it. While it can run outside of Docker containers, we will not provide any support for it. It is recommended to use a Linux machine to run CODA.

Getting CODA#

As we do not provide any pre-built Docker images yet, the easiest way to get CODA is to clone the Git repository by entering the following command into a shell.

git clone https://github.com/coda-oa/coda

After cloning the repository, open the newly created coda directory.

Preparing environment variables#

CODA uses environment variable files to configure certain settings. The variable files you need to edit are located in the .envs/.production directory.

coda.env#

In coda.env you can set which port CODA will be run under by adjusting the CODA_EXPOSED_PORT variable.

django.env#

In django.env you must set the following variables:

DJANGO_SECRET_KEY=<your-secret-key>
DJANGO_ALLOWED_HOSTS=<your-allowed-hosts>
DJANGO_CSRF_TRUSTED_ORIGINS=<your-trusted-origins>

DJANGO_ALLOWED_HOSTS and DJANGO_CSRF_TRUSTED_ORIGINS should generally point to the same hosts. For example if CODA is running on the address coda.example.com then these variable could look as follows:

DJANGO_ALLOWED_HOSTS=coda.example.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://coda.example.com

For more information about these values, see the official Django documentation:

It is recommended to comment out unused variables with a leading #

postgres.env#

In postgres.env you need to set a password for the database:

POSTGRES_PASSWORD=<your-password>

Launching CODA#

All that’s left is to launch CODA using the provided startup script. Simply run the following command in a terminal from the CODA directory:

./commands/start-coda.sh --production

Or for a local development environment:

./commands/start-coda.sh --local

Even though this step appears to finish quickly, it can take a couple of minutes before CODA is accessible in your web browser. This happens because CODA needs to establish its Journal, Publisher and Contracts database on startup.

Creating a superuser#

After CODA has launched, you need to create a superuser to log in and create other users. Run the following command in your shell:

./commands/create-superuser.sh --production

Or for local environment:

./commands/create-superuser.sh --local

After creating a superuser, you should be able to log into CODA from your web browser.

Stopping CODA#

To stop CODA, use the stop script:

./commands/stop-coda.sh --production

Or for local environment:

./commands/stop-coda.sh --local

Backups#

CODA provides a built-in backup system to protect your database. It’s highly recommended to create regular backups of your CODA installation.

Creating a Backup#

To create a new database backup:

./commands/backups.sh --production create

Or for local environment:

./commands/backups.sh --local create

The backup will be automatically timestamped and stored in the PostgreSQL backup directory.

Listing Available Backups#

To see all available backups:

./commands/backups.sh --production list

Or for local environment:

./commands/backups.sh --local list

This will display all backup files with their names and creation dates.

Restoring from a Backup#

To restore CODA from a previous backup:

./commands/backups.sh --production restore <backup_name>

Or for local environment:

./commands/backups.sh --local restore <backup_name>

Replace <backup_name> with the exact name from the backup list (e.g., backup_2026_01_21_143022.sql.gz).

Important

The restore process will automatically:

  1. Stop the Django service to prevent database access

  2. Ensure PostgreSQL is running

  3. Restore the database from the backup file

  4. You’ll need to restart CODA afterward using ./commands/start-coda.sh --production