VibeFinance/BEHEER.md

VibeFinance — Beheer

---

Ontwikkeling

.\dev.ps1                          # build + start (standaard)
.\dev.ps1 build                    # alleen bouwen
.\dev.ps1 build -Target backend    # alleen backend bouwen
.\dev.ps1 build -Target frontend   # alleen frontend bouwen
.\dev.ps1 up -Target backend       # alleen backend herbouwen + herstarten
.\dev.ps1 up -Target frontend      # alleen frontend herbouwen + herstarten
.\dev.ps1 push                     # dev-images naar registry pushen
.\dev.ps1 push -Target backend     # alleen backend pushen
.\dev.ps1 push -Target frontend    # alleen frontend pushen

Op macOS/Linux: gebruik ./dev.sh met dezelfde argumenten.

⚠️ .\dev.ps1 up (beide services) en .\dev.ps1 down voeren intern docker compose down -v uit — dit wist de development-database. Gebruik voor een herstart zonder dataverlies:

docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml up -d --build

---

Release workflow

# 1. Versienummer in package.json van "x.x.x-dev" naar "x.x.x"
# 2.
.\release.ps1           # bouw, push naar registry, maak Git-tag aan
.\release.ps1 -DryRun   # droogloop — toont alle stappen zonder uit te voeren
.\release.ps1 -NoBuild  # sla docker build over, push bestaande images

# 3. Versienummer in package.json naar "x.x.(x+1)-dev" voor volgende cyclus

---

Docker

# Update via pre-built images
docker compose pull && docker compose up -d

# Reset inclusief database  ⚠️ wist alle data
docker compose down -v && docker compose up -d

PostgreSQL versie-upgrade

Bij een upgrade van PostgreSQL (bijv. 16 → 18) is de bestaande data niet compatibel. Stappen:

# 1. Backup maken
docker exec vibefinance_postgres pg_dump -U vibefinance vibefinance > backup-$(date +%F).sql

# 2. Oude containers en volumes verwijderen
docker compose down -v

# 3. Nieuwe versie starten
docker compose up -d

# 4. Backup terugzetten
docker exec -i vibefinance_postgres psql -U vibefinance -d vibefinance < backup-YYYY-MM-DD.sql

---

Architectuur — nginx proxy

De frontend-container (nginx) serveert de React-app en proxyt /api/-verzoeken intern door naar de backend-container op poort 3001. Dit is geconfigureerd in frontend/nginx-spa.conf:

location /api/ {
    proxy_pass http://backend:3001;
}

Ontbreekt dit blok, dan krijgen gebruikers "Kan geen verbinding maken met de server" bij het inloggen — ook al draaien alle containers.

---

Logs en diagnose

# Live logs (dev)
docker compose -f docker-compose.dev.yml logs -f

# Live logs (productie)
docker compose logs -f

# Status containers
docker compose ps

# Database inspecteren (dev)
docker exec -it vibefinance-postgres-dev psql -U vibefinance -d vibefinance

# Database inspecteren (productie)
docker exec -it vibefinance_postgres psql -U vibefinance -d vibefinance

---

Data persistentie

De backend slaat alle data op in PostgreSQL.

Omgeving	Volume	Mount pad
Productie	vibefinance_pgdata	/var/lib/postgresql
Development	postgres_dev_data	/var/lib/postgresql

PostgreSQL 18 gebruikt PGDATA=/var/lib/postgresql/18/docker. Het volume is gemount op /var/lib/postgresql zodat data bewaard blijft na een container restart.

Backup maken:

# Dev
docker exec vibefinance-postgres-dev pg_dump -U vibefinance vibefinance > backup-$(date +%F).sql

# Productie
docker exec vibefinance_postgres pg_dump -U vibefinance vibefinance > backup-$(date +%F).sql

Backup terugzetten:

# Dev
docker exec -i vibefinance-postgres-dev psql -U vibefinance -d vibefinance < backup-2026-04-08.sql

# Productie
docker exec -i vibefinance_postgres psql -U vibefinance -d vibefinance < backup-2026-04-08.sql

---

Gebruikersbeheer

De eerste geregistreerde gebruiker krijgt automatisch de Admin-rol. Verdere accounts kunnen via de app aangemaakt worden (Gebruikersbeheer, Admin vereist) of via de API.

Rollen:

Rol	Rechten
Admin	Alles, inclusief gebruikersbeheer
Bewerker	Data lezen en bewerken
Viewer	Alleen lezen

---

Productie checklist

• POSTGRES_PASSWORD instellen op een sterk wachtwoord
• JWT_SECRET aanpassen (genereer met openssl rand -hex 64)
• CORS_ORIGIN instellen op je domeinnaam
• FRONTEND_PORT aanpassen indien poort 3300 al in gebruik is
• TLS afhandelen via een externe reverse proxy (bijv. Nginx Proxy Manager, Caddy, Traefik)

---

Registry

vibehoogie.duckdns.org:3000/vibe/vibefinance-backend
vibehoogie.duckdns.org:3000/vibe/vibefinance-frontend

Tags:
  latest          productie — meest recente release
  x.x.x           productie — specifieke versie
  latest-dev      development — meest recente dev build
  x.x.x-dev       development — specifieke dev versie

Inloggen op registry:

docker login vibehoogie.duckdns.org:3000

---

Update-notificaties

De app vergelijkt de draaiende versie met de laatste release op Gitea en toont dat op het belletje in de topbalk en onder "Over VibeFinance".

Hoe de check loopt

1. De frontend vraagt /api/update-check op de eigen backend — de Gitea API stuurt geen CORS-headers, dus de browser mag die niet direct bevragen.
2. De backend haalt releases/latest bij Gitea op en cachet het antwoord 15 minuten.
3. De frontend kijkt bij het openen, daarna elk half uur en bij het terugkeren naar het tabblad. Alleen een écht hoger versienummer geeft een melding.

Builds met een -dev suffix melden nooit (die lopen voor op de laatste release). Wil je de melding tijdens ontwikkeling toch testen: open de app met ?updatecheck in de URL.

Configuratie

De bron staat in de root package.json:

"repository": "https://vibehoogie.duckdns.org/vibe/VibeFinance",
"updateCheckUrl": "https://vibehoogie.duckdns.org/api/v1/repos/vibe/VibeFinance/releases/latest"

dev.ps1 zet die URL als UPDATE_CHECK_URL in de omgeving; in productie komt hij uit .env (of de default in docker-compose.yml). Beschikbare backend-variabelen:

Variabele	Betekenis
UPDATE_CHECK_URL	Release-API die gepolld wordt. Leeg = melding uit.
UPDATE_CHECK_TOKEN	Alleen nodig als de repo in Gitea niet publiek leesbaar is.

Een release publiceren

Een kale Git-tag is niet genoeg: releases/latest geeft alleen echte releases terug. release.ps1 maakt die aan (stap 4) met de changelog-sectie van die versie als release-notes. Daarvoor is een Gitea-token met release-rechten nodig:

$env:GITEA_TOKEN = "<token>"
.\release.ps1

Zonder token slaat het script die stap over met een waarschuwing — images en tag staan dan wel klaar, maar gebruikers zien geen melding tot de release bestaat.