DOCSEARCHbyAlgolia
Submit Docs

ODK Central

repository·master·Indexed 42 days ago

https://github.com/getodk/central

A Docker-based server for managing user accounts, permissions, and form definitions, serving as the central hub for ODK data collection clients. It provides programmatic access via REST, OpenRosa, and OData APIs and integrates with Enketo for web-based form collection.

Tokens
1.5K
Snippets
3
Records
8
Agent score
3%

What's inside ODK Central

  1. What is ODK Central

    master

    ODK Central is the server component of the ODK ecosystem. It provides the following core functionalities:

    • User Management: Manages user accounts and permissions.
    • Form Management: Stores Form definitions.
    • Data Collection: Acts as a central hub for data collection clients (like ODK Collect) to download forms and upload submitted data.
    • Extensibility: Provides programmatic access via REST, OpenRosa, and OData APIs.

    Central is deployed as a Docker-based application.

  2. Understand Central's branching model

    master

    The branching strategy for this repository differs from the central-backend and central-frontend repositories:

    • master branch: This is the stable branch. Users should clone this branch for production installations.
    • next branch: This reflects ongoing development for the upcoming version of Central.

    Note for Contributors: When submitting a Pull Request to this repository, target the next branch (unless you are only updating documentation like the README).

  3. Set up a local development environment with `make dev`

    master

    To develop on Central without manually setting up dependencies like PostgreSQL or Enketo, you can use make dev to start these services as Docker containers.

    This setup requires a local domain name (e.g., central-dev). You must configure this name in three places:

    1. Environment File: Set DOMAIN=central-dev in your .env file.
    2. Hosts File: Add 127.0.0.1 central-dev to your /etc/hosts file.
    3. Backend Configuration: Create a local.json file in the central-backend directory and set the default.env.domain value to http://central-dev:8989.
    # Example configuration steps
echo "DOMAIN=central-dev" >> .env
echo "127.0.0.1 central-dev" | sudo tee -a /etc/hosts

# Create local.json in central-backend/
cat <<EOF > central-backend/local.json
{
  "default": {
    "env": {
      "domain": "http://central-dev:8989"
    }
  }
}
EOF

# Start services
make dev

  4. Enable Sentry error reporting

    master

    To enable frontend error reporting and performance monitoring, set the SENTRY_DSN_FRONTEND environment variable in your .env file (refer to .env.template for the structure). After setting the variable, restart your Docker Compose stack to apply the changes.

    # After setting SENTRY_DSN_FRONTEND in .env
docker compose up -d

  5. Configure ODK Central database connections

    master

    ODK Central uses libpq environment variables for database connectivity. You can configure the connection using either the modern PG* variables or the legacy DB_* variables.

    Resolution Order:

    1. PGVAR specified in .env (including empty values like PGPASSWORD=).
    2. Corresponding legacy DB_VAR in .env.
    3. ODK default values.

    Available Variables:

    • PGHOST (defaults to postgres14 or DB_HOST)
    • PGDATABASE (defaults to odk or DB_NAME)
    • PGUSER (defaults to odk or DB_USER)
    • PGPASSWORD (defaults to odk or DB_PASSWORD)
    • PGAPPNAME (defaults to odkcentral)
    # Example using modern PG variables
PGHOST=my-db-host
PGDATABASE=odk_db
PGUSER=odk_user
PGPASSWORD=secure_password

# Example using legacy DB variables
DB_HOST=my-db-host
DB_NAME=odk_db
DB_USER=odk_user
DB_PASSWORD=secure_password

  6. Configure Nginx and SSL settings

    master

    The nginx service handles incoming web traffic and SSL termination.

    Key Configuration Variables:

    • DOMAIN: The domain name for the instance.
    • CERTBOT_EMAIL: Email for Let's Encrypt notifications (set via SYSADMIN_EMAIL).
    • SSL_TYPE: Type of SSL to use (default: letsencrypt).
    • SENTRY_ORG_SUBDOMAIN, SENTRY_KEY, SENTRY_PROJECT, SENTRY_DSN_FRONTEND: Sentry configuration for the frontend.
    • HTTP_PORT: Port for HTTP traffic (default: 80).
    • HTTPS_PORT: Port for HTTPS traffic (default: 443).

    Custom SSL: You can provide custom certificates by mounting them to ./files/local/customssl/ which maps to /etc/customssl/live/local/ inside the container.

  7. Configure Enketo settings

    master

    Enketo is used for web-based form collection. Its configuration is managed via the enketo service.

    Key Configuration Variables:

    • DOMAIN: The domain name for the instance.
    • SUPPORT_EMAIL: Support email address (set via SYSADMIN_EMAIL).
    • HTTPS_PORT: Port for HTTPS (default: 443).

  8. Configure ODK Central service environment variables

    master

    The service container is the core of ODK Central. You can customize its behavior via the following environment variables in your .env file:

    General & Network

    • DOMAIN: The domain name for the instance.
    • SYSADMIN_EMAIL: Email for the system administrator.
    • HTTPS_PORT: Port for HTTPS (default: 443).
    • NODE_OPTIONS: Additional Node.js options.

    Database

    • DB_SSL: SSL configuration (default: null).
    • DB_POOL_SIZE: Database connection pool size (default: 10).

    Email Settings

    • EMAIL_FROM: Sender email address (default: no-reply@$DOMAIN).
    • EMAIL_HOST: SMTP server host (default: mail).
    • EMAIL_PORT: SMTP server port (default: 25).
    • EMAIL_SECURE: Use secure connection (default: false).
    • EMAIL_IGNORE_TLS: Ignore TLS errors (default: true).
    • EMAIL_USER: SMTP username.
    • EMAIL_PASSWORD: SMTP password.

    Authentication (OIDC)

    • OIDC_ENABLED: Enable OpenID Connect (default: false).
    • OIDC_ISSUER_URL: The OIDC provider URL.
    • OIDC_CLIENT_ID: The OIDC client ID.
    • OIDC_CLIENT_SECRET: The OIDC client secret.

    Storage (S3)

    • S3_SERVER: S3 compatible server endpoint.
    • S3_ACCESS_KEY: S3 access key.
    • S3_SECRET_KEY: S3 secret key.
    • S3_BUCKET_NAME: S3 bucket name.

    Session & Monitoring

    • SESSION_LIFETIME: Session duration in seconds (default: 86400).
    • SENTRY_ORG_SUBDOMAIN, SENTRY_KEY, SENTRY_PROJECT, SENTRY_TRACE_RATE: Sentry error tracking configuration.