xtablo-source/docs/DOCKER_BUILD.md

Docker Build Guide for XTablo API

Overview

This Dockerfile is configured for a pnpm monorepo setup. It must be built from the repository root, not from the apps/api directory.

Build Commands

Production Build (default)

cd /path/to/xtablo-source
docker build -f apps/api/Dockerfile -t xtablo-api:production .

Staging Build

cd /path/to/xtablo-source
docker build -f apps/api/Dockerfile --target staging -t xtablo-api:staging .

Build Specific Stages (for testing)

# Test dependencies stage
docker build -f apps/api/Dockerfile --target deps -t xtablo-api:deps .

# Test build stage
docker build -f apps/api/Dockerfile --target build -t xtablo-api:build .

# Test production dependencies
docker build -f apps/api/Dockerfile --target prod-deps -t xtablo-api:prod-deps .

Running the Container

Basic Run

docker run -p 8080:8080 \
  -e SUPABASE_URL=your_url \
  -e SUPABASE_SERVICE_ROLE_KEY=your_key \
  -e STREAM_API_KEY=your_key \
  -e STREAM_SECRET=your_secret \
  xtablo-api:production

With Environment File

docker run -p 8080:8080 --env-file .env.production xtablo-api:production

Docker Compose Example

version: "3.8"

services:
  api:
    build:
      context: .
      dockerfile: apps/api/Dockerfile
      target: production
    ports:
      - "8080:8080"
    environment:
      - NODE_ENV=production
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_SERVICE_ROLE_KEY=${SUPABASE_SERVICE_ROLE_KEY}
      - STREAM_API_KEY=${STREAM_API_KEY}
      - STREAM_SECRET=${STREAM_SECRET}
    restart: unless-stopped

Image Structure

• Base Image: node:18-alpine
• Package Manager: pnpm (via corepack)
• Working Directory: /app/apps/api
• User: nodejs (non-root, UID 1001)
• Port: 8080

Multi-Stage Build Details

1. base: Sets up Node.js, pnpm, copies workspace files
2. deps: Installs all dependencies (including dev dependencies)
3. build: Compiles TypeScript to JavaScript
4. prod-deps: Installs only production dependencies
5. staging: Creates staging image with production dependencies
6. production: Creates production image (default target)

Important Notes

• ⚠️ Always build from the monorepo root, not from apps/api
• Environment variables should be injected at runtime, not baked into the image
• The image uses pnpm's workspace features with proper symlink structure
• pnpm version: 10.19.0 (via corepack)
• Node version: 18.20.8
• The .dockerignore file excludes local dist and node_modules to ensure clean builds

Verification Commands

Check image size

docker images xtablo-api:production

Inspect image

docker run --rm --entrypoint sh xtablo-api:production -c "ls -la /app/apps/api"

Test pnpm installation

docker run --rm --entrypoint sh xtablo-api:production -c "pnpm --version"

Check built files

docker run --rm --entrypoint sh xtablo-api:production -c "ls -la /app/apps/api/dist"

Troubleshooting

"pnpm-lock.yaml: not found"

• Make sure you're building from the repository root
• Use -f apps/api/Dockerfile to specify the Dockerfile location

"Permission denied"

• The container runs as a non-root user (nodejs)
• Ensure file permissions are set correctly (handled by the Dockerfile)

Dependencies not found

• The monorepo structure requires the entire workspace for dependency resolution
• Make sure pnpm-workspace.yaml is present in the root

CI/CD Integration

For Cloud Build or similar CI/CD systems, update your build configuration:

steps:
  - name: "gcr.io/cloud-builders/docker"
    args:
      - "build"
      - "-f"
      - "apps/api/Dockerfile"
      - "-t"
      - "gcr.io/$PROJECT_ID/xtablo-api:$COMMIT_SHA"
      - "-t"
      - "gcr.io/$PROJECT_ID/xtablo-api:latest"
      - "."
    dir: "." # Build from root, not apps/api