Use Canopy in Docker

Canopy detects Docker containers at startup using two signals — the /.dockerenv sentinel file and /proc/1/cgroup runtime keywords — and automatically activates in ephemeral mode. No seat is reserved; the activation disappears when the container stops.

docker run

Pass the license key as an environment variable. Never bake it into an image.

docker run --rm \
  -e CANOPY_LICENSE_KEY="$CANOPY_LICENSE_KEY" \
  -v "$(pwd):/repo" \
  ubuntu:24.04 \
  bash -c "
    curl -fsSL https://downloads.canopy.ironpinelabs.com/install.sh | sh
    export PATH=\"\$HOME/.canopy/bin:\$PATH\"
    canopy activate \"\$CANOPY_LICENSE_KEY\"
    canopy health --repo /repo
  "

Dockerfile (single stage)

FROM ubuntu:24.04

# Install Canopy binary into the image
RUN curl -fsSL https://downloads.canopy.ironpinelabs.com/install.sh | sh
ENV PATH="/root/.canopy/bin:$PATH"

# Activation is done at container runtime, not build time.
# Pass CANOPY_LICENSE_KEY via docker run -e or docker-compose environment.
ENTRYPOINT ["sh", "-c", "canopy activate \"$CANOPY_LICENSE_KEY\" && canopy serve /repo"]

docker run -e CANOPY_LICENSE_KEY="..." -v $(pwd):/repo my-forge-image

Multi-stage build

Use Canopy in the build stage to check code quality, then discard the license from the final image:

# Stage 1: lint + health check
FROM ubuntu:24.04 AS forge-check
RUN curl -fsSL https://downloads.canopy.ironpinelabs.com/install.sh | sh
ENV PATH="/root/.canopy/bin:$PATH"

COPY . /repo
ARG CANOPY_LICENSE_KEY
RUN canopy activate "$CANOPY_LICENSE_KEY" && \
    canopy index /repo && \
    canopy health --repo /repo

# Stage 2: production image — Canopy is not included, no license exposure
FROM node:22-slim AS production
COPY --from=forge-check /repo/dist /app
CMD ["node", "/app/index.js"]

docker build \
  --build-arg CANOPY_LICENSE_KEY="$CANOPY_LICENSE_KEY" \
  --target production \
  -t my-app:latest .

The CANOPY_LICENSE_KEY build arg is used only in the forge-check stage and is not present in the final image.

docker-compose

docker-compose.yml

services:
  canopy:
    image: ubuntu:24.04
    environment:
      # Set CANOPY_LICENSE_KEY in a .env file (not checked into git)
      CANOPY_LICENSE_KEY: ${CANOPY_LICENSE_KEY}
    volumes:
      - .:/repo
    command: >
      bash -c "
        curl -fsSL https://downloads.canopy.ironpinelabs.com/install.sh | sh &&
        export PATH=\"\$$HOME/.canopy/bin:\$$PATH\" &&
        canopy activate \"\$$CANOPY_LICENSE_KEY\" &&
        canopy serve /repo
      "

# .env (add to .gitignore)
CANOPY_LICENSE_KEY=your-key-here

Kubernetes

apiVersion: v1
kind: Secret
metadata:
  name: forge-license
type: Opaque
stringData:
  key: "your-forge-license-key"
---
apiVersion: batch/v1
kind: Job
metadata:
  name: forge-health-check
spec:
  template:
    spec:
      containers:
        - name: canopy
          image: ubuntu:24.04
          env:
            - name: CANOPY_LICENSE_KEY
              valueFrom:
                secretKeyRef:
                  name: forge-license
                  key: key
          command:
            - bash
            - -c
            - |
              curl -fsSL https://downloads.canopy.ironpinelabs.com/install.sh | sh
              export PATH="$HOME/.canopy/bin:$PATH"
              canopy activate "$CANOPY_LICENSE_KEY"
              canopy health --repo /repo
          volumeMounts:
            - mountPath: /repo
              name: source
      volumes:
        - name: source
          persistentVolumeClaim:
            claimName: source-pvc
      restartPolicy: Never

Canopy detects Kubernetes via kubepods in /proc/1/cgroup and activates in ephemeral mode automatically.

Overrides

Variable	Effect
CANOPY_EPHEMERAL=1	Force ephemeral mode (useful on VMs that look like containers)
CANOPY_EPHEMERAL=0	Force persistent mode — seat IS consumed (useful for long-lived container agents)

WSL2 note: Some WSL2 configurations expose Docker cgroup entries even on the host. If Canopy incorrectly detects ephemeral mode on your WSL2 machine, set CANOPY_EPHEMERAL=0 in your shell profile.