Docker Environments

Docker Environments

name: Docker Environments category: connect activateOn: docker-environment freedomLevel: high version: 1.0.0 description: > Docker-aware Mémoire operation. Detects Dockerfile, docker-compose.yml, and .devcontainer/ in the project root and adapts the Mémoire pipeline accordingly. Covers Figma bridge port-forwarding, CI/CD headless audits, shared MCP server as a team service, agent worker containers, and devcontainer setup.

1. Auto-Detection

Mémoire activates this Note when any of the following are present in the project root:

When detected, Mémoire applies these Docker-aware defaults:

• Bridge discovery checks localhost AND host.docker.internal
• Preview server binds to 0.0.0.0 (not 127.0.0.1)
• Port conflict warnings include Docker port-mapping guidance
• memi doctor output includes container networking status

2. Figma Bridge in Docker

Problem: Figma plugin runs on the host machine. Mémoire inside a container cannot auto-discover it — localhost inside the container is the container, not the host.

Fix: Forward the bridge port range from host to container.

yamlCopy code
# docker-compose.yml
services:
  memoire:
    ports:
      - "9223-9232:9223-9232"  # Figma bridge range

jsonCopy code
// .memoire/project.json
{
  "bridge": {
    "host": "0.0.0.0",
    "portRange": [9223, 9232]
  }
}

When NOT to use Docker for canvas work: If your primary workflow is Figma canvas operations (design, library, real-time sync), run Mémoire on the host. Port forwarding works but adds latency. Use Docker for CI, MCP, and agent workers.

3. CI/CD Headless Pipeline

Headless-Safe Commands

Dockerfile (CI Build)

dockerfileCopy code
FROM node:20-alpine AS base
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts
COPY . .
RUN npm run build

FROM base AS ci
ENV MEMOIRE_HEADLESS=true
ENV MEMOIRE_NO_BRIDGE=true
ENTRYPOINT ["node", "dist/cli.js"]

docker-compose.yml with Profiles

yamlCopy code
version: "3.9"
services:
  # Local dev — bridge enabled, ports forwarded
  memoire-dev:
    build: { context: ., target: base }
    profiles: ["dev"]
    ports:
      - "4400:4400"
      - "4401:4401"
      - "9223-9232:9223-9232"
    volumes: [".:/app", "/app/node_modules"]
    environment: [MEMOIRE_ENV=development]
    command: ["node", "dist/cli.js", "watch", "--code"]

  # CI — headless, no bridge
  memoire-ci:
    build: { context: ., target: ci }
    profiles: ["ci"]
    volumes: [".:/workspace"]
    working_dir: /workspace
    environment: [MEMOIRE_HEADLESS=true, MEMOIRE_NO_BRIDGE=true]
    command: ["node", "dist/cli.js", "audit", "--wcag", "--exit-code"]

  # MCP server — shared team service
  memoire-mcp:
    build: { context: ., target: base }
    profiles: ["mcp"]
    ports: ["4402:4402"]
    environment: [MEMOIRE_MCP_PORT=4402]
    command: ["node", "dist/cli.js", "mcp", "start"]
    restart: unless-stopped

Running CI Audits

bashCopy code
# Run headless WCAG audit
docker compose --profile ci run --rm memoire-ci

# Validate all specs
docker compose --profile ci run --rm memoire-ci \
  node dist/cli.js spec validate --all --strict

# Dry-run code generation
docker compose --profile ci run --rm memoire-ci \
  node dist/cli.js generate --dry-run

GitHub Actions

yamlCopy code
name: Design System CI
on: [push, pull_request]
jobs:
  design-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: WCAG audit
        run: docker compose --profile ci run --rm memoire-ci
      - name: Validate specs
        run: docker compose --profile ci run --rm memoire-ci node dist/cli.js spec validate --all --strict
      - name: Generate (dry run)
        run: docker compose --profile ci run --rm memoire-ci node dist/cli.js generate --dry-run

Exit Codes

Soft policy: gate on 2+. Strict policy: gate on 1+.

4. Shared MCP Server (Team Service)

Problem: Each developer running memi mcp start locally produces divergent design system state.

Fix: Deploy one containerized MCP instance. All Claude Code and Cursor sessions on the team point to it.

dockerfileCopy code
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
VOLUME ["/workspace/.memoire"]
EXPOSE 4402
CMD ["node", "dist/cli.js", "mcp", "start", "--port", "4402"]

Claude Code config for each developer — replace localhost with the shared host:

jsonCopy code
{
  "mcpServers": {
    "memoire": {
      "url": "http://memoire.internal:4402/mcp",
      "transport": "http"
    }
  }
}

Shared volume for .memoire/ state:

yamlCopy code
services:
  memoire-mcp:
    volumes:
      - design-system:/workspace/.memoire
    command: ["node", "dist/cli.js", "mcp", "start"]

volumes:
  design-system:
    driver: local
    driver_opts:
      type: nfs
      o: addr=nas.internal,rw
      device: ":/design-system"

5. Agent Workers as Containers

Each role gets isolated resources, its own restart policy, and no shared process state.

yamlCopy code
services:
  token-engineer:
    build: .
    command: ["node", "dist/cli.js", "agent", "spawn", "token-engineer"]
    environment: [MEMOIRE_AGENT_ROLE=token-engineer]
    restart: on-failure:3
    healthcheck:
      test: ["CMD", "node", "dist/cli.js", "agent", "status", "--role", "token-engineer", "--json"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

  component-architect:
    build: .
    command: ["node", "dist/cli.js", "agent", "spawn", "component-architect"]
    environment: [MEMOIRE_AGENT_ROLE=component-architect]
    restart: on-failure:3

  accessibility-checker:
    build: .
    command: ["node", "dist/cli.js", "agent", "spawn", "accessibility-checker"]
    environment: [MEMOIRE_AGENT_ROLE=accessibility-checker]
    restart: on-failure:3

  orchestrator:
    build: .
    command: ["node", "dist/cli.js", "compose", "--listen"]
    depends_on: [token-engineer, component-architect, accessibility-checker]
    restart: unless-stopped

Scale bottleneck roles (the task queue is lock-based — multiple workers are safe):

bashCopy code
docker compose up --scale code-generator=3

6. Devcontainer Support

jsonCopy code
// .devcontainer/devcontainer.json
{
  "name": "Mémoire Dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "memoire-dev",
  "workspaceFolder": "/app",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" }
  },
  "forwardPorts": [4400, 4401, 9223, 9224, 9225],
  "postCreateCommand": "npm ci && npm run build",
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
    }
  },
  "remoteEnv": {
    "FIGMA_ACCESS_TOKEN": "${localEnv:FIGMA_ACCESS_TOKEN}",
    "MEMOIRE_ENV": "development"
  }
}

• remoteEnv forwards FIGMA_ACCESS_TOKEN from host shell — set once in .zshrc/.bashrc, never committed.
• VS Code auto-forwards ports in forwardPorts. The Figma plugin connects to localhost:9223 on the host; VS Code tunnels it into the container transparently.

7. Environment Variables Reference

Set in .env for local dev (never commit). Use Docker secrets or CI environment for production.

8. .memoire/project.json Docker Block

jsonCopy code
{
  "docker": {
    "enabled": true,
    "mode": "dev",
    "bridge": {
      "host": "0.0.0.0",
      "portRange": [9223, 9232],
      "fallbackHost": "host.docker.internal"
    },
    "preview": { "host": "0.0.0.0", "port": 4400 },
    "ci": {
      "headless": true,
      "noBridge": true,
      "exitOnAuditError": true,
      "failOnWarn": false
    },
    "mcp": { "shared": true, "host": "memoire.internal", "port": 4402 }
  }
}

9. Anti-Patterns

Never: Run bridge exclusively in Docker for canvas work

Every canvas op adds a port-forward round trip. Run Mémoire on the host for design-heavy sessions.

Never: Use root user in production containers

dockerfileCopy code
# Bad
CMD ["node", "dist/cli.js"]

# Good
RUN addgroup -S memoire && adduser -S memoire -G memoire
USER memoire
CMD ["node", "dist/cli.js"]

Never: Bake .memoire/ into the image

Mount it as a volume. Baking it in means every spec change requires a rebuild.

dockerfileCopy code
VOLUME ["/workspace/.memoire"]

Never: Bind preview server to 127.0.0.1 in containers

Set MEMOIRE_PREVIEW_HOST=0.0.0.0 or configure via .memoire/project.json.

Never: Hardcode FIGMA_ACCESS_TOKEN in docker-compose.yml

yamlCopy code
# Bad
environment: [FIGMA_ACCESS_TOKEN=figd_abc123...]

# Good — read from host env
environment: [FIGMA_ACCESS_TOKEN=${FIGMA_ACCESS_TOKEN}]

# Production — Docker secrets
secrets:
  figma_token: { external: true }
services:
  memoire-mcp:
    secrets: [figma_token]
    environment: [FIGMA_ACCESS_TOKEN_FILE=/run/secrets/figma_token]

Never: Skip health checks on agent workers

Dead workers stall the task queue. The heartbeat timeout is 30s. Always add health checks and restart: on-failure.