[English](docker-ghcr.md) | [简体中文](docker-ghcr.zh-CN.md)

# 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:

```text
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:

```bash
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:

```bash
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.

```bash
# 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:

```bash
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](configuration.md) for the full environment variable reference and
[credentials.md](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:

```bash
OPEN_CONNECTOR_VERSION="<release-version>"

docker run --rm \
  -e OOMOL_CONNECT_DATABASE_URL="postgresql://migration_user:password@db.example.com: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`](../docker-compose.yml) that runs this published image.
From a checkout, export the secrets shown above and start it:

```bash
docker compose up
```

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

```bash
docker compose run --rm connector migrate
```

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

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

## Verify

Check the health endpoint:

```bash
curl http://localhost:3000/health
```

The expected response is:

```json
{ "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`](../.github/workflows/publish-docker.yml).