docs(06): research phase domain

Phase 6: Deployment - Standard stack identified (adapter-node, node:22-alpine) - Multi-stage Dockerfile patterns documented - Native module (better-sqlite3, sharp) considerations - SQLite WAL mode and Docker volume best practices - Environment variable configuration patterns - Health check and backup script examples
2026-02-01 13:03:07 +01:00
parent ef89b721f6
commit 94044cc49a
1 changed files with 494 additions and 0 deletions
--- a/.planning/phases/06-deployment/06-RESEARCH.md
+++ b/.planning/phases/06-deployment/06-RESEARCH.md
@@ -0,0 +1,494 @@
 # Phase 6: Deployment - Research
 **Researched:** 2026-02-01
 **Domain:** Docker containerization, SvelteKit production deployment
 **Confidence:** HIGH
 ## Summary
 This phase containerizes the TaskPlaner SvelteKit application for production deployment with Docker. The research confirms a well-established pattern for deploying SvelteKit with adapter-node: multi-stage Alpine builds, runtime environment variables, health checks via API routes, and named volumes for data persistence.
 The key technical considerations are:
 1. Switching from adapter-auto to adapter-node for production Node.js server
 2. Native module compilation (better-sqlite3, sharp) requiring npm install inside the container
 3. SQLite WAL mode working correctly with Docker named volumes (single host, same filesystem)
 4. Environment variable configuration via adapter-node's built-in support
 **Primary recommendation:** Use a two-stage Dockerfile with node:22-alpine, run npm install in the builder stage to compile native modules correctly, and configure all runtime behavior via environment variables with sensible defaults.
 ## Standard Stack
 The established libraries/tools for this domain:
 ### Core
 | Library | Version | Purpose | Why Standard |
 |---------|---------|---------|--------------|
 | @sveltejs/adapter-node | ^5.x | SvelteKit Node.js server | Official adapter, supports all env vars natively |
 | node:22-alpine | LTS | Docker base image | Small (~40MB vs 350MB+), includes 'node' user |
 ### Supporting
 | Library | Version | Purpose | When to Use |
 |---------|---------|---------|-------------|
 | dumb-init | ^1.2.5 | PID 1 init process | Optional: proper signal handling in containers |
 ### Alternatives Considered
 | Instead of | Could Use | Tradeoff |
 |------------|-----------|----------|
 | node:alpine | node:slim (debian) | Debian avoids musl issues, but 3x larger image |
 | Built-in signals | tini/dumb-init | adapter-node handles SIGTERM natively, may not need |
 **Installation:**
 ```bash
 npm install -D @sveltejs/adapter-node
 ```
 ## Architecture Patterns
 ### Recommended Project Structure
 ```
 project-root/
 ├── Dockerfile              # Multi-stage build
 ├── docker-compose.yml      # Single-service compose
 ├── .dockerignore           # Build context exclusions
 ├── .env.example            # Environment variable template
 ├── backup.sh               # Volume backup script
 ├── build/                  # (gitignored) Production build output
 └── data/                   # (gitignored) Local dev data
    ├── db/
    │   └── taskplaner.db
    └── uploads/
        ├── originals/
        └── thumbnails/
 ```
 ### Pattern 1: Multi-Stage Dockerfile
 **What:** Separate build dependencies from runtime to minimize image size
 **When to use:** Always for production Docker deployments
 **Example:**
 ```dockerfile
 # Source: https://gist.github.com/aradalvand/04b2cad14b00e5ffe8ec96a3afbb34fb
 # Stage 1: Build
 FROM node:22-alpine AS builder
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci
 COPY . .
 RUN npm run build
 RUN npm prune --production
 # Stage 2: Production
 FROM node:22-alpine
 WORKDIR /app
 COPY --from=builder /app/build build/
 COPY --from=builder /app/node_modules node_modules/
 COPY package.json .
 USER node
 EXPOSE 3000
 ENV NODE_ENV=production
 CMD ["node", "build"]
 ```
 ### Pattern 2: SvelteKit Health Check Endpoint
 **What:** API route returning 200 for container health checks
 **When to use:** Docker HEALTHCHECK, Kubernetes probes, load balancer checks
 **Example:**
 ```typescript
 // src/routes/health/+server.ts
 // Source: https://svelte.dev/docs/kit/routing
 import type { RequestHandler } from './$types';
 export const GET: RequestHandler = async () => {
  return new Response('ok', { status: 200 });
 };
 ```
 ### Pattern 3: Runtime Environment Configuration
 **What:** Configure app behavior via environment variables at runtime
 **When to use:** All deployments - allows same image for different environments
 **Example:**
 ```bash
 # adapter-node reads these automatically
 # Source: https://svelte.dev/docs/kit/adapter-node
 PORT=3000
 HOST=0.0.0.0
 ORIGIN=http://localhost:3000
 BODY_SIZE_LIMIT=10M
 # Reverse proxy headers (when behind nginx/traefik)
 PROTOCOL_HEADER=x-forwarded-proto
 HOST_HEADER=x-forwarded-host
 ADDRESS_HEADER=x-forwarded-for
 XFF_DEPTH=1
 ```
 ### Pattern 4: Named Volume for Data Persistence
 **What:** Docker-managed volume mounted to container data directory
 **When to use:** Any stateful data (database, uploads)
 **Example:**
 ```yaml
 # docker-compose.yml
 services:
  app:
    volumes:
      - taskplaner_data:/data
 volumes:
  taskplaner_data:
 ```
 ### Anti-Patterns to Avoid
 - **Copying node_modules from host:** Native modules compiled for host OS won't work in Alpine container. Always run npm install inside Dockerfile.
 - **Bind mounts for production data:** Use named volumes for better portability and Docker management.
 - **Running as root:** Security risk. Use `USER node` in production stage.
 - **Hardcoded configuration:** Makes the image environment-specific. Use env vars.
 - **Installing dev dependencies in production:** Bloats image. Use `npm prune --production` or `npm ci --only=production`.
 ## Don't Hand-Roll
 Problems that look simple but have existing solutions:
 | Problem | Don't Build | Use Instead | Why |
 |---------|-------------|-------------|-----|
 | Environment variables | Custom config parser | adapter-node env vars | Built-in, documented, handles edge cases |
 | Graceful shutdown | Signal handlers | adapter-node SHUTDOWN_TIMEOUT | Built-in, handles request draining |
 | Health checks | Complex readiness probe | Simple /health route | Docker just needs HTTP 200 |
 | Process management | supervisor/pm2 | Docker restart policies | Container-native, simpler |
 | Logging to files | File appenders | stdout/stderr | Docker captures, aggregators consume |
 **Key insight:** adapter-node provides most production concerns out of the box. Don't add middleware or wrappers - use its environment variables.
 ## Common Pitfalls
 ### Pitfall 1: Native Module Architecture Mismatch
 **What goes wrong:** App crashes with "Cannot find module" or "symbol not found" errors for better-sqlite3 or sharp
 **Why it happens:** node_modules from macOS/Windows host copied to Linux container
 **How to avoid:**
 1. Add `node_modules` to `.dockerignore`
 2. Run `npm ci` inside Dockerfile builder stage
 3. For sharp on Alpine, npm will download musl-compatible prebuilt binaries automatically (sharp >= 0.33)
 **Warning signs:** Errors mentioning `linuxmusl`, `glibc`, or module loading failures
 ### Pitfall 2: SQLite WAL File Permissions
 **What goes wrong:** "database is locked" or "read-only" errors
 **Why it happens:** SQLite creates `-wal` and `-shm` files with same permissions as main db file. If user/group mismatch, can't access.
 **How to avoid:**
 1. Run container as `node` user (uid 1000)
 2. Use named volumes (Docker manages permissions)
 3. Ensure app creates data directories with correct ownership
 **Warning signs:** Works first time, fails on restart; "attempt to write a readonly database"
 ### Pitfall 3: ORIGIN Environment Variable Missing
 **What goes wrong:** CSRF errors on form submissions: "Cross-site POST form submissions are forbidden"
 **Why it happens:** SvelteKit validates Origin header against expected origin
 **How to avoid:** Always set `ORIGIN` env var to match how users access the app
 **Warning signs:** Forms work in development but fail in production
 ### Pitfall 4: Missing Reverse Proxy Headers
 **What goes wrong:** App sees internal Docker IPs instead of real client IPs; redirects go to wrong protocol/host
 **Why it happens:** Default behavior ignores X-Forwarded-* headers for security
 **How to avoid:** Set `PROTOCOL_HEADER`, `HOST_HEADER`, `ADDRESS_HEADER` only when behind trusted proxy
 **Warning signs:** Logs show 172.x.x.x instead of real IPs; HTTPS redirects to HTTP
 ### Pitfall 5: Volume Data Not Persisting
 **What goes wrong:** Data disappears after container restart
 **Why it happens:** Using anonymous volumes or not declaring volume in compose file
 **How to avoid:**
 1. Declare named volume in `volumes:` section of docker-compose.yml
 2. Use consistent mount path in container
 3. Don't use `docker-compose down -v` unless intentionally deleting data
 **Warning signs:** Fresh database on each restart
 ### Pitfall 6: Health Check Curl Not Installed
 **What goes wrong:** Container marked unhealthy despite app running
 **Why it happens:** Alpine doesn't include curl by default
 **How to avoid:** Use wget (included in Alpine) or node for health checks
 **Warning signs:** Container in "unhealthy" state but app responds normally
 ## Code Examples
 Verified patterns from official sources:
 ### svelte.config.js with adapter-node
 ```javascript
 // Source: https://svelte.dev/docs/kit/adapter-node
 import adapter from '@sveltejs/adapter-node';
 /** @type {import('@sveltejs/kit').Config} */
 const config = {
  kit: {
    adapter: adapter({
      out: 'build',
      precompress: true,
      envPrefix: 'TASKPLANER_'
    })
  }
 };
 export default config;
 ```
 ### Complete Dockerfile
 ```dockerfile
 # Stage 1: Build
 FROM node:22-alpine AS builder
 WORKDIR /app
 # Copy package files first for layer caching
 COPY package*.json ./
 RUN npm ci
 # Copy source and build
 COPY . .
 RUN npm run build
 # Remove dev dependencies
 RUN npm prune --production
 # Stage 2: Production
 FROM node:22-alpine
 # Create app directory
 WORKDIR /app
 # Copy built app and production dependencies
 COPY --from=builder /app/build build/
 COPY --from=builder /app/node_modules node_modules/
 COPY package.json .
 # Create data directory and set ownership
 RUN mkdir -p /data/db /data/uploads/originals /data/uploads/thumbnails \
    && chown -R node:node /data /app
 # Switch to non-root user
 USER node
 # Environment defaults
 ENV NODE_ENV=production
 ENV PORT=3000
 ENV TASKPLANER_DATA_DIR=/data
 EXPOSE 3000
 # Health check using wget (available in Alpine)
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
 CMD ["node", "build"]
 ```
 ### docker-compose.yml
 ```yaml
 # Source: https://docs.docker.com/reference/compose-file/
 services:
  taskplaner:
    build: .
    container_name: taskplaner
    restart: unless-stopped
    ports:
      - "${PORT:-3000}:3000"
    volumes:
      - taskplaner_data:/data
    environment:
      - NODE_ENV=production
      - PORT=3000
      - TASKPLANER_DATA_DIR=/data
      - ORIGIN=${ORIGIN:-http://localhost:3000}
      # Uncomment when behind reverse proxy:
      # - PROTOCOL_HEADER=x-forwarded-proto
      # - HOST_HEADER=x-forwarded-host
      # - ADDRESS_HEADER=x-forwarded-for
      # - XFF_DEPTH=1
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
 volumes:
  taskplaner_data:
 ```
 ### .dockerignore
 ```
 # Source: https://snyk.io/blog/10-best-practices-to-containerize-nodejs-web-applications-with-docker/
 # Dependencies - rebuild inside container
 node_modules
 # Build outputs
 build
 .svelte-kit
 # Development files
 .git
 .gitignore
 .env
 .env.*
 *.md
 *.log
 # IDE/Editor
 .vscode
 .idea
 # Docker files (prevent recursion)
 Dockerfile
 .dockerignore
 docker-compose*.yml
 # Test files
 *.test.ts
 *.spec.ts
 coverage
 ```
 ### .env.example
 ```bash
 # TaskPlaner Environment Configuration
 # Copy to .env and customize for your deployment
 # === Server Configuration ===
 # Port the server listens on (inside container, map with docker-compose ports)
 PORT=3000
 # === Data Storage ===
 # Directory for database and uploads (must match volume mount)
 TASKPLANER_DATA_DIR=/data
 # === Production URL ===
 # Required: The full URL where users access the app
 # Used for CSRF validation and generating absolute URLs
 ORIGIN=http://localhost:3000
 # === Reverse Proxy (uncomment when behind nginx/traefik) ===
 # PROTOCOL_HEADER=x-forwarded-proto
 # HOST_HEADER=x-forwarded-host
 # ADDRESS_HEADER=x-forwarded-for
 # XFF_DEPTH=1
 # === Request Limits ===
 # Maximum request body size (default: 512kb)
 # Supports K, M, G suffixes
 BODY_SIZE_LIMIT=10M
 # === Logging ===
 # Log level: debug, info, warn, error
 # TASKPLANER_LOG_LEVEL=info
 ```
 ### backup.sh
 ```bash
 #!/bin/bash
 # Source: https://docs.docker.com/engine/storage/volumes/
 # Backup TaskPlaner data volume
 set -e
 BACKUP_DIR="${BACKUP_DIR:-./backups}"
 CONTAINER_NAME="${CONTAINER_NAME:-taskplaner}"
 VOLUME_NAME="${VOLUME_NAME:-taskplaner_data}"
 TIMESTAMP=$(date +%Y%m%d_%H%M%S)
 BACKUP_FILE="${BACKUP_DIR}/taskplaner_backup_${TIMESTAMP}.tar.gz"
 # Create backup directory if needed
 mkdir -p "$BACKUP_DIR"
 echo "Backing up TaskPlaner data..."
 echo "Volume: $VOLUME_NAME"
 echo "Output: $BACKUP_FILE"
 # Create backup using temporary container
 docker run --rm \
  -v "${VOLUME_NAME}:/data:ro" \
  -v "$(pwd)/${BACKUP_DIR}:/backup" \
  alpine:latest \
  tar czf "/backup/taskplaner_backup_${TIMESTAMP}.tar.gz" -C /data .
 echo "Backup complete: $BACKUP_FILE"
 echo "Size: $(du -h "$BACKUP_FILE" | cut -f1)"
 ```
 ### Health Check Endpoint
 ```typescript
 // src/routes/health/+server.ts
 import type { RequestHandler } from './$types';
 import { db } from '$lib/server/db';
 import { entries } from '$lib/server/db/schema';
 export const GET: RequestHandler = async () => {
  try {
    // Verify database connectivity
    db.select().from(entries).limit(1).all();
    return new Response('ok', {
      status: 200,
      headers: { 'Content-Type': 'text/plain' }
    });
  } catch (error) {
    return new Response('unhealthy', {
      status: 503,
      headers: { 'Content-Type': 'text/plain' }
    });
  }
 };
 ```
 ## State of the Art
 | Old Approach | Current Approach | When Changed | Impact |
 |--------------|------------------|--------------|--------|
 | adapter-auto | adapter-node for Docker | SvelteKit 2.x | Explicit Node.js server, env var support |
 | COPY node_modules | npm ci in Dockerfile | Always best practice | Correct native module binaries |
 | curl in healthcheck | wget (Alpine native) | Alpine best practice | No extra packages needed |
 | Root user | node:node (uid 1000) | Security standard | Reduced attack surface |
 | JSON config files | Environment variables | 12-factor app | Same image, different configs |
 **Deprecated/outdated:**
 - `adapter-node@1.x`: Use 5.x for SvelteKit 2 compatibility
 - Installing sharp with `--platform` flags: sharp 0.33+ auto-detects musl
 - Manual signal handling: adapter-node handles SIGTERM/SIGINT natively
 ## Open Questions
 Things that couldn't be fully resolved:
 1. **JSON logging integration**
   - What we know: Pino is the standard for JSON logging in Node.js
   - What's unclear: Pino has bundling issues with SvelteKit production builds (Worker Threads)
   - Recommendation: Defer structured logging to a future enhancement. Console.log output goes to stdout and Docker captures it. Can add pino later if needed.
 2. **Drizzle migrations in production**
   - What we know: Currently using `drizzle-kit push` for development
   - What's unclear: Best practice for running migrations in Docker container
   - Recommendation: For single-user app, continue using push mode via db initialization in hooks.server.ts. Schema is simple enough. Could add migration script later if needed.
 3. **Specific extended environment variables**
   - What we know: CONTEXT.md says "extended config scope" beyond PORT/DATA_DIR
   - What's unclear: Exactly which additional env vars users need
   - Recommendation: Start with essentials (PORT, DATA_DIR, ORIGIN, BODY_SIZE_LIMIT, log level). Add more based on user feedback.
 ## Sources
 ### Primary (HIGH confidence)
 - [SvelteKit adapter-node documentation](https://svelte.dev/docs/kit/adapter-node) - Environment variables, configuration, graceful shutdown
 - [Docker official volumes documentation](https://docs.docker.com/engine/storage/volumes/) - Named volumes, backup procedures
 - [Docker Compose services documentation](https://docs.docker.com/reference/compose-file/services/) - Health checks, configuration
 - [Sharp installation documentation](https://sharp.pixelplumbing.com/install/) - Cross-platform, musl support
 ### Secondary (MEDIUM confidence)
 - [SvelteKit Dockerfile gist by aradalvand](https://gist.github.com/aradalvand/04b2cad14b00e5ffe8ec96a3afbb34fb) - Multi-stage build pattern
 - [Snyk Node.js Docker best practices](https://snyk.io/blog/10-best-practices-to-containerize-nodejs-web-applications-with-docker/) - Security, .dockerignore
 - [Node.js docker-node best practices](https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md) - Non-root user, Alpine considerations
 ### Tertiary (LOW confidence)
 - Various Medium/DEV articles on SvelteKit Docker deployment - General patterns confirmed by official docs
 ## Metadata
 **Confidence breakdown:**
 - Standard stack: HIGH - adapter-node is official, well-documented
 - Architecture: HIGH - Multi-stage builds, named volumes are established Docker patterns
 - Pitfalls: HIGH - Native modules, SQLite permissions are well-known issues with documented solutions
 - Code examples: HIGH - Based on official documentation
 **Research date:** 2026-02-01
 **Valid until:** 2026-03-01 (30 days - Docker/SvelteKit patterns are stable)