Quickstart with Docker¶

This guide will walk you through setting up Publish MDM locally using Docker Compose.

Prerequisites¶

Docker and Docker Compose
Credentials to access an ODK Central server, such as ODK Cloud
A Google Cloud Platform project with the Google Drive API and Google Picker API enabled.

Google OAuth Client ID¶

Publish MDM accesses spreadsheets on behalf of an end user, so you will need to create a Google OAuth client ID to authenticate users. To create a new OAuth client ID, follow the steps below:

Follow For End Users: Using OAuth Client ID from the gspread documentation to create a new OAuth client ID.
Save the client ID and client secret for the next step.

We use the https://www.googleapis.com/auth/drive.file Google Oauth scope, which allows users to only give access to specific files in their Google account. The scope is configured in the SOCIALACCOUNT_PROVIDERS Django setting. When adding or editing a form template, a user can select the spreadsheet for that template using the Google Picker.

Google API Key¶

Create an API key and save it for the next step. We need this to use the Google Picker API.

Google App ID¶

Go to your Google Cloud dashboard and save the “Project number” for the next step. We need this to use the Google Picker API.

Setup¶

A docker-compose.yaml file exists in the codebase that sets up a PostgreSQL database and Infisical, which is used for secrets management.

Create a new directory for the project and navigate to it:

mkdir publish-mdm
cd publish-mdm

Create a new file named docker-compose.yml and paste the following content:

include:
  - ../docker-compose.yaml

services:
  app:
    image: ghcr.io/caktus/publish-mdm:main
    command: daphne config.asgi:application -b 0.0.0.0 -p 8000
    env_file:
      - .env
    ports:
      - "8000:8000"
    depends_on:
      infisical:
        condition: service_healthy
      db:
        condition: service_started

volumes:
  dev_pgdata:

3. Create a new file named .env and paste the following content. If you do not have values for the INFISICAL_* variables yet, you will update them later (in step 6 below).

DJANGO_SETTINGS_MODULE="config.settings.deploy"
DATABASE_URL="postgresql://postgres@db/publish_mdm"
DJANGO_SECRET_KEY="django-insecure-CHANGEME"
SESSION_COOKIE_SECURE="False"
DJANGO_SECURE_SSL_REDIRECT="False"
DJANGO_MANAGEPY_MIGRATE="on"

# google oauth for django-allauth
GOOGLE_CLIENT_ID="your-client-id-from-above"
GOOGLE_CLIENT_SECRET="your-client-secret-from-above"
GOOGLE_API_KEY="your-api-key-from-above"
GOOGLE_APP_ID="your-app-id-from-above"

# Infisical
INFISICAL_API_URL=http://localhost:8888
INFISICAL_TOKEN="your-infisical-access-token"
INFISICAL_KMS_PROJECT_ID="your-infisical-kms-project-id"
# Set these if you're going to use Infisical to inject secrets as environment variables
INFISICAL_SECRETS_PROJECT_ID="your-infisical-secrets-project-id"
INFISICAL_SECRETS_ENV="your-infisical-secrets-environment-slug"

Run the following command to start the application and login:

docker compose up

Visit http://localhost:8000 in your browser and log in with your Google account.

After logging in, make yourself a superuser by running the following command:

docker compose exec app python manage.py shell -c "from apps.users.models import User; User.objects.all().update(is_staff=True, is_superuser=True)"

6. Infisical should be running at http://localhost:8888. You can now set up a KMS project and an access token. If you want infisical run to inject secrets as environment variables, you’ll also need to:

set up a Secrets project and add your secrets to it.
Update the docker-compose.yml file to change the command for the app service to infisical run --projectId $INFISICAL_SECRETS_PROJECT_ID --env $INFISICAL_SECRETS_ENV --silent -- daphne config.asgi:application -b 0.0.0.0 -p 8000. For further details on infisical run, see Infisical’s docs.

Update the INFISICAL_* variables in the .env file, then re-run step 4.

Local development¶

Build development image locally¶

To build the development image locally, run the following command:

docker build -t publish-mdm:latest --target deploy -f Dockerfile .

This will build the image with the tag publish-mdm:latest, which you can use in your docker-compose.yml file.