Docker and containers

For a container you control, choose the token-and-instructions path in capy deploy. It emits SECRETS_BLOB and PROJECT_KEY. Put both in the container environment and make capy run the entrypoint.

Install Capy in the image

The npm package is the simplest choice for a Node application:

FROM node:22-slim
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm install -g @capysc/cli
COPY . .

ENTRYPOINT ["capy", "run", "--"]
CMD ["node", "server.js"]

For an image that does not otherwise need Node, install the released native binary in a build stage. The installer selects the platform binary, verifies the published checksum when it is available, and falls back to npm only when needed.

FROM node:22-bookworm-slim AS capy
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
  && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://raw.githubusercontent.com/capysc/capy-cli/main/install.sh | \
  CAPY_VERSION=0.9.7 CAPY_PREFIX=/opt/capy CAPY_NO_NPM_FALLBACK=1 bash

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates libstdc++6 \
  && rm -rf /var/lib/apt/lists/*
COPY --from=capy /opt/capy/bin/capy /usr/local/bin/capy
WORKDIR /app
COPY ./my-server /app/my-server
ENTRYPOINT ["capy", "run", "--"]
CMD ["/app/my-server"]

The native-only example disables npm fallback because only the executable is copied into the final image. Exclude .env, .env.pre-capy.old, and local Capy state from the image with .dockerignore. Build the image without the runtime pair. Supply it when the container starts:

docker build -t my-app .
docker run --env-file /etc/my-app/capy-runtime.env -p 3000:3000 my-app

/etc/my-app/capy-runtime.env should contain only deployment configuration and be readable by the account that starts the container:

SECRETS_BLOB=replace-with-the-generated-value
PROJECT_KEY=replace-with-the-generated-value

Compose and Kubernetes

Keep the pair outside the application repository. For Compose, point at an externally managed env file:

services:
  app:
    build: .
    env_file: /etc/my-app/capy-runtime.env
    ports:
      - "3000:3000"

For Kubernetes, create or update a cluster secret through your normal secret-management workflow and inject it into the container:

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          image: registry.example.com/my-app:latest
          envFrom:
            - secretRef:
                name: capy-runtime

The image entrypoint decrypts at container startup, then starts the child process. It contacts the Capy service once at that point and does not read local .env in deployed mode. With the emitted SECRETS_BLOB / PROJECT_KEY names, any same-named variable already present in the container takes precedence; remove stale plaintext duplicates when the Capy value must be used.

Updates and revocation

Create a distinct pair for each environment. When values change, mint a new pair from the correct Capy branch, update the external secret store, and restart the workload. Revoke unused pairs with capy deploy revoke <deploy-id>; already-running containers retain their environment until they restart.

Running your app

Runtime-pair mode detection and precedence.

Getting started

Using Capy

Deploying

Organizations

Branches

Team

CLI reference

Under the hood

Comparisons

Docker and containers

Install Capy in the image

Compose and Kubernetes

Updates and revocation

Running your app

​Install Capy in the image

​Compose and Kubernetes

​Updates and revocation

Running your app

Install Capy in the image

Compose and Kubernetes

Updates and revocation