Ports follow the workspace Port Registry: backend 8094, PostgreSQL 5437, Redis 6380, AuditPic (external) 8093. These are intentionally non-default to avoid clashing with other projects on the same workstation/cluster.

Prerequisites

| Tool | Purpose | |------|---------| | Docker | Postgres + Redis + backend via docker compose | | Java 21 + Maven (bundled ./mvnw) | Backend (Spring Boot 3) | | Flutter 3.8+ | Mobile app | | op (1Password CLI) | Read secrets from the Claimio vault | | kubeseal | Seal secrets with the cluster public key | | kubectl / helm | Deploy to k3s (136.144.174.219) | | gh | CI / PRs |

60-second local start

make up                                   # docker compose: postgres :5437, redis :6380, backend
set -a && source .env.dev && set +a       # env below
cd backend && ./mvnw spring-boot:run      # backend on :8094
curl http://localhost:8094/actuator/health   # → {"status":"UP"}

Mobile:

cd mobile && flutter pub get && flutter run

`.env.dev` (repo root — never commit)

DATABASE_URL=jdbc:postgresql://localhost:5437/claimiodb
DATABASE_USERNAME=claimio
DATABASE_PASSWORD=claimio
DATABASE_ADMIN_USERNAME=claimio
DATABASE_ADMIN_PASSWORD=claimio
REDIS_HOST=localhost
REDIS_PORT=6380
JWT_SECRET=local-dev-secret-at-least-32-chars-long!!
AUDITPIC_BASE_URL=http://localhost:8093
AUDITPIC_API_KEY=test-key
PII_ENCRYPTION_KEY=MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=
PII_HMAC_KEY=YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=
SERVER_PORT=8094

The PII keys above are dev-only dummies. For staging/prod, run ./scripts/generate-pii-keys.sh and store the output in 1Password (below).

Common `make` targets

| Command | What it does | |---------|--------------| | make up / make down | Start / stop the docker compose stack | | make logs | Tail backend logs | | make test | Backend unit tests (needs make up first) | | make build | Build backend JAR (skips tests) | | make test-security | OWASP ZAP baseline scan |

1Password vault structure

All secrets live in the Claimio vault (mahmoudholdingbv.1password.com), items claimio-secrets-staging and claimio-secrets-production.

| Field | Purpose | Generate | |-------|---------|----------| | database-password | DML-only app runtime user | openssl rand -base64 24 | | database-admin-password | Flyway / schema-owner user | openssl rand -base64 24 | | jwt-secret | JWT signing (≥32 chars) | openssl rand -base64 32 | | jwt-previous-secret | Previous JWT key (rotation overlap; blank initially) | leave blank on first setup | | redis-password | Redis auth | openssl rand -base64 24 | | auditpic-api-key | AuditPic integration | provided by AuditPic | | pii-encryption-key | AES-256 PII field encryption (base64) | openssl rand -base64 32 | | pii-hmac-key | HMAC-SHA256 PII blind index (base64) | openssl rand -base64 32 |

./scripts/generate-pii-keys.sh prints the exact op item edit commands for the two PII keys.

Sealing secrets → k3s

Flow: 1Password → Bitnami Sealed Secrets → k3s. The seal-secrets.sh script takes a staging|production arg, reads from claimio-secrets-${ENV} in the Claimio vault, and writes the env-specific manifest.

OP_SERVICE_ACCOUNT_TOKEN=<token> ./scripts/seal-secrets.sh staging   # or: production
git add k8s/sealed-secrets/backend-secrets-staging.yaml
git commit -m "chore: update sealed secrets (staging)"
git push        # CD applies the env-specific file before helm upgrade

Never sed-rename a SealedSecret's namespace — they are namespace-scoped and the cluster cannot decrypt a re-targeted manifest.

Connect kubectl to k3s

ssh -i ~/.ssh/id_ed25519 sarkoutmahmoud@136.144.174.219 \
  "sudo cat /etc/rancher/k3s/k3s.yaml" \
  | sed 's/127.0.0.1/136.144.174.219/' > ~/.kube/claimio-k3s.yaml
export KUBECONFIG=~/.kube/claimio-k3s.yaml
kubectl get nodes

GitHub secrets required

Set under Settings → Secrets and variables → Actions:

| Secret | Description | |--------|-------------| | GHCR_TOKEN | GHCR token (write:packages) | | OP_SERVICE_ACCOUNT_TOKEN | 1Password service-account token with read on the Claimio vault | | VPS_SSH_KEY | Private SSH key for sarkoutmahmoud@136.144.174.219 | | KUBECONFIG | Base64-encoded kubeconfig for the k3s cluster | | BACKUP_S3_ACCESS_KEY / BACKUP_S3_SECRET_KEY | DB-backup S3 storage |

Troubleshooting

Backend exits at startup on a PII key — PII_ENCRYPTION_KEY / PII_HMAC_KEY missing or not 32-byte base64. Copy the dev values above.
make test → connection refused — run make up first (tests hit localhost:5437 / :6380).
/api/v1/auth/login → 401 on a fresh DB — no users seeded; there is no public /register. Seed a tenant + user via SQL after Flyway runs.
Port already in use — 8094/5437/6380 are non-default by design; change SERVER_PORT or stop the conflicting process.

See deployment.md for the staging/prod deploy flow and the cluster bring-up recipe, and architecture.md for the system design.

Reacties

Nog geen reacties

Athena — claimio/setup.md

Claimio — Local Dev & Secrets Setup