> ## Documentation Index
> Fetch the complete documentation index at: https://keyring.docs.composio.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy with Docker

> Run the published distroless Node image with a mounted encryption configuration.

The official image runs Keyring as a non-root user in a small distroless container with no shell or
package manager.

## Pull the official image

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker pull composiohq/keyring:alpha
```

`alpha` is the current supported image tag on Docker Hub. It is a moving tag; use a controlled rollout
when adopting an update.

## Create runtime configuration

Create `keyring.env` without provider credentials:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
APP_ENV=production
RUNTIME=node
HOST=0.0.0.0
PORT=7464
AUTH_AUDIENCE=<COMPOSIO_ORG_ID>
AUTH_ISSUER=https://backend.composio.dev
AUTH_JWT_ALGORITHMS=RS256
AUTH_JWKS_URL=https://backend.composio.dev/.well-known/jwks.json
AUDIT_DURABILITY=required
OTEL_COLLECTOR_URL=https://otel.example.com
OTEL_COLLECTOR_HEADERS=Authorization=Bearer%20replace-me
LOG_LEVEL=info
ENCRYPTION_CONFIG=/etc/keyring/config.yaml
```

Replace `AUTH_AUDIENCE` with the Composio organization ID from **Project Settings → General**; the
placeholder above is not a valid production audience.

Replace the OTLP placeholders using the [telemetry delivery guide](/deployment/observability). Running
a collector beside Keyring is recommended for production.

Create `config.yaml` using one of the [KMS adapter examples](/configuration/kms_adapters). Prefer a workload identity so the file contains key references, not long-lived provider credentials.

<Warning>
  Treat both files as secrets if either contains an OTLP credential, cloud credential, Vault token,
  private key, or access token. Do not bake them into the image.
</Warning>

## Run the container

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
docker run --rm \
  --name keyring \
  --env-file keyring.env \
  --mount type=bind,src="$PWD/config.yaml",dst=/etc/keyring/config.yaml,readonly \
  --publish 127.0.0.1:7464:7464 \
  composiohq/keyring:alpha
```

The process listens on `0.0.0.0` inside the container so port publishing works, while the example binds only to host loopback. Put a reviewed TLS reverse proxy or private load balancer in front of it before remote use.

## Verify the deployment

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --fail http://127.0.0.1:7464/healthz
curl --fail http://127.0.0.1:7464/readyz
curl --fail http://127.0.0.1:7464/transfer-keys
```

## Container-platform identity

With AWS adapters, `credential_source: runtime_environment` checks static AWS environment variables first, then ECS-compatible container credential endpoints. It supports ECS/Fargate task roles and EKS Pod Identity. It intentionally does not use EC2 IMDS or IRSA/web identity.

The application refreshes expiring container credentials and may use still-valid cached credentials during a transient endpoint failure. Provider IAM must allow only the configured root and transfer keys.

## Healthcheck behavior

The image includes a healthcheck for `/healthz`. Because the container has no shell or diagnostic
utilities, perform troubleshooting from the host, a sidecar, or your platform tooling.