ui-syncup 0.3.13 → 0.4.0-beta.1

package/cli/src/commands/status.ts

@@ -0,0 +1,25 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { ui } from '../lib/ui.js'
+import { isDockerRunning } from '../lib/docker.js'
+import { parseEnv } from '../lib/env.js'
+
+export async function statusCommand(composeFile: string): Promise<void> {
+  if (!isDockerRunning()) {
+    ui.error('Docker is not running.')
+    process.exit(1)
+  }
+
+  if (!existsSync(composeFile)) {
+    ui.error(`Compose file not found: ${composeFile}. Run: ui-syncup init`)
+    process.exit(1)
+  }
+
+  spawnSync('docker', ['compose', '-f', composeFile, 'ps'], { stdio: 'inherit' })
+
+  const vars = existsSync('.env') ? parseEnv('.env') : {}
+  const port = vars['PORT'] || '3000'
+  const appUrl = vars['NEXT_PUBLIC_APP_URL'] || `http://localhost:${port}`
+  console.log('')
+  ui.info(`App → ${appUrl}`)
+}

package/cli/src/commands/stop.ts

@@ -0,0 +1,20 @@
+import { ui } from '../lib/ui.js'
+import { isDockerRunning, runCompose } from '../lib/docker.js'
+
+export async function stopCommand(composeFile: string): Promise<void> {
+  ui.header('UI SyncUp — Stop')
+
+  if (!isDockerRunning()) {
+    ui.error('Docker is not running.')
+    process.exit(1)
+  }
+
+  ui.info('Stopping stack...')
+  const result = runCompose(composeFile, ['stop'])
+  if (!result.success) {
+    ui.error('Failed to stop stack')
+    process.exit(1)
+  }
+
+  ui.success('Stack stopped. Data preserved — run: ui-syncup start to resume.')
+}

package/cli/src/commands/upgrade.ts

@@ -0,0 +1,28 @@
+import ora from 'ora'
+import { ui } from '../lib/ui.js'
+import { isDockerRunning, runCompose } from '../lib/docker.js'
+
+export async function upgradeCommand(composeFile: string): Promise<void> {
+  ui.header('UI SyncUp — Upgrade')
+
+  if (!isDockerRunning()) {
+    ui.error('Docker is not running.')
+    process.exit(1)
+  }
+
+  const pull = ora('Pulling latest image...').start()
+  const pullResult = runCompose(composeFile, ['pull'], [], true)
+  if (!pullResult.success) {
+    pull.fail('docker compose pull failed')
+    process.exit(1)
+  }
+  pull.succeed('Latest image pulled')
+
+  const up = ora('Restarting stack (migrations run automatically)...').start()
+  const upResult = runCompose(composeFile, ['up', '-d', '--remove-orphans'], [], true)
+  if (!upResult.success) {
+    up.fail('Stack restart failed — check logs with: ui-syncup logs')
+    process.exit(1)
+  }
+  up.succeed('Upgrade complete. Migrations applied.')
+}

package/cli/src/lib/docker.ts

@@ -0,0 +1,40 @@
+import { execSync, spawnSync } from 'node:child_process'
+
+export function isDockerRunning(): boolean {
+  try {
+    execSync('docker info', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function volumeExists(volumeName: string): boolean {
+  try {
+    const result = execSync(`docker volume inspect ${volumeName}`, { stdio: 'pipe' })
+    return !!result
+  } catch {
+    return false
+  }
+}
+
+export function removeVolume(volumeName: string): boolean {
+  try {
+    execSync(`docker volume rm ${volumeName}`, { stdio: 'pipe' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function runCompose(
+  composeFile: string,
+  args: string[],
+  profiles: string[] = [],
+  quiet = false
+): { success: boolean } {
+  const profileFlags = profiles.flatMap(p => ['--profile', p])
+  const cmd = ['docker', 'compose', '-f', composeFile, ...profileFlags, ...args]
+  const result = spawnSync(cmd[0], cmd.slice(1), { stdio: quiet ? 'pipe' : 'inherit' })
+  return { success: result.status === 0 }
+}

package/cli/src/lib/env.ts

@@ -0,0 +1,42 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+
+export const REQUIRED_VARS = [
+  'DATABASE_URL',
+  'DIRECT_URL',
+  'REDIS_URL',
+  'BETTER_AUTH_SECRET',
+  'BETTER_AUTH_URL',
+  'NEXT_PUBLIC_APP_URL',
+  'NEXT_PUBLIC_API_URL',
+]
+
+export const ENV_EXAMPLE_URL =
+  'https://github.com/BYKHD/ui-syncup/blob/main/.env.example'
+
+export function parseEnv(filePath: string): Record<string, string> {
+  if (!existsSync(filePath)) return {}
+  const content = readFileSync(filePath, 'utf-8')
+  const vars: Record<string, string> = {}
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const idx = trimmed.indexOf('=')
+    if (idx === -1) continue
+    vars[trimmed.slice(0, idx)] = trimmed.slice(idx + 1)
+  }
+  return vars
+}
+
+export function writeEnv(filePath: string, vars: Record<string, string>): void {
+  const lines = Object.entries(vars).map(([k, v]) => `${k}=${v}`)
+  writeFileSync(filePath, lines.join('\n') + '\n', { mode: 0o600 })
+}
+
+export function generateSecret(): string {
+  return randomBytes(32).toString('hex')
+}
+
+export function getMissingVars(vars: Record<string, string>): string[] {
+  return REQUIRED_VARS.filter(k => !vars[k] || vars[k].trim() === '')
+}

package/cli/src/lib/ui.ts

@@ -0,0 +1,43 @@
+import chalk from 'chalk'
+
+const pipe = chalk.white('│')
+
+export const ui = {
+  banner: (version: string) => {
+    const title   = `  ✲  UI SyncUp  v${version}  `
+    const tagline = `  A visual feedback and issue tracking platform  `
+    const width   = Math.max(title.length, tagline.length)
+    const pad     = (s: string) => s + ' '.repeat(width - s.length)
+
+    console.log(chalk.white('╔' + '═'.repeat(width) + '╗'))
+    console.log(
+      chalk.white('║') +
+      '  ' + chalk.white('✲') + '  ' + chalk.bold.white('UI SyncUp') + '  ' + chalk.dim(`v${version}`) +
+      ' '.repeat(width - title.length + 2) +
+      chalk.white('║')
+    )
+    console.log(chalk.white('╠' + '─'.repeat(width) + '╣'))
+    console.log(
+      chalk.white('║') +
+      chalk.dim(pad(tagline)) +
+      chalk.white('║')
+    )
+    console.log(chalk.white('╚' + '═'.repeat(width) + '╝'))
+  },
+
+  header: (msg: string) => {
+    console.log(' ')
+    console.log(chalk.cyan('⚙︎') + ' ' + chalk.bold.white(msg))
+    console.log(pipe)
+  },
+
+  step: (n: number, total: number, msg: string) => {
+    console.log(chalk.magenta('◆') + '  ' + chalk.bold.magenta(`Step ${n} of ${total}`))
+    console.log(pipe + '  ' + chalk.white(msg))
+  },
+
+  info:    (msg: string) => console.log(pipe + '  ' + '🚀' + ' ' + chalk.blue(msg)),
+  success: (msg: string) => console.log(pipe + '  ' + '✨' + ' ' + chalk.green(msg)),
+  warn:    (msg: string) => console.log(pipe + '  ' + '⚠️ ' + chalk.yellow(msg)),
+  error:   (msg: string) => console.error(pipe + '  ' + '🚨' + ' ' + chalk.red(msg)),
+}

package/cli/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["index.ts", "src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/cli/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['index.ts'],
+  format: ['cjs'],
+  target: 'node20',
+  bundle: true,
+  clean: true,
+  sourcemap: false,
+  minify: false,
+  shims: true,
+})

package/components.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "remixicon",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/docker/README.md

@@ -0,0 +1,430 @@
+# Self-Hosted Deployment via Docker (No CLI)
+
+This guide covers deploying UI SyncUp using `docker/compose.yml` directly — without the `ui-syncup` CLI. Use this path when deploying on a Linux server, Coolify, or Dokploy.
+
+> **You do not need the `Dockerfile`.**
+> `compose.yml` pulls the pre-built image `ghcr.io/bykhd/ui-syncup:latest` published by the CI/CD pipeline. The Dockerfile is only used by the GitHub Actions release workflow to build and publish that image.
+
+---
+
+## Files in this directory
+
+| File | Purpose |
+|------|---------|
+| `compose.yml` | Production self-hosting compose — the only file needed for deployment |
+| `compose.dev.yml` | Local development override (SMTP pass-through, mailpit, etc.) |
+| `compose.dev-minio.yml` | Standalone MinIO for local development (no profiles, no auth) |
+
+---
+
+## How services and profiles work
+
+`compose.yml` defines four services. The `app` service always starts. The three infrastructure services are **opt-in via profiles** — nothing bundled runs unless you explicitly activate a profile.
+
+| Profile | Service(s) started | Use when |
+|---------|--------------------|----------|
+| _(none)_ | `app` only | You supply all external services (Supabase, Neon, Upstash, AWS S3, Resend) |
+| `db` | `app` + `postgres:15-alpine` | You want a bundled PostgreSQL database |
+| `cache` | `app` + `redis:7-alpine` | You want a bundled Redis cache |
+| `storage` | `app` + `minio` + `minio-init` | You want bundled S3-compatible object storage |
+| `db,cache` | `app` + `postgres` + `redis` | Bundled database and cache |
+| `db,cache,storage` | all services | Fully self-contained, all-in-one bundle |
+
+**Selecting profiles** — two equivalent methods:
+
+```bash
+# Method A: --profile flags on the command line
+docker compose -f docker/compose.yml \
+  --profile db --profile cache --profile storage up -d
+
+# Method B: COMPOSE_PROFILES env var (preferred for platforms and .env files)
+COMPOSE_PROFILES=db,cache,storage docker compose -f docker/compose.yml up -d
+```
+
+On Coolify, Dokploy, or any platform that manages env vars for you, use **Method B** — set `COMPOSE_PROFILES` in the platform's environment variable UI.
+
+---
+
+## Step 1 — Download the compose file
+
+```bash
+curl -fsSL \
+  https://raw.githubusercontent.com/BYKHD/ui-syncup/main/docker/compose.yml \
+  -o compose.yml
+```
+
+Or copy it directly from this repository. You only need this one file on your server.
+
+---
+
+## Step 2 — Create your `.env` file
+
+```bash
+curl -fsSL \
+  https://raw.githubusercontent.com/BYKHD/ui-syncup/main/.env.example \
+  -o .env
+
+chmod 600 .env
+```
+
+Then open `.env` in an editor and fill in the required variables (see [Environment Variables](#environment-variables) below).
+
+**Place `.env` in the same directory as `compose.yml`.** The `app` service loads it automatically via `env_file`.
+
+---
+
+## Step 3 — Choose your infrastructure backends
+
+Decide which services you will bundle vs. supply externally. This determines your `COMPOSE_PROFILES` value.
+
+### Option A — All external (lightest, cloud-managed)
+
+Leave `COMPOSE_PROFILES` unset or empty. Supply connection strings for all services in `.env`:
+
+```dotenv
+COMPOSE_PROFILES=
+
+DATABASE_URL=postgresql://user:pass@your-db-host:5432/ui_syncup
+DIRECT_URL=postgresql://user:pass@your-db-host:5432/ui_syncup
+REDIS_URL=redis://your-redis-host:6379
+# ... storage and email vars pointing to external providers
+```
+
+### Option B — All bundled (heaviest, no external dependencies)
+
+```dotenv
+COMPOSE_PROFILES=db,cache,storage
+
+POSTGRES_USER=syncup
+POSTGRES_PASSWORD=change-me-strong-password
+POSTGRES_DB=ui_syncup
+
+DATABASE_URL=postgresql://syncup:change-me-strong-password@postgres:5432/ui_syncup
+DIRECT_URL=postgresql://syncup:change-me-strong-password@postgres:5432/ui_syncup
+REDIS_URL=redis://redis:6379
+
+MINIO_ROOT_USER=minioadmin
+MINIO_ROOT_PASSWORD=change-me-strong-password
+STORAGE_ENDPOINT=http://minio:9000
+STORAGE_REGION=us-east-1
+STORAGE_ACCESS_KEY_ID=minioadmin
+STORAGE_SECRET_ACCESS_KEY=change-me-strong-password
+STORAGE_ATTACHMENTS_BUCKET=ui-syncup-attachments
+STORAGE_MEDIA_BUCKET=ui-syncup-media
+STORAGE_ATTACHMENTS_PUBLIC_URL=https://your-domain.com/storage/attachments
+STORAGE_MEDIA_PUBLIC_URL=https://your-domain.com/storage/media
+```
+
+Note: when using bundled Postgres, the hostname in `DATABASE_URL` is `postgres` (the service name). When using bundled Redis, the hostname is `redis`.
+
+### Option C — Mix and match
+
+Any combination works. Only activate profiles for the services you want bundled:
+
+```dotenv
+# Bundled DB + cache, external storage (e.g. AWS S3)
+COMPOSE_PROFILES=db,cache
+```
+
+---
+
+## Step 4 — Set required variables
+
+Regardless of which profile combination you choose, these variables are always required:
+
+```dotenv
+# App identity
+BETTER_AUTH_SECRET=<random string, minimum 32 characters>
+BETTER_AUTH_URL=https://your-domain.com
+NEXT_PUBLIC_APP_URL=https://your-domain.com
+NEXT_PUBLIC_API_URL=https://your-domain.com/api
+
+# Database — either bundled (postgres service) or external
+DATABASE_URL=postgresql://...
+DIRECT_URL=postgresql://...
+
+# Cache — either bundled (redis service) or external
+REDIS_URL=redis://...
+```
+
+Generate a secure `BETTER_AUTH_SECRET`:
+
+```bash
+openssl rand -hex 32
+```
+
+---
+
+## Step 5 — Start the stack
+
+```bash
+docker compose -f compose.yml up -d
+```
+
+Because `COMPOSE_PROFILES` is set in `.env`, Docker Compose reads it automatically — no `--profile` flags needed on the command line.
+
+**What happens on startup:**
+
+1. Bundled infrastructure services (if any profiles active) start and run their health checks.
+2. The `app` container waits for any bundled `postgres`/`redis` to pass their health checks before starting (via `depends_on: condition: service_healthy`). External services have no wait — their availability is your responsibility.
+3. The `app` container runs `bun run db:migrate` automatically before the Next.js server starts.
+4. If migration fails, the `app` container exits immediately (the server never starts). Check logs with `docker compose logs app`.
+5. Once migrations succeed, `node server.js` starts and the app becomes available.
+
+The stack should reach a healthy state within 60 seconds.
+
+---
+
+## Step 6 — Verify
+
+```bash
+# Check all containers are running
+docker compose ps
+
+# Check app logs (confirms migrations ran)
+docker compose logs app
+
+# Hit the health endpoint
+curl http://localhost:3000/api/health
+# Expected: {"status":"ok","version":"...","timestamp":"..."}
+```
+
+---
+
+## Deploying on Coolify
+
+Coolify manages `docker compose` deployments through its UI. There are no `--profile` flags to type — everything is done via environment variables.
+
+### Steps
+
+1. **Create a new Resource** → choose **Docker Compose**.
+
+2. **Compose source** — choose one of:
+   - **URL**: paste the raw GitHub URL to `docker/compose.yml`
+   - **Git repository**: connect your fork and set the compose file path to `docker/compose.yml`
+   - **Inline**: paste the full contents of `compose.yml` directly
+
+3. **Environment Variables** tab — add all your variables. The critical one for profiles:
+
+   ```
+   COMPOSE_PROFILES=db,cache,storage
+   ```
+
+   Add every other required variable from your `.env` here. Coolify injects them into the container environment and passes `COMPOSE_PROFILES` to `docker compose up` automatically.
+
+4. **Port** — Coolify will detect port `3000` from the compose file. Set your domain in the Domains section.
+
+5. **Deploy** — click Deploy. Coolify runs `docker compose up -d` with your env vars injected.
+
+6. **Verify** — check the deployment logs in Coolify's UI. Look for `bun run db:migrate` completing successfully in the `app` container logs.
+
+### Profile selection on Coolify
+
+| What you want | Set in Coolify env vars |
+|---------------|-------------------------|
+| App only (fully external) | `COMPOSE_PROFILES=` (empty value, or omit entirely) |
+| Bundled Postgres only | `COMPOSE_PROFILES=db` |
+| Bundled Postgres + Redis | `COMPOSE_PROFILES=db,cache` |
+| All bundled | `COMPOSE_PROFILES=db,cache,storage` |
+
+> Coolify does not have a "profile selector" UI. The `COMPOSE_PROFILES` env var is the only mechanism. Docker Compose natively reads this variable when running `docker compose up`.
+
+---
+
+## Deploying on Dokploy
+
+Dokploy works the same way as Coolify for Docker Compose deployments.
+
+### Steps
+
+1. **Create a new Application** → choose **Docker Compose**.
+
+2. **Compose file** — paste the contents of `docker/compose.yml` into the compose editor, or connect a Git repository and set the compose file path to `docker/compose.yml`.
+
+3. **Environment** tab — add all your variables including:
+
+   ```
+   COMPOSE_PROFILES=db,cache,storage
+   ```
+
+4. **Domain** — configure your domain in Dokploy's domain settings. It will proxy to port `3000`.
+
+5. **Deploy** — click Deploy.
+
+6. **Logs** — check the `app` service logs in Dokploy to confirm migrations ran before the server started.
+
+### Profile selection on Dokploy
+
+Same as Coolify — set `COMPOSE_PROFILES` in Dokploy's **Environment** tab. No flags or CLI commands required.
+
+---
+
+## Environment Variables
+
+### Always required
+
+| Variable | Description |
+|----------|-------------|
+| `DATABASE_URL` | PostgreSQL pooled connection string |
+| `DIRECT_URL` | PostgreSQL direct (non-pooled) connection string — used by Prisma migrations |
+| `REDIS_URL` | Redis connection string |
+| `BETTER_AUTH_SECRET` | Random string, minimum 32 characters |
+| `BETTER_AUTH_URL` | Full public URL of your app (e.g. `https://syncup.example.com`) |
+| `NEXT_PUBLIC_APP_URL` | Same as `BETTER_AUTH_URL` |
+| `NEXT_PUBLIC_API_URL` | `${NEXT_PUBLIC_APP_URL}/api` |
+
+### Bundled Postgres (`--profile db`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `POSTGRES_USER` | `syncup` | Database username |
+| `POSTGRES_PASSWORD` | _(required)_ | Database password — set a strong value |
+| `POSTGRES_DB` | `ui_syncup` | Database name |
+
+When using bundled Postgres, set `DATABASE_URL` and `DIRECT_URL` to point at the `postgres` service:
+```
+postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+```
+
+### Bundled Redis (`--profile cache`)
+
+No extra variables needed. Set `REDIS_URL=redis://redis:6379` in your `.env`.
+
+### Bundled MinIO (`--profile storage`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MINIO_ROOT_USER` | _(required)_ | MinIO admin username |
+| `MINIO_ROOT_PASSWORD` | _(required, min 8 chars)_ | MinIO admin password |
+| `STORAGE_ENDPOINT` | `http://minio:9000` | S3 endpoint the app uses |
+| `STORAGE_REGION` | `us-east-1` | S3 region |
+| `STORAGE_ACCESS_KEY_ID` | — | Set to the same value as `MINIO_ROOT_USER` |
+| `STORAGE_SECRET_ACCESS_KEY` | — | Set to the same value as `MINIO_ROOT_PASSWORD` |
+| `STORAGE_ATTACHMENTS_BUCKET` | `ui-syncup-attachments` | Bucket name for attachments |
+| `STORAGE_MEDIA_BUCKET` | `ui-syncup-media` | Bucket name for media |
+| `STORAGE_ATTACHMENTS_PUBLIC_URL` | — | Public URL for attachments (e.g. `https://your-domain.com/storage/attachments`) |
+| `STORAGE_MEDIA_PUBLIC_URL` | — | Public URL for media |
+
+Buckets are created automatically by the `minio-init` container on first startup.
+
+### Email (choose one)
+
+**Resend (cloud):**
+| Variable | Description |
+|----------|-------------|
+| `RESEND_API_KEY` | API key from resend.com |
+| `RESEND_FROM_EMAIL` | Verified sender address |
+
+**SMTP (self-hosted):**
+| Variable | Description |
+|----------|-------------|
+| `SMTP_HOST` | SMTP server hostname |
+| `SMTP_PORT` | SMTP port (e.g. `587`) |
+| `SMTP_USER` | SMTP username |
+| `SMTP_PASSWORD` | SMTP password |
+| `SMTP_FROM_EMAIL` | Sender address |
+| `SMTP_SECURE` | `true` for TLS, `false` for STARTTLS |
+
+### OAuth (all optional)
+
+```dotenv
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_REDIRECT_URI=
+
+MICROSOFT_CLIENT_ID=
+MICROSOFT_CLIENT_SECRET=
+MICROSOFT_TENANT_ID=
+
+ATLASSIAN_CLIENT_ID=
+ATLASSIAN_CLIENT_SECRET=
+```
+
+### Runtime environment
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NODE_ENV` | `production` | Set to `development` to enable verbose runtime logging. Note: the published Docker image is always a production build — this only affects runtime behavior, not the compiled output. |
+| `PORT` | `3000` | Host port mapped to the app container |
+
+---
+
+## Upgrading
+
+Pull the latest image and restart. Migrations run automatically on startup.
+
+```bash
+docker compose -f compose.yml pull
+docker compose -f compose.yml up -d --remove-orphans
+```
+
+Check that migrations applied successfully:
+
+```bash
+docker compose logs app | grep -E "migrate|Migration"
+```
+
+> Data volumes (`postgres_data`, `redis_data`, `minio_data`) are never removed by `pull` or `up --remove-orphans`. Your data is safe.
+
+---
+
+## Stopping and removing
+
+```bash
+# Stop containers, keep volumes (data preserved)
+docker compose -f compose.yml down
+
+# Stop containers and remove all data volumes (DESTRUCTIVE)
+docker compose -f compose.yml down -v
+```
+
+---
+
+## Troubleshooting
+
+**App container exits immediately on startup**
+
+The most common cause is a failed migration. Check:
+
+```bash
+docker compose logs app
+```
+
+Look for the `bun run db:migrate` output. Common causes:
+- `DATABASE_URL` is wrong or unreachable
+- Postgres container is not yet healthy (should not happen with `depends_on`, but can occur with external DBs)
+- Schema conflict from a partial previous migration
+
+**Bundled Postgres never becomes healthy**
+
+```bash
+docker compose logs postgres
+```
+
+Usually caused by a missing or empty `POSTGRES_PASSWORD`. Postgres 15 requires a non-empty password unless `POSTGRES_HOST_AUTH_METHOD=trust` is set.
+
+**`COMPOSE_PROFILES` has no effect**
+
+Ensure the variable is set in the environment where `docker compose` runs, not just inside the container. On Coolify/Dokploy this means the **Environment Variables** tab (platform-level), not a variable only passed to the `app` container.
+
+**MinIO buckets not created**
+
+Check `minio-init` logs:
+
+```bash
+docker compose logs minio-init
+```
+
+If `minio-init` exited before MinIO was healthy, restart it:
+
+```bash
+docker compose up minio-init
+```
+
+**Health check failing**
+
+```bash
+curl -v http://localhost:3000/api/health
+```
+
+Expected response: `{"status":"ok","version":"...","timestamp":"..."}`. If the endpoint returns a 502 or connection refused, check `docker compose logs app` for startup errors.