331 lines
9 KiB
Markdown
331 lines
9 KiB
Markdown
# Docker & Docker Compose Best Practices — MeshiTrack
|
|
|
|
> Instruction file for containerization and local development environment.
|
|
|
|
## Docker Compose Architecture
|
|
|
|
```
|
|
┌─────────────┐ ┌───────────────┐ ┌──────────┐
|
|
│ web:3000 │────→│ api:3001 │────→│ mongodb │
|
|
│ (Next.js) │ │ (NestJS) │ │ :27017 │
|
|
└─────────────┘ └───────┬───────┘ └──────────┘
|
|
│
|
|
┌───────▼───────┐
|
|
│ keycloak │
|
|
│ :8080 │
|
|
└───────────────┘
|
|
```
|
|
|
|
## docker-compose.yml
|
|
|
|
```yaml
|
|
version: '3.8'
|
|
|
|
services:
|
|
mongodb:
|
|
image: mongo:7
|
|
container_name: meshitrack-mongodb
|
|
restart: unless-stopped
|
|
ports:
|
|
- '27017:27017'
|
|
environment:
|
|
MONGO_INITDB_ROOT_USERNAME: meshitrack
|
|
MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD:-devpassword}
|
|
MONGO_INITDB_DATABASE: meshitrack
|
|
volumes:
|
|
- mongo-data:/data/db
|
|
- ./mongo/init-replica.js:/docker-entrypoint-initdb.d/init-replica.js:ro
|
|
command: ['--replSet', 'rs0', '--bind_ip_all']
|
|
healthcheck:
|
|
test: ['CMD', 'mongosh', '--eval', "db.adminCommand('ping')"]
|
|
interval: 10s
|
|
timeout: 5s
|
|
retries: 5
|
|
|
|
keycloak:
|
|
image: quay.io/keycloak/keycloak:24.0
|
|
container_name: meshitrack-keycloak
|
|
restart: unless-stopped
|
|
ports:
|
|
- '8080:8080'
|
|
environment:
|
|
KC_DB: dev-mem
|
|
KEYCLOAK_ADMIN: admin
|
|
KEYCLOAK_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD:-admin}
|
|
command: start-dev --import-realm
|
|
volumes:
|
|
- ./keycloak/realm-export.json:/opt/keycloak/data/import/realm-export.json:ro
|
|
healthcheck:
|
|
test:
|
|
[
|
|
'CMD-SHELL',
|
|
"exec 3<>/dev/tcp/127.0.0.1/8080; echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3; cat <&3 | grep -q '200'",
|
|
]
|
|
interval: 15s
|
|
timeout: 5s
|
|
retries: 10
|
|
|
|
api:
|
|
build:
|
|
context: ..
|
|
dockerfile: docker/Dockerfile.api
|
|
target: development
|
|
container_name: meshitrack-api
|
|
restart: unless-stopped
|
|
ports:
|
|
- '3001:3001'
|
|
depends_on:
|
|
mongodb:
|
|
condition: service_healthy
|
|
keycloak:
|
|
condition: service_healthy
|
|
environment:
|
|
NODE_ENV: development
|
|
PORT: 3001
|
|
MONGODB_URI: mongodb://meshitrack:${MONGO_PASSWORD:-devpassword}@mongodb:27017/meshitrack?authSource=admin&replicaSet=rs0
|
|
KEYCLOAK_URL: http://keycloak:8080
|
|
KEYCLOAK_REALM: meshitrack
|
|
KEYCLOAK_CLIENT_ID: meshitrack-api
|
|
volumes:
|
|
- ../packages/api/src:/app/packages/api/src:ro # Hot reload
|
|
- ../packages/shared/src:/app/packages/shared/src:ro
|
|
|
|
web:
|
|
build:
|
|
context: ..
|
|
dockerfile: docker/Dockerfile.web
|
|
target: development
|
|
container_name: meshitrack-web
|
|
restart: unless-stopped
|
|
ports:
|
|
- '3000:3000'
|
|
depends_on:
|
|
- api
|
|
environment:
|
|
NODE_ENV: development
|
|
NEXT_PUBLIC_API_URL: http://localhost:3001/api/v1
|
|
NEXT_PUBLIC_KEYCLOAK_URL: http://localhost:8080
|
|
NEXT_PUBLIC_KEYCLOAK_REALM: meshitrack
|
|
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID: meshitrack-web
|
|
volumes:
|
|
- ../packages/web/src:/app/packages/web/src:ro
|
|
|
|
# Dev-only services
|
|
mongo-express:
|
|
image: mongo-express
|
|
container_name: meshitrack-mongo-express
|
|
ports:
|
|
- '8081:8081'
|
|
depends_on:
|
|
mongodb:
|
|
condition: service_healthy
|
|
environment:
|
|
ME_CONFIG_MONGODB_ADMINUSERNAME: meshitrack
|
|
ME_CONFIG_MONGODB_ADMINPASSWORD: ${MONGO_PASSWORD:-devpassword}
|
|
ME_CONFIG_MONGODB_URL: mongodb://meshitrack:${MONGO_PASSWORD:-devpassword}@mongodb:27017/
|
|
profiles:
|
|
- dev
|
|
|
|
volumes:
|
|
mongo-data:
|
|
```
|
|
|
|
## Dockerfile Best Practices
|
|
|
|
### Multi-stage builds
|
|
|
|
```dockerfile
|
|
# docker/Dockerfile.api
|
|
|
|
# ---- Base ----
|
|
FROM node:20-alpine AS base
|
|
WORKDIR /app
|
|
RUN corepack enable
|
|
|
|
# ---- Dependencies ----
|
|
FROM base AS dependencies
|
|
COPY package.json package-lock.json ./
|
|
COPY packages/api/package.json ./packages/api/
|
|
COPY packages/shared/package.json ./packages/shared/
|
|
RUN npm ci --workspace=packages/shared --workspace=packages/api
|
|
|
|
# ---- Build ----
|
|
FROM dependencies AS build
|
|
COPY packages/shared/ ./packages/shared/
|
|
COPY packages/api/ ./packages/api/
|
|
COPY tsconfig.base.json ./
|
|
RUN npm run build --workspace=packages/shared
|
|
RUN npm run build --workspace=packages/api
|
|
|
|
# ---- Production ----
|
|
FROM base AS production
|
|
COPY --from=build /app/packages/api/dist ./packages/api/dist
|
|
COPY --from=build /app/packages/shared/dist ./packages/shared/dist
|
|
COPY --from=build /app/node_modules ./node_modules
|
|
COPY --from=build /app/packages/api/package.json ./packages/api/
|
|
COPY --from=build /app/packages/shared/package.json ./packages/shared/
|
|
COPY --from=build /app/package.json ./
|
|
|
|
ENV NODE_ENV=production
|
|
EXPOSE 3001
|
|
CMD ["node", "packages/api/dist/main.js"]
|
|
|
|
# ---- Development ----
|
|
FROM dependencies AS development
|
|
COPY packages/shared/ ./packages/shared/
|
|
COPY packages/api/ ./packages/api/
|
|
COPY tsconfig.base.json ./
|
|
RUN npm run build --workspace=packages/shared
|
|
EXPOSE 3001
|
|
CMD ["npm", "run", "dev", "--workspace=packages/api"]
|
|
```
|
|
|
|
### Key principles
|
|
|
|
1. **Layer ordering**: Copy `package.json` files first, then `npm ci`, then source code. This ensures dependency layers are cached unless `package.json` changes.
|
|
|
|
2. **Multi-stage targets**: Use `--target=development` for dev (with hot reload), `--target=production` for deploy (minimal image).
|
|
|
|
3. **Alpine images**: Use `node:20-alpine` for smaller images (~180MB vs ~1GB).
|
|
|
|
4. **.dockerignore**: Always include to prevent sending unnecessary files to the build context:
|
|
```
|
|
node_modules
|
|
.git
|
|
.next
|
|
dist
|
|
*.md
|
|
docs/
|
|
.env*
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
### .env.example (committed to repo)
|
|
|
|
```env
|
|
# MongoDB
|
|
MONGO_PASSWORD=devpassword
|
|
|
|
# Keycloak
|
|
KC_ADMIN_PASSWORD=admin
|
|
|
|
# API
|
|
API_PORT=3001
|
|
MONGODB_URI=mongodb://meshitrack:devpassword@localhost:27017/meshitrack?authSource=admin
|
|
|
|
# Web
|
|
NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1
|
|
NEXT_PUBLIC_KEYCLOAK_URL=http://localhost:8080
|
|
NEXT_PUBLIC_KEYCLOAK_REALM=meshitrack
|
|
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=meshitrack-web
|
|
|
|
# LLM (Phase 6)
|
|
LLM_PROVIDER_TYPE=noop
|
|
# OPENAI_API_KEY=sk-...
|
|
# LLM_MONTHLY_BUDGET_USD=20.00
|
|
```
|
|
|
|
### .env (gitignored, developer-specific)
|
|
|
|
Never commit `.env`. Each developer copies `.env.example` to `.env` and fills in secrets.
|
|
|
|
### In Docker Compose, use variable substitution
|
|
|
|
```yaml
|
|
environment:
|
|
MONGO_PASSWORD: ${MONGO_PASSWORD:-devpassword} # Fallback for dev
|
|
```
|
|
|
|
## Health Checks
|
|
|
|
Every service should have a health check so `depends_on: condition: service_healthy` works:
|
|
|
|
```yaml
|
|
# MongoDB
|
|
healthcheck:
|
|
test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
|
|
interval: 10s
|
|
timeout: 5s
|
|
retries: 5
|
|
|
|
# API (requires /api/v1/health endpoint in code)
|
|
healthcheck:
|
|
test: ["CMD", "wget", "-qO-", "http://localhost:3001/api/v1/health"]
|
|
interval: 10s
|
|
timeout: 5s
|
|
retries: 5
|
|
```
|
|
|
|
## Volume Management
|
|
|
|
### Named volumes for persistence
|
|
|
|
```yaml
|
|
volumes:
|
|
mongo-data: # Survives container recreations
|
|
```
|
|
|
|
### Bind mounts for hot reload in development
|
|
|
|
```yaml
|
|
volumes:
|
|
- ../packages/api/src:/app/packages/api/src:ro # Read-only for safety
|
|
```
|
|
|
|
Use `:ro` (read-only) for source code mounts — the container shouldn't modify your source files.
|
|
|
|
## MongoDB Replica Set for Transactions
|
|
|
|
MongoDB transactions require a replica set. For local development, initialize a single-node replica:
|
|
|
|
```javascript
|
|
// docker/mongo/init-replica.js
|
|
// This runs on first start via /docker-entrypoint-initdb.d/
|
|
try {
|
|
rs.initiate({ _id: 'rs0', members: [{ _id: 0, host: 'mongodb:27017' }] });
|
|
} catch (e) {
|
|
if (e.codeName !== 'AlreadyInitialized') throw e;
|
|
}
|
|
```
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
# Start all services
|
|
docker compose up -d
|
|
|
|
# Start with dev tools (mongo-express)
|
|
docker compose --profile dev up -d
|
|
|
|
# View logs
|
|
docker compose logs -f api
|
|
|
|
# Rebuild after dependency changes
|
|
docker compose build --no-cache api
|
|
|
|
# Reset database
|
|
docker compose down -v # -v removes volumes
|
|
docker compose up -d
|
|
|
|
# Enter a running container
|
|
docker compose exec api sh
|
|
docker compose exec mongodb mongosh -u meshitrack -p devpassword
|
|
|
|
# Backup MongoDB
|
|
docker compose exec mongodb mongodump --uri="mongodb://meshitrack:devpassword@localhost:27017/meshitrack?authSource=admin" --archive | gzip > backup-$(date +%Y%m%d).gz
|
|
```
|
|
|
|
## Production Considerations
|
|
|
|
- Use separate `docker-compose.prod.yml` with:
|
|
- `target: production` for API and web builds
|
|
- No bind mounts
|
|
- No dev services (mongo-express)
|
|
- Proper resource limits
|
|
- External volumes for MongoDB data
|
|
- Log drivers configured
|
|
- Consider adding:
|
|
- **Traefik** or **nginx** as reverse proxy with TLS
|
|
- **Watchtower** for auto-updating container images
|
|
- Automated backup cron container for MongoDB
|