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)

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

### Staging Build

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

### Build Specific Stages (for testing)

```bash
# 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

```bash
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

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

## Docker Compose Example

```yaml
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

```bash
docker images xtablo-api:production
```

### Inspect image

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

### Test pnpm installation

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

### Check built files

```bash
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:

```yaml
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
```