admin/honeyDueAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README: reflect auto-seed, expand env var reference, link deployment book
Backend CI / Test (push) Has been cancelled
Details
Backend CI / Contract Tests (push) Has been cancelled
Details
Backend CI / Build (push) Has been cancelled
Details
Backend CI / Lint (push) Has been cancelled
Details
Backend CI / Secret Scanning (push) Has been cancelled
Details

Browse Source 
- 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) <noreply@anthropic.com>
This commit is contained in:
Trey t
2026-04-24 07:30:55 -05:00
parent 6f303dbbaa
commit 6d39875ef2
1 changed files with 137 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+137 -49
View File
@@ -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) - **Background Jobs**: [Asynq](https://github.com/hibiken/asynq) (Redis-backed)
- **Push Notifications**: APNs ([apns2](https://github.com/sideshow/apns2)) + FCM HTTP API - **Push Notifications**: APNs ([apns2](https://github.com/sideshow/apns2)) + FCM HTTP API
- **Caching**: Redis - **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) - **Logging**: [zerolog](https://github.com/rs/zerolog)
- **Configuration**: [Viper](https://github.com/spf13/viper) - **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 ## Prerequisites
@@ -35,20 +38,21 @@ cd honeyDueAPI-go
# 2. Create your environment file # 2. Create your environment file
cp .env.example .env 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 # 3. Build and start all services
make docker-dev make docker-dev
# 4. Seed the database with lookup data (required) # 4. Verify the API is running
docker exec -i honeydue-db psql -U honeydue -d honeydue < seeds/001_lookups.sql # Lookups, admin user, and task templates auto-seed on first boot
# via internal/database/migration_seed_initial_data.go. The data_migrations
# 5. (Optional) Seed test data — creates test users, residences, tasks # table tracks what's been applied so re-runs are safe.
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
curl http://localhost:8000/api/health/ 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`. The API is now available at `http://localhost:8000`.
@@ -75,15 +79,15 @@ cp .env.example .env
# - Set DB_HOST=localhost # - Set DB_HOST=localhost
# - Set DB_PORT=5433 (docker-compose maps 5433 externally) # - Set DB_PORT=5433 (docker-compose maps 5433 externally)
# - Set REDIS_URL=redis://localhost:6379/0 # - 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 # 5. Run the API server
psql -h localhost -p 5433 -U honeydue -d honeydue < seeds/001_lookups.sql # First boot auto-seeds lookups, admin user, and task templates
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
make run 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 # 7. (Optional) Run the background worker in a separate terminal
make run-worker make run-worker
``` ```
@@ -109,26 +113,101 @@ createdb honeydue
## Environment Variables ## 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 | ### Core (required)
|----------|-------------|---------|----------|
| `PORT` | Server port | `8000` | No | | Variable | Description | Default |
| `DEBUG` | Enable debug logging | `true` | No | |----------|-------------|---------|
| `SECRET_KEY` | JWT signing secret (32+ chars) | — | **Yes** | | `SECRET_KEY` | Signing secret (32+ chars) | — |
| `POSTGRES_DB` | Database name | `honeydue` | Yes | | `POSTGRES_DB` | Database name | `honeydue` |
| `POSTGRES_USER` | Database user | `postgres` | Yes | | `POSTGRES_USER` | Database user | `postgres` |
| `POSTGRES_PASSWORD` | Database password | — | Yes | | `POSTGRES_PASSWORD` | Database password | — |
| `DB_HOST` | Database host | `localhost` | Yes | | `DB_HOST` | Database host | `localhost` |
| `DB_PORT` | Database port | `5432` | Yes | | `DB_PORT` | Database port | `5432` |
| `REDIS_URL` | Redis connection URL | `redis://localhost:6379/0` | Yes | | `DB_SSLMODE` | TLS mode for Postgres (`disable` for local, `require` for Neon) | `disable` |
| `EMAIL_HOST` | SMTP server | `smtp.gmail.com` | For email | | `REDIS_URL` | Redis connection URL | `redis://localhost:6379/0` |
| `EMAIL_HOST_USER` | SMTP username | — | For email |
| `EMAIL_HOST_PASSWORD` | SMTP app password | — | For email | ### Server (optional)
| `APNS_AUTH_KEY_PATH` | Path to APNs `.p8` key file | — | For iOS push |
| `APNS_AUTH_KEY_ID` | APNs key ID | — | For iOS push | | Variable | Description | Default |
| `APNS_TEAM_ID` | Apple Team ID | — | For iOS push | |----------|-------------|---------|
| `FCM_SERVER_KEY` | Firebase server key | — | For Android push | | `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 ## Project Structure
@@ -162,10 +241,13 @@ honeyDueAPI-go/
│ └── integration/ # Integration + contract tests │ └── integration/ # Integration + contract tests
├── admin/ # Next.js admin panel ├── admin/ # Next.js admin panel
├── migrations/ # SQL migration files ├── migrations/ # SQL migration files
├── seeds/ # Seed data (lookups, test users) ├── seeds/ # Seed data (lookups, test users, admin, templates)
├── templates/emails/ # Email templates ├── templates/emails/ # Email templates
├── docs/ # API docs, OpenAPI spec ├── 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 ├── docker-compose.dev.yml # Self-contained local dev config
├── Dockerfile # Multi-stage build (api, worker, admin) ├── Dockerfile # Multi-stage build (api, worker, admin)
├── Makefile # Build, test, Docker commands ├── Makefile # Build, test, Docker commands
@@ -200,11 +282,10 @@ go test ./internal/handlers -v
go test -run TestTaskHandler_CreateTask ./internal/handlers 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.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 ```bash
# Dev # Dev
@@ -214,10 +295,13 @@ make docker-down # Stop dev containers
make docker-logs # Tail dev container logs make docker-logs # Tail dev container logs
make docker-restart # Restart dev containers make docker-restart # Restart dev containers
# Prod # Build production amd64 images (push to registry handled separately)
make docker-build-prod # Build production images (api, worker, admin) 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 ### Database Migrations
```bash ```bash
@@ -230,14 +314,18 @@ make migrate-create name=add_column # Create a new migration pair
Seed files in `seeds/`: Seed files in `seeds/`:
| File | Purpose | Required | | File | Purpose | Loaded by |
|------|---------|----------| |------|---------|-----------|
| `001_lookups.sql` | Residence types, task categories, priorities, frequencies, contractor specialties | **Yes** | | `001_lookups.sql` | Residence types, task categories, priorities, frequencies, contractor specialties | **Auto-seeded on first API boot** |
| `002_test_data.sql` | Test users, residences, tasks, contractors, documents, notifications | Dev only | | `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 | Dev only | | `003_task_templates.sql` | Pre-built task templates for onboarding | **Auto-seeded on first API boot** |
| `003_admin_user.sql` | Admin panel user | If using admin | | `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` All test users have password: `password123`