ODK Central¶

This guide will walk you through setting up ODK Central locally using Docker Compose for development purposes with Publish MDM. This is not intended for production use. For production deployments, see the official Installing ODK Central guide.

Note

The compose file in this guide uses forked images of ODK Central services to support overriding the default configuration with environment variables. The images are hosted on Caktus Group’s GitHub Container Registry and are built from the caktus/central repository.

Prerequisites¶

Docker and Docker Compose
PostgreSQL (to use a shared database cluster with Publish MDM)
ngrok or Tailscale (for tunneling connections from ODK Collect to your ODK Central instance)

Tunnel¶

ODK Collect requires a valid HTTPS certificate to connect to ODK Central. To create a secure tunnel to your local services, you can use a tunneling service like ngrok or Tailscale.

ngrok¶

Install ngrok and connect your ngrok agent to your ngrok account following the Getting Started guide.
Create a static subdomain for your ngrok account.

Make a note of the HTTPS URL ngrok provides. You will need this to configure ODK Collect to connect to your local ODK Central instance.
Start a tunnel to your local ODK Central instance:

ngrok http 9100 --url https://<your-static-subdomain>.ngrok-free.app

Setup¶

Create a central database in your local PostgreSQL instance:

dropdb --if-exists central && createdb central

Note

If you’re on Linux, you may need to update the PostgreSQL configuration to allow connections from the Docker network. Here’s how you can do that on a fresh PostgreSQL 17 installation:

sudo -u postgres psql -c "ALTER SYSTEM SET listen_addresses TO '*';"
sudo -u postgres createuser --superuser <your-username>
sudo -u postgres psql -c "ALTER USER <your-username> WITH PASSWORD '<your-password>';"
sudo -u postgres sh -c "echo 'host    all             all             0.0.0.0/0               md5' >> /etc/postgresql/17/main/pg_hba.conf"
sudo systemctl restart postgresql

Then you can start the services with the following command:

DOMAIN=<your-tunnel-fqdn> PGHOST=172.17.0.1 PGPASSWORD=<your-pass> docker compose up -d

Or you can set the environment variables in a .env file.

Start the ODK Central services:

cd services/
DOMAIN=<your-tunnel-fqdn> docker-compose up -d

Create an admin user:

# Create a new account
docker compose exec service odk-cmd --email YOUREMAIL@ADDRESSHERE.com user-create
# Make the new account an administrator
docker compose exec service odk-cmd --email YOUREMAIL@ADDRESSHERE.com user-promote

Access the ODK Central web interface at https://<your-tunnel-fqdn> and log in with the admin user you created.
Finally, when you log in to Publish MDM, create a Central Server with the base URL set to https://<your-tunnel-fqdn>.