chore: streamline compose migrations (#68)

* chore: address QA findings

* chore: pin compose migration image

Author: xernobyl

.env.example

@@ -10,6 +10,10 @@ API_KEY=your-secret-api-key-here
 # Postgres host port for docker-compose (optional). Default: 5432. Override only if 5432 is in use (e.g. POSTGRES_PORT=5433); keep DATABASE_URL in sync.
 # POSTGRES_PORT=5432
 
+# Hub image tag for docker-compose migration container (optional). Default: 0.2.0.
+# Use a pinned release tag, not latest, so migration tooling is reproducible.
+# HUB_IMAGE_TAG=0.2.0
+
 # Database connection URL (optional). Port must match POSTGRES_PORT when you override it.
 # Default: postgres://postgres:postgres@localhost:5432/test_db?sslmode=disable
 # Format: postgres://username:password@host:port/database?sslmode=disable
@@ -95,7 +99,7 @@ WEBHOOK_MAX_COUNT=500
 # GOOGLE_APPLICATION_CREDENTIALS=    (optional; for google-gemini when outside Google Cloud: path to service account key JSON)
 # EMBEDDING_MODEL=<model name>        (required to enable embeddings; no default)
 
-# River UI basic auth (optional, used when running River UI via docker compose)
-# Defaults: admin / changeme if unset
+# Local River UI basic auth (optional, used by docker compose). Change these for your local setup as needed.
+# compose.yml defaults to admin / changeme if these are unset.
 RIVER_BASIC_AUTH_USER=admin
 RIVER_BASIC_AUTH_PASS=changeme

README.md

@@ -83,9 +83,14 @@ If you want to evaluate Hub quickly, start with the docs:
 ### Local development in this repository
 
 This repository contains the standalone Hub API and worker. The local
-`compose.yml` starts dependency services only: PostgreSQL and River UI. It does
-not start `hub-api` or `hub-worker`; run those from this repository after the
-database is ready.
+`compose.yml` starts dependency services only: PostgreSQL, a one-shot
+`hub-migrate` container, and River UI. The migration container uses the packaged
+Hub image for `goose` and `river`, and bind-mounts this checkout's
+`migrations/` directory so the database schema matches the branch you are
+working on. The image tag defaults to the current Hub release and should stay
+pinned if you override `HUB_IMAGE_TAG`. Docker setup does not require migration
+tools on the host. It does not start `hub-api` or `hub-worker`; run those from
+this repository after the database is ready.
 
 For a local Hub setup:
 
@@ -98,7 +103,15 @@ make run
 `make run` applies River queue migrations and starts both `hub-api` and
 `hub-worker` for local webhook delivery and embedding jobs. Use `make run-api`
 or `make run-worker` only when you intentionally want to run one process on its
-own. `make dev-setup` runs the Hub schema migrations through `make init-db`.
+own. `make dev-setup` also runs the local Hub schema migrations through
+`make init-db`, which is useful when you are changing migration files in this
+repository.
+
+The public Docker quickstart at [hub.formbricks.com/quickstart](https://hub.formbricks.com/quickstart/)
+is maintained outside this repository. Its Compose example should use the same
+one-shot migration service pattern, but rely on the published Hub image's bundled
+`/app/migrations` because quickstart users may not have this repository checked
+out.
 
 For the full Formbricks XM Suite UI, use the
 [`formbricks/formbricks`](https://github.com/formbricks/formbricks) repository

compose.yml

@@ -21,19 +21,46 @@ services:
       postgres
       -c shared_preload_libraries=vector
 
+  # One-shot migration container for Docker-only setup. The Hub image supplies goose and river;
+  # the bind mount keeps migrations aligned with this checkout.
+  hub-migrate:
+    image: ghcr.io/formbricks/hub:${HUB_IMAGE_TAG:-0.2.0}
+    container_name: formbricks_hub_migrate
+    restart: "no"
+    entrypoint: ["sh", "-ec"]
+    command:
+      - |
+        test -x /usr/local/bin/goose ||
+        { echo "Migration tool missing: /usr/local/bin/goose"; exit 1; }
+        test -x /usr/local/bin/river ||
+        { echo "Migration tool missing: /usr/local/bin/river"; exit 1; }
+        test -d /app/migrations ||
+        { echo "Migration directory missing: /app/migrations"; exit 1; }
+        /usr/local/bin/goose -dir /app/migrations postgres "$$DATABASE_URL" up
+        /usr/local/bin/river migrate-up --database-url "$$DATABASE_URL"
+    environment:
+      DATABASE_URL: postgres://postgres:postgres@postgres:5432/test_db?sslmode=disable
+    volumes:
+      - ./migrations:/app/migrations:ro
+    depends_on:
+      postgres:
+        condition: service_healthy
+
   # River UI - web dashboard for River job queue (webhook delivery jobs)
   riverui:
     image: ghcr.io/riverqueue/riverui:latest
     container_name: formbricks_riverui
     environment:
       DATABASE_URL: postgres://postgres:postgres@postgres:5432/test_db?sslmode=disable
-      RIVER_BASIC_AUTH_USER: ${RIVER_BASIC_AUTH_USER}
-      RIVER_BASIC_AUTH_PASS: ${RIVER_BASIC_AUTH_PASS}
+      RIVER_BASIC_AUTH_USER: ${RIVER_BASIC_AUTH_USER:-admin}
+      RIVER_BASIC_AUTH_PASS: ${RIVER_BASIC_AUTH_PASS:-changeme}
     ports:
       - '8081:8080'
     depends_on:
       postgres:
         condition: service_healthy
+      hub-migrate:
+        condition: service_completed_successfully
 
 volumes:
   postgres_data:

tests/README.md

@@ -6,10 +6,9 @@ This directory contains integration tests for the Formbricks Hub API.
 
 Before running the tests, ensure:
 
-1. **PostgreSQL is running** (e.g. `make docker-up`). `make docker-up` starts dependency containers, currently PostgreSQL and River UI; it does not start the Hub API or worker. The tests use the connection string from `.env` (`DATABASE_URL`) when set; if empty, the default `postgres://postgres:postgres@localhost:5432/test_db?sslmode=disable` is used. If you set `POSTGRES_PORT` in `.env`, keep `DATABASE_URL` in sync. If you see `password authentication failed for user "postgres"`, start the stack with `make docker-up` and run `make init-db`.
-2. **Database schema** has been initialized (`make init-db`).
-3. **River queue migrations** have been applied (`make river-migrate`) when testing worker-backed webhook delivery flows.
-4. **API_KEY** is set automatically by the tests; you do not need to set it.
+1. **PostgreSQL is running** (e.g. `make docker-up`). `make docker-up` starts dependency containers: PostgreSQL, the one-shot `hub-migrate` container, and River UI; it does not start the Hub API or worker. The tests use the connection string from `.env` (`DATABASE_URL`) when set; if empty, the default `postgres://postgres:postgres@localhost:5432/test_db?sslmode=disable` is used. If you set `POSTGRES_PORT` in `.env`, keep `DATABASE_URL` in sync.
+2. **Database schema and River queue migrations** have been initialized. The default `make docker-up` path runs them through the packaged `hub-migrate` container, using this checkout's `migrations/` directory. If you are editing local migration files after the stack is already running, run `make init-db` and `make river-migrate` against your test database.
+3. **API_KEY** is set automatically by the tests; you do not need to set it.
 
 ## Running Tests