> ## Documentation Index
> Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Hub Publishing

> Publish Comis images to Docker Hub and pull official releases

Comis publishes official Docker images to Docker Hub under the
[comisai](https://hub.docker.com/u/comisai) organization. Releases are built
automatically on every version tag via GitHub Actions and produce multi-arch
manifests for `linux/amd64` and `linux/arm64`.

## Available images

| Image reference            | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `comisai/comis:X.Y.Z`      | Daemon + gateway, full `node:22-bookworm` base         |
| `comisai/comis:X.Y.Z-slim` | Daemon + gateway, smaller `node:22-bookworm-slim` base |
| `comisai/comis-web:X.Y.Z`  | Nginx-served web dashboard SPA                         |

## Tag strategy

For a release tag such as `vX.Y.Z`, the Docker workflow produces:

| Tag pattern                | Example       | Notes                             |
| -------------------------- | ------------- | --------------------------------- |
| `{{version}}`              | `X.Y.Z`       | Version-specific daemon image     |
| `{{major}}.{{minor}}`      | `X.Y`         | Moves forward to the latest patch |
| `latest`                   | `latest`      | Default variant, latest release   |
| `{{version}}-slim`         | `X.Y.Z-slim`  | Version-specific slim variant     |
| `{{major}}.{{minor}}-slim` | `X.Y-slim`    | Slim variant, latest patch        |
| `latest-slim`              | `latest-slim` | Slim variant, latest release      |

**Variants:**

* **Default** (`comisai/comis:latest`) -- `node:22-bookworm` base. Includes
  extra system packages useful for debugging in production.
* **Slim** (`comisai/comis:latest-slim`) -- `node:22-bookworm-slim` base.
  Smaller image with a reduced attack surface. Recommended for most deployments.

<Tip>
  Pin a deployment to an exact version tag (for example,
  `comisai/comis:X.Y.Z`) rather than `latest` to avoid unexpected updates.
</Tip>

## Pulling images

```bash theme={}
# Latest slim daemon (recommended)
docker pull comisai/comis:latest-slim

# Specific version
docker pull comisai/comis:X.Y.Z

# Web dashboard
docker pull comisai/comis-web:latest
```

Use with Docker Compose by setting the image environment variables:

```bash theme={}
export COMIS_IMAGE=comisai/comis:latest-slim
export COMIS_WEB_IMAGE=comisai/comis-web:latest
docker compose up -d
```

Or in your `.env` file:

```bash theme={}
COMIS_IMAGE=comisai/comis:latest-slim
COMIS_WEB_IMAGE=comisai/comis-web:latest
```

## Automated releases via GitHub Actions

The workflow `.github/workflows/dockerhub-release.yml` runs on every `v*` tag
push after verifying that the tag exactly matches the `comisai` package version.
It builds multi-arch images for both `linux/amd64` and `linux/arm64` using
per-platform runners that merge into a single manifest — no QEMU emulation for
the daemon, which keeps build times fast.

### Workflow structure

```
push tag v* ─► version preflight ─┬─► build (amd64) ─┬─► merge-default ──► comisai/comis:x.y.z
                                  │                   │                       comisai/comis:x.y
                                  │                   │                       comisai/comis:latest
                                  │   build (arm64) ─┤
                                  │                   └─► merge-slim ────► comisai/comis:x.y.z-slim
                                  │                                        comisai/comis:x.y-slim
                                  │                                        comisai/comis:latest-slim
                                  │
                                  └─► build-web ──────────────────────► comisai/comis-web:x.y.z
                                                                          comisai/comis-web:x.y
                                                                          comisai/comis-web:latest

all Docker Hub outputs + successful npm and GHCR publishes ─────────► GitHub Release
```

Each `build` job compiles both the default and slim variants. Because the two
variants share the same build stage layers, the second variant uses the cached
layers and completes near-instantly.

### Required GitHub secrets

Add these two secrets at **Settings → Secrets and variables → Actions**:

| Secret               | Value                                             |
| -------------------- | ------------------------------------------------- |
| `DOCKERHUB_USERNAME` | `comisai`                                         |
| `DOCKERHUB_TOKEN`    | Docker Hub access token (Read/Write/Delete scope) |

To create an access token: Docker Hub → Account Settings → Personal access
tokens → Generate new token.

### Triggering a release

Pushing a `v*` tag starts the Docker Hub and npm publishing workflows in
parallel:

```bash theme={}
git tag vX.Y.Z
git push origin vX.Y.Z
```

The GitHub Release is the final coordinated step in the Docker Hub workflow. It
is created only after the Docker Hub default, slim, and web images are
published, and the npm and GitHub Container Registry workflows for the same
commit report success. A failed artifact build therefore does not create a
community-facing release that points to incomplete packages.

### Caching

Build layers are cached in GitHub Actions cache (`type=gha`) scoped by
platform and variant:

| Cache key                | Scope                  |
| ------------------------ | ---------------------- |
| `dh-default-linux/amd64` | Default variant, amd64 |
| `dh-default-linux/arm64` | Default variant, arm64 |
| `dh-slim-linux/amd64`    | Slim variant, amd64    |
| `dh-slim-linux/arm64`    | Slim variant, arm64    |
| `dh-web`                 | Web dashboard          |

Subsequent releases reuse cached dependency and build layers, cutting build
time significantly after the first run.

## Manual publishing

To build and push manually from the repository root:

```bash theme={}
VERSION=X.Y.Z
USER=comisai

# Daemon — default variant
docker build --build-arg COMIS_VARIANT=default \
  -t $USER/comis:$VERSION -t $USER/comis:latest -f Dockerfile .
docker push $USER/comis:$VERSION
docker push $USER/comis:latest

# Daemon — slim variant
docker build --build-arg COMIS_VARIANT=slim \
  -t $USER/comis:$VERSION-slim -t $USER/comis:latest-slim -f Dockerfile .
docker push $USER/comis:$VERSION-slim
docker push $USER/comis:latest-slim

# Web dashboard
docker build -t $USER/comis-web:$VERSION -t $USER/comis-web:latest -f Dockerfile.web .
docker push $USER/comis-web:$VERSION
docker push $USER/comis-web:latest
```

For multi-arch builds locally (requires `docker buildx`):

```bash theme={}
docker buildx create --use --name comis-builder   # one-time

docker buildx build --platform linux/amd64,linux/arm64 \
  --build-arg COMIS_VARIANT=default \
  -t $USER/comis:$VERSION -t $USER/comis:latest \
  -f Dockerfile --push .
```

## Related pages

<CardGroup cols={2}>
  <Card title="Docker Operations" icon="docker" href="/operations/docker">
    Production Dockerfile details, Compose services, and security hardening.
  </Card>

  <Card title="Install with Docker" icon="download" href="/installation/install-docker">
    Quick-start setup using the automated setup script.
  </Card>
</CardGroup>