163 lines
3.9 KiB
Markdown
163 lines
3.9 KiB
Markdown
# 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
|
|
```
|