Docker Image (GHCR)

OpenConnector ships a prebuilt Docker image on the GitHub Packages container registry (GHCR), so you can run it without cloning the repository or building anything. The image is:

ghcr.io/oomol-lab/open-connector

Choose A Tag

Tag	Points at	Use it when
`latest`	the newest published release	you want the current stable runtime
`<release-version>`	a specific release (immutable)	you deploy to production and want a pinned, reproducible build
`tip`	the latest commit on `main`	you want to try changes that are not released yet
`<short-sha>`	a specific `main` commit (immutable)	you want to pin an exact pre-release build

For production, pin a specific released version instead of latest.

Pull

The image is public, so no sign-in is required:

docker pull ghcr.io/oomol-lab/open-connector:latest

If you get an unauthorized or denied error, sign in with a GitHub token that has the read:packages scope:

echo "$GITHUB_TOKEN" | docker login ghcr.io -u <github-username> --password-stdin

The image is multi-arch (linux/amd64 + linux/arm64), so Docker automatically pulls the variant that matches your machine — running natively on Intel/AMD hosts and on arm64 hosts such as Apple Silicon and AWS Graviton. No --platform flag is needed.

Run

The image listens on port 3000, binds to 0.0.0.0, and stores runtime data in /app/data.

First generate the runtime secrets and save them somewhere safe. OOMOL_CONNECT_ENCRYPTION_KEY encrypts stored credentials, OAuth client configuration, and completed idempotent Action responses; if it is lost, the encrypted data in /app/data cannot be recovered. OOMOL_CONNECT_ADMIN_TOKEN authenticates the admin API and console.

# Save both values in a password manager or secrets vault before running.
export OOMOL_CONNECT_ENCRYPTION_KEY=$(openssl rand -base64 32)
export OOMOL_CONNECT_ADMIN_TOKEN=$(openssl rand -base64 32)

Then run the image, mounting a volume so data survives restarts:

docker run -d \
  --name open-connector \
  -p 3000:3000 \
  -v open_connector_data:/app/data \
  -e OOMOL_CONNECT_ORIGIN="https://api.example.com" \
  -e OOMOL_CONNECT_ENCRYPTION_KEY="$OOMOL_CONNECT_ENCRYPTION_KEY" \
  -e OOMOL_CONNECT_ADMIN_TOKEN="$OOMOL_CONNECT_ADMIN_TOKEN" \
  ghcr.io/oomol-lab/open-connector:latest

See configuration.md for the full environment variable reference and credentials.md for connecting providers.

PostgreSQL Migrations

When using PostgreSQL, run the image's explicit migrate command before the first server start and before starting a newer image that contains pending migrations. Use the same image tag that you will deploy:

OPEN_CONNECTOR_VERSION="<release-version>"

docker run --rm \
  -e OOMOL_CONNECT_DATABASE_URL="postgresql://migration_user:[email protected]:5432/open_connector?sslmode=verify-full" \
  "ghcr.io/oomol-lab/open-connector:${OPEN_CONNECTOR_VERSION}" \
  migrate

Replace <release-version> with the exact release tag used by the server you will deploy. The migration image and server image must use the same tag.

The command exits after applying migrations and does not start the HTTP server. Starting the image without a command still starts the server, which only checks schema readiness and never applies PostgreSQL DDL.

Docker Compose

The repository ships a docker-compose.yml that runs this published image. From a checkout, export the secrets shown above and start it:

docker compose up

With OOMOL_CONNECT_DATABASE_URL exported, run PostgreSQL migrations as a one-off Compose command:

docker compose run --rm connector migrate

To build from source instead of pulling, add the build overlay:

docker compose -f docker-compose.yml -f docker-compose.build.yml up --build

Verify

Check the health endpoint:

curl http://localhost:3000/health

The expected response is:

{ "ok": true }

How Images Are Published

Images are built and pushed automatically, so the tags above stay current: every push to main updates tip and adds the <short-sha> tag, and every published release adds latest and the release version. Each tag is a multi-arch manifest built natively for linux/amd64 and linux/arm64. The build is defined in .github/workflows/publish-docker.yml.

4.8 KiB Raw Permalink Blame History