Improve Coolify deploy build caching

README.md

@@ -81,10 +81,16 @@ On container startup, the app applies Drizzle migrations automatically before la
 The app stores SQLite data in Docker volume `fiscal_sqlite_data` (mounted to `/app/data`) and workflow world data in Postgres volume `workflow_postgres_data`.
 Container startup runs:
 1. `workflow-postgres-setup` (idempotent Workflow world bootstrap)
-2. Drizzle migrations for SQLite app tables
+2. Programmatic Drizzle migrations for SQLite app tables
 3. Next.js server boot
 
 Docker images use Bun (`oven/bun:1.3.5-alpine`) for build and runtime.
+Docker builds use BuildKit cache mounts for Bun downloads and `.next/cache`, so repeated server-side builds can reuse dependency and Next/Turbopack caches on the same builder.
+
+Optional runtime toggles:
+
+- `RUN_WORKFLOW_SETUP_ON_START=true` keeps `workflow-postgres-setup` enabled at container boot.
+- `RUN_DB_MIGRATIONS_ON_START=true` keeps SQLite migrations enabled at container boot.
 
 ## Coolify deployment
 
@@ -107,6 +113,9 @@ Operational constraints for Coolify:
 - Ensure both named volumes are persisted (`fiscal_sqlite_data`, `workflow_postgres_data`).
 - Keep `WORKFLOW_POSTGRES_URL` explicit so Workflow does not fall back to `DATABASE_URL` (SQLite).
 - The app `/api/health` probes Workflow backend connectivity and returns non-200 when Workflow world is unavailable.
+- Keep `Include Source Commit in Build` disabled so Docker layer cache stays reusable between commits.
+- Keep Docker cleanup threshold-based rather than aggressive, otherwise Coolify will discard build cache.
+- Keep repeated builds pinned to the same builder/server when possible so Docker layer cache and BuildKit cache mounts remain warm.
 
 Emergency rollback path:
 
@@ -140,6 +149,8 @@ WORKFLOW_TARGET_WORLD=local
 WORKFLOW_POSTGRES_URL=postgres://workflow:workflow@workflow-postgres:5432/workflow
 WORKFLOW_POSTGRES_WORKER_CONCURRENCY=10
 WORKFLOW_POSTGRES_JOB_PREFIX=fiscal_
+RUN_WORKFLOW_SETUP_ON_START=true
+RUN_DB_MIGRATIONS_ON_START=true
 
 # Optional local-world fallback
 WORKFLOW_LOCAL_DATA_DIR=.workflow-data