Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Run OpenD with Docker Compose

The smallest install: the app, the build worker and Postgres on one host, from the Compose file in the repository.

Before you begin

You need Docker with Compose, a checkout of the OpenD repository, and a host name readers can reach over HTTPS (terminate TLS in a reverse proxy in front of port 3000).

  1. Create the configuration from the examples. 
    cp deploy/.env.example deploy/.env
cp deploy/seed/seed.example.yaml deploy/seed/seed.yaml
  2. Edit deploy/.env.

    Set at least PUBLIC_URL and a random SESSION_SECRET. For publishing set GITHUB_WEBHOOK_SECRET; for reader sign-in, the OIDC_* variables; for the admin API, OPEND_ADMIN_TOKEN. Change POSTGRES_PASSWORD. See the environment variable reference.

  3. Edit deploy/seed/seed.yaml with your docs repository, organizations, entitlements and readers.

    See Manage organizations, entitlements and readers for the format.

  4. Build and start the stack. 
    docker compose -f deploy/docker-compose.yml up -d --build

    Compose starts Postgres, runs the migrate service once to create the schema, then starts app on port 3000 (or OPEND_PORT) and worker. Both share the blobs volume at /data/blobs.

  5. Load the seed file. 
    docker compose -f deploy/docker-compose.yml run --rm migrate seed /seed/seed.yaml

    Seeding is idempotent: everything is upserted, so run it again after each change.

  6. Check health: curl http://localhost:3000/healthz returns {"status":"ok"}.
  7. Connect GitHub and your identity provider.

    See Connect GitHub: webhooks and the GitHub App and Set up reader sign-in with OIDC.

Results

Readers sign in at PUBLIC_URL and get the live release for their version's line. The first push to a release ref publishes it.

To evaluate without an identity provider, set NODE_ENV=development and OPEND_DEV_LOGIN=1, then sign in at /auth/dev as any seeded reader. Never do this with real content.

The web editor is an optional Compose profile, editor. See Run the web editor.