Production Deployment Guide

CopyPatch v2 deploys directly inside your application server. Because the API route runs at /__copypatch/api/v2 on the same HTTPS origin, no secondary services, extra open ports, or CORS reverse proxies are needed.

1. Storage Adapter Configuration

Option A: SQLite (Single Node / VPS / Container)

SQLite is fast, transactional, and zero-maintenance for single-server setups:

lib/copypatch.ts (SQLite)

import { createSQLitePersistence } from '@copypatch/storage-sqlite';

const persistence = createSQLitePersistence({
  filename: process.env.COPYPATCH_SQLITE_PATH ?? './data/copypatch.sqlite',
  busyTimeoutMs: 5_000,
});

// Run idempotent schema migrations on server start
await persistence.migrate();

Persistent Volume: Mount a persistent storage directory in Docker/Kubernetes (e.g. /data) to preserve the SQLite database and its WAL sidecar files (.sqlite-wal and .sqlite-shm).
WAL Mode: @copypatch/storage-sqlite automatically enables WAL (Write-Ahead Logging) mode and sets busy retry timeouts for high concurrency.

Option B: PostgreSQL (Distributed / Clusters / Serverless)

PostgreSQL synchronizes copy, drafts, and rate-limits across multiple app instances:

lib/copypatch.ts (PostgreSQL)

import { Pool } from 'pg';
import { createPostgresPersistence } from '@copypatch/storage-postgres';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL!,
  max: 10,
  idleTimeoutMillis: 30000,
  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: true } : false,
});

const persistence = createPostgresPersistence({
  pool,
  schema: 'copypatch',
});

// Run idempotent schema migrations (protected by PostgreSQL advisory locks)
await persistence.migrate();

Advisory Locks: Schema migrations use PostgreSQL transaction advisory locks to guarantee that concurrent container rollouts never perform duplicate migrations.
Connection Pooling: Pass an existing pg.Pool to share database connections with your host application.

2. Environment Variables Reference

Variable	Required	Description
`COPYPATCH_PASSPHRASE_HASH`	Yes (if using built-in auth)	Argon2id encoded password hash generated with `copypatch hash --stdin`.
`COPYPATCH_SQLITE_PATH`	No (SQLite only)	Absolute or relative filesystem path to the SQLite database file (default: `./data/copypatch.sqlite`).
`DATABASE_URL`	Yes (Postgres only)	PostgreSQL connection URI (e.g. `postgres://user:pass@host:5432/dbname`).
`NODE_ENV`	Recommended	Set to `production` to enforce secure cookie flags and HTTPS policies.

3. Health Check & Monitoring

CopyPatch includes a lightweight health check endpoint at /__copypatch/api/v2/health:

Health Check

// Check health endpoint
// curl -i https://yoursite.com/__copypatch/api/v2/health
// HTTP/1.1 200 OK
// Content-Type: application/json
{
  "status": "ok",
  "version": "2.0.0",
  "storage": "ready"
}

4. Production Deployment Checklist

HTTPS Enforcement: Serve your application over HTTPS so that Secure and __Host- session cookies function properly.
Run Migrations at Startup: Call await persistence.migrate() in your server initialization code before accepting traffic.
No Static SSG for Editing: Ensure your hosting provider executes Node.js or serverless functions for the API route.
Regular Backups: Include your SQLite volume or PostgreSQL database in your scheduled automated backup routine.