server-up/docs/installeren.md

# Installeren

## In één regel

```bash
curl -fsSL https://git.ramonbesselink.nl/bes-r/server-up/raw/branch/main/install.sh | sh
```

Dat installeert Server Up in `/opt/server-up`, bereikbaar op
`http://localhost:5000`.

**Liever eerst zien wat je uitvoert?** Verstandig — je haalt een script binnen
dat root-rechten gebruikt:

```bash
curl -fsSL https://git.ramonbesselink.nl/bes-r/server-up/raw/branch/main/install.sh -o install.sh
less install.sh
sh install.sh
```

Wil je alleen weten wát het zou doen, zonder dat er iets verandert:

```bash
sh install.sh --dry-run
```

---

## Wat het script doet

1. Controleert of je op Linux zit en of `curl` en `tar` aanwezig zijn
2. Kijkt of Docker draait — zo niet, biedt het aan die te installeren via het
   officiële script van docker.com (het vraagt eerst)
3. Kloont de repo naar `/opt/server-up` (of pakt het tar-archief uit als git
   ontbreekt)
4. Maakt `.env` aan op basis van `.env.example`, met jouw poort en bind-adres
5. Bouwt het image en start de container
6. Wacht tot `/healthz` antwoordt en toont waar je terecht kunt

Het gebruikt alleen `sudo` waar dat nodig is. Kun je zelf al in de doelmap
schrijven én `docker` aanroepen, dan blijft alles onder je eigen account.

---

## Opties

```
--dir PAD        Installatiemap (standaard: /opt/server-up)
--port POORT     Poort voor de webinterface (standaard: 5000)
--bind ADRES     Waarop de poort luistert (standaard: 127.0.0.1)
--branch NAAM    Branch om te installeren (standaard: main)
--token TOKEN    Toegangstoken, als je repo niet openbaar is
--base-dir PAD   Hoofdmap voor stacks, appdata en backups (standaard:
                 /opt/serverup)
--user NAAM      Account waaronder Server Up draait ('serverup' wordt zo nodig
                 aangemaakt; 'root' is de oude situatie)
--admin NAAM     Maak meteen een beheerdersaccount met deze naam
--admin-password-file PAD
                 Lees het wachtwoord uit een bestand
--create-admin   Alleen het account aanmaken, bij een draaiende installatie
--update         Bijwerken naar de nieuwste versie
--uninstall      Stoppen en verwijderen (gegevens blijven staan)
--purge          Bij --uninstall: ook het volume, je gegevensmap en het
                 aangemaakte account weg. Vraagt per onderdeel.
--reconfigure    Bind, poort, account of hoofdmap wijzigen zonder opnieuw te
                 installeren
--doctor         Een bestaande installatie doorlichten
--yes            Niets vragen
--dry-run        Alleen tonen wat er zou gebeuren
```

Het script vraagt ook wanneer je het met `curl … | sh` draait: het praat met je
terminal, niet met stdin. Wil je écht niets gevraagd krijgen, gebruik dan
`--yes`.

Duurt de eerste start langer dan anderhalve minuut — een trage schijf, een
zwakke machine — zet dan het aantal pogingen hoger:

```bash
SU_WACHT_POGINGEN=120 sh install.sh
```

### Voorbeelden

```bash
# Standaard: vraagt waarop het moet luisteren en of je een account wil
sh install.sh

# Bereikbaar op je netwerk, andere poort
sh install.sh --bind 0.0.0.0 --port 8080

# Volledig automatisch, met account
SU_ADMIN_PASSWORD='een-lang-wachtwoord' sh install.sh --admin ramon --yes

# Ergens anders neerzetten
sh install.sh --dir /srv/server-up

# De beta-branch, zonder vragen
sh install.sh --branch dev --yes

# Uit een repo die niet openbaar is
sh install.sh --token jouw-forgejo-token
```

---

## Onder welk account het draait

Bij de installatie wordt gevraagd onder welk account Server Up moet draaien:

```
  Onder welk account moet Server Up draaien?
  Het draait nu nog als root; dat hoeft niet voor alles.

    1) Een nieuw account 'serverup' aanmaken — aanbevolen
       Systeemaccount zonder shell en zonder wachtwoord.
    2) ramon — het account waarmee je nu werkt
    3) Een bestaand account kiezen
    4) Als root draaien — zoals voorheen
```

Met `--user NAAM` of `--yes` sla je de vraag over; dan wordt het `serverup`. De
keuze komt als `SU_UID`/`SU_GID` in je `.env` en blijft bij een `--update` staan.

Zet dat account **niet** in de `docker`-groep. Dat geeft het root op je machine
en is niet nodig — de container regelt de toegang tot de socket zelf. Wat dit
wel en niet oplevert staat in [beveiliging.md](beveiliging.md).

---

## Waar je gegevens staan

`--dir` bepaalt waar Server Up zélf staat. Waar je *stacks, appdata en backups*
komen is een aparte keuze: dat is `BASE_DIR` in `.env`, standaard
`/opt/serverup`. Alles valt daaronder:

```
/opt/serverup/stacks     de compose-bestanden van je apps
/opt/serverup/appdata    de gegevens van je apps
/opt/serverup/backups    de backups
```

Wil je alles onder `/srv`, geef dat dan bij de installatie mee:

```bash
sh install.sh --base-dir /srv/serverup
```

Achteraf kan het ook, maar dan verhuist je data niet mee — daarvoor is
Instellingen → Paden (zie hieronder):

```bash
echo 'BASE_DIR=/srv/serverup' >> .env
docker compose up -d
```

Die map wordt in de container op hetzelfde pad gemount, zodat de paden in je
compose-bestanden op de host kloppen. Server Up kan daardoor **alleen bij paden
onder `BASE_DIR`**. Vul je in de interface een map buiten die boom in, dan zegt
hij welke regel je in `.env` moet zetten in plaats van stilletjes naar een map
binnen de container te schrijven — die je op de host nooit terugziet.

### Later verhuizen

Staat er al data, dan is `.env` aanpassen niet genoeg: je stacks blijven naar
hun oude appdata-map wijzen. Ga naar **Instellingen → Paden**, vul de nieuwe
hoofdmap in en klik op **Alles overnemen**. Server Up:

1. stopt de draaiende stacks
2. kopieert alles naar de nieuwe plek, met een voortgangsbalk
3. controleert of aantal en omvang kloppen
4. schrijft de paden in elke stack om (`docker-compose.yml`, `.env`, metadata)
5. start de stacks weer op de nieuwe plek
6. **en ruimt pas daarna het oude op**

Klopt de controle niet, dan blijft het origineel staan en krijg je de fout te
zien. Ligt de nieuwe map buiten de huidige `BASE_DIR`, zet die dan eerst in
`.env` en draai `docker compose up -d`; daarna kun je verhuizen.

---

## Doorlichten

Werkt er iets niet, of wil je weten of alles klopt:

```bash
sh /opt/server-up/install.sh --doctor
```

Hij kijkt alleen; er wordt niets gewijzigd. Wat hij nagaat:

- of er een installatie staat, en of `.env` afgeschermd is (daar staan tokens in)
- of de Docker-daemon reageert en de container draait en gezond is
- of de webinterface antwoordt **op het adres waarop compose publiceert**, niet
  op een aanname
- onder welk account hij draait, en of dat overeenkomt met `SU_UID` in `.env` —
  staat er iets anders, dan is de container nog niet hercreëerd
- of `BASE_DIR` echt in de container gekoppeld is. Bestaan is niet genoeg: een
  niet-gekoppelde map bestaat wél binnen de container, maar wat daar geschreven
  wordt komt nooit op de host terecht
- hoeveel er in `stacks`, `appdata` en `backups` staat, van wie die mappen zijn,
  en hoeveel ruimte er over is

De exitcode is 1 als er fouten zijn, zodat je hem in een controle kunt hangen.

---

## Instellingen wijzigen

Wil je alleen het bind-adres, de poort of het account veranderen, dan hoef je
niet bij te werken — dat zou ongewild ook nieuwe code binnenhalen:

```bash
sh /opt/server-up/install.sh --reconfigure
```

Hij toont wat er nu staat, stelt dezelfde vragen als bij de installatie en start
de container opnieuw. De broncode blijft ongemoeid.

---

## Bijwerken en terugrollen

```bash
sh /opt/server-up/install.sh --update
```

Komt de nieuwe versie niet omhoog, dan zet het script de broncode terug op de
commit van vóór het bijwerken en start die opnieuw. Lukt dat, dan draai je weer
op je oude versie en is de exitcode 1 — geen stilstaande server en geen rijtje
commando's dat je zelf moet uitvoeren.

Draait je installatie vanaf een registry-image (`SU_IMAGE` in `.env`), dan haalt
het script dat op in plaats van zelf te bouwen. Dat scheelt de paar minuten die
een build kost.

---

## Het beheerdersaccount

Server Up beheert de Docker-daemon, en wie containers kan starten kan
willekeurige mappen van de host mounten. Zolang er nog geen account is, kan
iedereen die de pagina bereikt het claimen — dus hoe korter dat venster, hoe
beter. Het script kan het account daarom meteen aanmaken.

Op een terminal vraagt het script erom. Automatisch kan het ook:

```bash
# Wachtwoord uit een bestand
sh install.sh --admin ramon --admin-password-file /root/su-ww --yes

# Of uit een omgevingsvariabele
SU_ADMIN_PASSWORD='een-lang-wachtwoord' sh install.sh --admin ramon --yes
```

Geef je geen wachtwoord en is er geen terminal, dan maakt het script er zelf een
van 24 tekens en zet die op het scherm. Schrijf die meteen over — hij staat
nergens anders.

> Het wachtwoord kan **niet** als optie mee. Opdrachtregelargumenten zijn voor
> elke gebruiker op de server zichtbaar met `ps` en blijven in je
> shell-geschiedenis staan. `--admin-password` weigert daarom met een verwijzing
> naar de twee manieren hierboven.

Ging het aanmaken mis, of heb je het overgeslagen? Dan kan het achteraf, zolang
er nog geen account bestaat:

```bash
sh /opt/server-up/install.sh --create-admin --admin ramon
```

Eist minstens 10 tekens, net als de webinterface.

---

## Bereikbaarheid

Het script vraagt waarop de webinterface moet luisteren:

| Keuze | `BIND` | Wanneer |
|---|---|---|
| Alleen deze server | `127.0.0.1` | Standaard en veiligst. Erbij via een SSH-tunnel of een reverse proxy op dezelfde machine. |
| Het hele netwerk | `0.0.0.0` | Direct bereikbaar op het adres van je server. Zet er een reverse proxy met TLS voor. |
| Een specifiek adres | zelf opgeven | Bijvoorbeeld alleen je beheernetwerk. |

Achteraf wijzigen kan met dezelfde optie; die wordt ook doorgevoerd in een
`.env` die er al staat:

```bash
sh /opt/server-up/install.sh --update --bind 0.0.0.0
```

Wat je *niet* expliciet meegeeft blijft staan zoals het was, zodat een `--update`
je instellingen niet terugzet. Pas `BIND` daarom aan in `.env` of via deze optie
— **niet** in `docker-compose.yml`, want dat bestand komt uit de repo en wordt
bij elke update overschreven.

Zie [beveiliging.md](beveiliging.md) voor de reverse proxy, rollen en SSO.

---

## Bijwerken

```bash
sh /opt/server-up/install.sh --update
```

Haalt de nieuwste versie op, bouwt opnieuw en herstart. Je `.env` blijft staan,
net als je stacks en gegevens.

Draait Server Up vanaf een registry-image, dan kun je ook bijwerken vanuit de
interface zelf — zie [updates.md](updates.md).

---

## Verwijderen

```bash
sh /opt/server-up/install.sh --uninstall
```

Stopt en verwijdert de container. **Je gegevens blijven staan**: het
docker-volume `su-data` (instellingen, accounts, auditlog) en je stackmappen
onder `BASE_DIR` (standaard `/opt/serverup`). Het script somt op wat er blijft.

Alles definitief weg:

```bash
sh /opt/server-up/install.sh --uninstall --purge
```

Dat vraagt **per onderdeel** apart — het volume, je gegevensmap, het account dat
bij de installatie is aangemaakt, en de installatiemap zelf. Bij de gegevensmap
toont het eerst hoe groot die is, want daar staat alles van al je apps in.

---

## Handmatig, zonder script

```bash
git clone https://git.ramonbesselink.nl/bes-r/server-up.git /opt/server-up
cd /opt/server-up
cp .env.example .env
$EDITOR .env
docker compose up -d --build
```

---

## Als er iets misgaat

| Melding | Wat er aan de hand is |
|---|---|
| `Geen root en geen sudo` | Draai als root, of kies met `--dir` een map waar je zelf in mag schrijven |
| `Docker is geïnstalleerd maar de daemon reageert niet` | `systemctl start docker` |
| `De docker-compose-plugin ontbreekt` | Installeer `docker-compose-plugin` via je pakketbeheerder |
| `Ophalen mislukt. Is de repo openbaar?` | Gebruik `--token` met een Forgejo-token dat de repo mag lezen |
| Reageert niet binnen anderhalve minuut | `docker compose -f /opt/server-up/docker-compose.yml logs --tail=50` |

Laadt de interface zonder opmaak, dan is het downloaden van de front-end-
bestanden tijdens de build misgegaan. Server Up meldt dat bij het opstarten in
zijn eigen log; opnieuw bouwen lost het meestal op.