From 6d39875ef2e543d7f7681c7e4a60a890128b0f28 Mon Sep 17 00:00:00 2001 From: Trey t Date: Fri, 24 Apr 2026 07:30:55 -0500 Subject: [PATCH] README: reflect auto-seed, expand env var reference, link deployment book - Getting Started (all 3 install paths): simplify to one "start the app, first-boot auto-seeds lookups + admin + templates" step + optional dev test-data seed - Seed Data table: mark 001_lookups / 003_admin_user / 003_task_templates as auto-seeded via internal/database/migration_seed_initial_data.go; only 002_test_data.sql is manual now - Environment Variables: split into logical groups (core, server, admin seed, email, push, B2, worker schedules, feature flags, Apple/Google), added ~45 vars that weren't documented. Defer full reference to docs/deployment/10-secrets-config.md - Add ADMIN_EMAIL / ADMIN_PASSWORD to the admin-seed group - Tech Stack: add Backblaze B2 (minio-go), Fastmail/go-mail, Cloudflare, K3s (production orchestrator) - Project Structure: add deploy-k3s/ and docs/deployment/; mark docker-compose.yml as Swarm-era legacy - Docker subsection: clarify compose files are local dev; point at deployment book for prod workflow Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 186 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 137 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 98c31ba..79ae8fd 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,12 @@ Go REST API for the honeyDue property management platform. Powers iOS and Androi - **Background Jobs**: [Asynq](https://github.com/hibiken/asynq) (Redis-backed) - **Push Notifications**: APNs ([apns2](https://github.com/sideshow/apns2)) + FCM HTTP API - **Caching**: Redis +- **Object Storage**: Backblaze B2 via [minio-go/v7](https://github.com/minio/minio-go) (S3-compatible) +- **Email**: SMTP via [wneessen/go-mail](https://github.com/wneessen/go-mail) (Fastmail in prod) - **Logging**: [zerolog](https://github.com/rs/zerolog) - **Configuration**: [Viper](https://github.com/spf13/viper) -- **Admin Panel**: Next.js (separate build target) +- **Admin Panel**: Next.js 16 (separate build target; auto-seeded via `ADMIN_EMAIL`/`ADMIN_PASSWORD`) +- **Production Orchestrator**: K3s v1.34.6 HA on Hetzner Cloud, fronted by Cloudflare. See [`docs/deployment/`](./docs/deployment/README.md) for the full book. ## Prerequisites @@ -35,20 +38,21 @@ cd honeyDueAPI-go # 2. Create your environment file cp .env.example .env -# Edit .env — at minimum set SECRET_KEY to a random 32+ char string +# Edit .env — at minimum set: +# - SECRET_KEY to a random 32+ char string +# - ADMIN_EMAIL + ADMIN_PASSWORD if you want the Next.js admin panel seeded # 3. Build and start all services make docker-dev -# 4. Seed the database with lookup data (required) -docker exec -i honeydue-db psql -U honeydue -d honeydue < seeds/001_lookups.sql - -# 5. (Optional) Seed test data — creates test users, residences, tasks -docker exec -i honeydue-db psql -U honeydue -d honeydue < seeds/002_test_data.sql -docker exec -i honeydue-db psql -U honeydue -d honeydue < seeds/003_task_templates.sql - -# 6. Verify the API is running +# 4. Verify the API is running +# Lookups, admin user, and task templates auto-seed on first boot +# via internal/database/migration_seed_initial_data.go. The data_migrations +# table tracks what's been applied so re-runs are safe. curl http://localhost:8000/api/health/ + +# 5. (Optional) Seed dev test data — creates test users, residences, tasks +docker exec -i honeydue-db psql -U honeydue -d honeydue < seeds/002_test_data.sql ``` The API is now available at `http://localhost:8000`. @@ -75,15 +79,15 @@ cp .env.example .env # - Set DB_HOST=localhost # - Set DB_PORT=5433 (docker-compose maps 5433 externally) # - Set REDIS_URL=redis://localhost:6379/0 +# - Set ADMIN_EMAIL + ADMIN_PASSWORD if you want the Next.js admin panel seeded -# 5. Seed the database -psql -h localhost -p 5433 -U honeydue -d honeydue < seeds/001_lookups.sql -psql -h localhost -p 5433 -U honeydue -d honeydue < seeds/002_test_data.sql -psql -h localhost -p 5433 -U honeydue -d honeydue < seeds/003_task_templates.sql - -# 6. Run the API server +# 5. Run the API server +# First boot auto-seeds lookups, admin user, and task templates make run +# 6. (Optional, dev only) Seed dev test data in a separate terminal +psql -h localhost -p 5433 -U honeydue -d honeydue < seeds/002_test_data.sql + # 7. (Optional) Run the background worker in a separate terminal make run-worker ``` @@ -109,26 +113,101 @@ createdb honeydue ## Environment Variables -Copy `.env.example` to `.env` and configure: +Copy `.env.example` to `.env` and configure. The table below covers what's +needed for local dev. For the complete production env var reference +(~60 vars), see +[`docs/deployment/10-secrets-config.md`](./docs/deployment/10-secrets-config.md). -| Variable | Description | Default | Required | -|----------|-------------|---------|----------| -| `PORT` | Server port | `8000` | No | -| `DEBUG` | Enable debug logging | `true` | No | -| `SECRET_KEY` | JWT signing secret (32+ chars) | — | **Yes** | -| `POSTGRES_DB` | Database name | `honeydue` | Yes | -| `POSTGRES_USER` | Database user | `postgres` | Yes | -| `POSTGRES_PASSWORD` | Database password | — | Yes | -| `DB_HOST` | Database host | `localhost` | Yes | -| `DB_PORT` | Database port | `5432` | Yes | -| `REDIS_URL` | Redis connection URL | `redis://localhost:6379/0` | Yes | -| `EMAIL_HOST` | SMTP server | `smtp.gmail.com` | For email | -| `EMAIL_HOST_USER` | SMTP username | — | For email | -| `EMAIL_HOST_PASSWORD` | SMTP app password | — | For email | -| `APNS_AUTH_KEY_PATH` | Path to APNs `.p8` key file | — | For iOS push | -| `APNS_AUTH_KEY_ID` | APNs key ID | — | For iOS push | -| `APNS_TEAM_ID` | Apple Team ID | — | For iOS push | -| `FCM_SERVER_KEY` | Firebase server key | — | For Android push | +### Core (required) + +| Variable | Description | Default | +|----------|-------------|---------| +| `SECRET_KEY` | Signing secret (32+ chars) | — | +| `POSTGRES_DB` | Database name | `honeydue` | +| `POSTGRES_USER` | Database user | `postgres` | +| `POSTGRES_PASSWORD` | Database password | — | +| `DB_HOST` | Database host | `localhost` | +| `DB_PORT` | Database port | `5432` | +| `DB_SSLMODE` | TLS mode for Postgres (`disable` for local, `require` for Neon) | `disable` | +| `REDIS_URL` | Redis connection URL | `redis://localhost:6379/0` | + +### Server (optional) + +| Variable | Description | Default | +|----------|-------------|---------| +| `PORT` | Server port | `8000` | +| `DEBUG` | Enable debug logging | `true` | +| `BASE_URL` | Canonical base URL used in generated links | `http://localhost:8000` | +| `ALLOWED_HOSTS` | Comma-separated Host header allowlist | `*` | +| `CORS_ALLOWED_ORIGINS` | Comma-separated CORS origins | `*` | +| `ADMIN_PANEL_URL` | URL of the Next.js admin panel | `http://localhost:3000` | +| `NEXT_PUBLIC_API_URL` | API URL baked into the admin bundle | `http://localhost:8000` | + +### Admin panel seed (new — see [commit 4ec4bbb](https://gitea.treytartt.com/admin/honeyDueAPI/commit/4ec4bbbfe88b6060e17c046e0fe2b321f7110bf1)) + +| Variable | Description | +|----------|-------------| +| `ADMIN_EMAIL` | Email for the initial `admin_users` row. Created on first boot. | +| `ADMIN_PASSWORD` | Password for that admin (bcrypt-hashed at seed time). Change in the admin UI after first login, then blank this out. | + +### Email (for transactional mail) + +| Variable | Description | Default | +|----------|-------------|---------| +| `EMAIL_HOST` | SMTP server | `smtp.gmail.com` | +| `EMAIL_PORT` | SMTP port | `587` | +| `EMAIL_HOST_USER` | SMTP username | — | +| `EMAIL_HOST_PASSWORD` | SMTP app password | — | +| `DEFAULT_FROM_EMAIL` | From address | — | +| `EMAIL_USE_TLS` | Opportunistic STARTTLS | `true` | + +### Push notifications (optional; gated behind `FEATURE_PUSH_ENABLED`) + +| Variable | Description | +|----------|-------------| +| `APNS_AUTH_KEY_PATH` | Path to APNs `.p8` key file | +| `APNS_AUTH_KEY_ID` | APNs key ID | +| `APNS_TEAM_ID` | Apple Team ID | +| `APNS_TOPIC` | Bundle ID | +| `FCM_SERVER_KEY` | Firebase server key | + +### Object storage (Backblaze B2 in prod; local volume in dev) + +| Variable | Description | +|----------|-------------| +| `B2_ENDPOINT` | S3-compatible endpoint (e.g. `s3.us-east-005.backblazeb2.com`) | +| `B2_KEY_ID` | B2 app key ID | +| `B2_APP_KEY` | B2 app key secret | +| `B2_BUCKET_NAME` | Bucket name | +| `B2_REGION` | Region code (e.g. `us-east-005`) | +| `B2_USE_SSL` | Use HTTPS | `true` | + +Leave all four `B2_*` empty in dev to fall back to a local `/app/uploads` volume. + +### Worker schedules (UTC hours) + +| Variable | Description | Default | +|----------|-------------|---------| +| `TASK_REMINDER_HOUR` | When to send task reminders | `14` | +| `OVERDUE_REMINDER_HOUR` | When to send overdue reminders | `15` | +| `DAILY_DIGEST_HOUR` | When to send daily digest | `3` | + +### Feature flags (default `true` in dev, configurable in prod) + +| Variable | Description | +|----------|-------------| +| `FEATURE_PUSH_ENABLED` | APNs / FCM push notifications | +| `FEATURE_EMAIL_ENABLED` | Transactional email | +| `FEATURE_WEBHOOKS_ENABLED` | Outbound webhooks | +| `FEATURE_ONBOARDING_EMAILS_ENABLED` | Onboarding drip emails | +| `FEATURE_PDF_REPORTS_ENABLED` | PDF task report generation | +| `FEATURE_WORKER_ENABLED` | Run the Asynq worker | + +### Apple / Google auth + IAP (optional) + +`APPLE_CLIENT_ID`, `APPLE_TEAM_ID`, `GOOGLE_CLIENT_ID`, `GOOGLE_ANDROID_CLIENT_ID`, +`GOOGLE_IOS_CLIENT_ID`, plus `APPLE_IAP_*` and `GOOGLE_IAP_*` for receipt +validation. See Chapter 10 of the deployment book for details. ## Project Structure @@ -162,10 +241,13 @@ honeyDueAPI-go/ │ └── integration/ # Integration + contract tests ├── admin/ # Next.js admin panel ├── migrations/ # SQL migration files -├── seeds/ # Seed data (lookups, test users) +├── seeds/ # Seed data (lookups, test users, admin, templates) ├── templates/emails/ # Email templates ├── docs/ # API docs, OpenAPI spec -├── docker-compose.yml # Production / Docker Swarm config +│ └── deployment/ # Full production deployment book (26 chapters) +├── deploy-k3s/ # Production Kubernetes manifests + migration notes +├── deploy/ # Legacy Docker Swarm config (to be removed) +├── docker-compose.yml # Legacy (Swarm-era); prod now runs on K3s ├── docker-compose.dev.yml # Self-contained local dev config ├── Dockerfile # Multi-stage build (api, worker, admin) ├── Makefile # Build, test, Docker commands @@ -200,11 +282,10 @@ go test ./internal/handlers -v go test -run TestTaskHandler_CreateTask ./internal/handlers ``` -### Docker +### Docker (local dev) -Two compose files: - **`docker-compose.dev.yml`** — self-contained local dev (build from source, `container_name`, `depends_on`, dev defaults) -- **`docker-compose.yml`** — production / Docker Swarm (image refs, `deploy:` sections, overlay network) +- **`docker-compose.yml`** — legacy (Swarm-era). Prod now runs on K3s (see [deployment book](./docs/deployment/README.md)). File retained temporarily. ```bash # Dev @@ -214,10 +295,13 @@ make docker-down # Stop dev containers make docker-logs # Tail dev container logs make docker-restart # Restart dev containers -# Prod -make docker-build-prod # Build production images (api, worker, admin) +# Build production amd64 images (push to registry handled separately) +make docker-build-prod ``` +For the full production build + deploy workflow, see +[`docs/deployment/14-deployment-process.md`](./docs/deployment/14-deployment-process.md). + ### Database Migrations ```bash @@ -230,14 +314,18 @@ make migrate-create name=add_column # Create a new migration pair Seed files in `seeds/`: -| File | Purpose | Required | -|------|---------|----------| -| `001_lookups.sql` | Residence types, task categories, priorities, frequencies, contractor specialties | **Yes** | -| `002_test_data.sql` | Test users, residences, tasks, contractors, documents, notifications | Dev only | -| `003_task_templates.sql` | Pre-built task templates for onboarding | Dev only | -| `003_admin_user.sql` | Admin panel user | If using admin | +| File | Purpose | Loaded by | +|------|---------|-----------| +| `001_lookups.sql` | Residence types, task categories, priorities, frequencies, contractor specialties | **Auto-seeded on first API boot** | +| `003_admin_user.sql` | Placeholder admin panel user (also seeded via `ADMIN_EMAIL` / `ADMIN_PASSWORD` env vars) | **Auto-seeded on first API boot** | +| `003_task_templates.sql` | Pre-built task templates for onboarding | **Auto-seeded on first API boot** | +| `002_test_data.sql` | Dev-only: test users, residences, tasks, contractors, documents, notifications | **Manual** (`psql` or `docker exec`) | -### Test Users +Auto-seeded files run once per database — tracked in the `data_migrations` +table by `internal/database/migration_seed_initial_data.go`. Each INSERT +uses `ON CONFLICT DO UPDATE`, so re-runs are safe. + +### Test Users (from `002_test_data.sql`; dev only) All test users have password: `password123`