VibeFinance/BEHEER.md

# VibeFinance — Beheer

---

## Ontwikkeling

```powershell
.\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:

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

---

## Release workflow

```powershell
# 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

```bash
# 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:

```bash
# 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
```

---

## Logs en diagnose

```bash
# 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:**

```bash
# 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:**

```bash
# 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:
```bash
docker login vibehoogie.duckdns.org:3000
```

---

## Update-notificaties

De app vergelijkt de draaiende versie met de laatste release op Gitea. Configuratie staat in `package.json`:

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

Vite en de build-scripts lezen deze velden automatisch uit — geen handmatige build-args nodig.