server-up/README.md

# Server Up

Zelfgehoste beheerinterface voor Docker: apps installeren uit een catalogus,
stacks starten en stoppen, backups maken en terugzetten, en containers een eigen
IP-adres in je netwerk geven.

> ⚠️ **Toegang tot Server Up staat gelijk aan root op de host.** De applicatie
> beheert de Docker-daemon, en wie containers kan starten kan willekeurige mappen
> van de host mounten. Behandel de interface navenant: maak direct een account
> aan, zet hem niet zonder reverse proxy met TLS op internet, en lees
> [docs/beveiliging.md](docs/beveiliging.md).

---

## Wat het doet

| | |
|---|---|
| **App-catalogus** | 96 kant-en-klare apps, ingedeeld in categorieën met kleur. Zoeken, filteren en installeren met een formulier in plaats van YAML. |
| **Stacks beheren** | Starten, stoppen, bijwerken en herstarten — per stack of per losse container, met logs en live CPU-/geheugengebruik. |
| **Apps koppelen** | Stacks komen op een gedeeld netwerk, zodat ze elkaar op naam bereiken. Een veld dat naar een andere app verwijst toont een keuzelijst met wat je al draait. |
| **Eigen IP per stack** | Met macvlan of ipvlan krijgt een app een eigen adres in je LAN in plaats van poorten op de host. |
| **Backups** | Handmatig, gepland, en automatisch vóór een update of verwijdering. Met terugzetten en een bewaarbeleid. |
| **Updates** | Voor Server Up zelf (stable of beta) en voor de images van je geïnstalleerde stacks. |
| **Toegang** | Lokale accounts met rollen (beheerder, operator, alleen lezen), of SSO via een reverse proxy. |

## Wat je nodig hebt

- Een Linux-server met Docker en de compose-plugin
- Toegang tot `/var/run/docker.sock`
- Ongeveer 300 MB schijfruimte voor de applicatie zelf

## Installeren

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

Dat controleert je systeem, installeert Docker als het ontbreekt, zet Server Up
in `/opt/server-up` en start het op `http://localhost:5000`.

Liever eerst lezen wat je uitvoert — verstandig, want het script gebruikt
root-rechten:

```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 --dry-run     # toont wat het zou doen, zonder iets te wijzigen
sh install.sh
```

Handmatig kan ook:

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

Alle opties staan in [docs/installeren.md](docs/installeren.md):
`--dir`, `--port`, `--bind`, `--branch`, `--token`, `--update`, `--uninstall`.

Open daarna de interface en **maak meteen een beheerdersaccount aan.**
Zolang dat niet gebeurd is, kan iedereen die de pagina bereikt het account
claimen — de container waarschuwt daar bij het opstarten ook voor.

### Instellingen

Alles staat met uitleg in [`.env.example`](.env.example). De twee die je
waarschijnlijk meteen nodig hebt:

```bash
BIND=127.0.0.1     # 0.0.0.0 om er van buiten de server bij te kunnen
PORT=5000
```

De poort bindt standaard op `127.0.0.1`. Zet hem pas open als er een reverse
proxy met TLS voor staat.

## Documentatie

| Document | Waarover |
|---|---|
| [docs/installeren.md](docs/installeren.md) | Het installatiescript, opties, bijwerken en verwijderen |
| [docs/beveiliging.md](docs/beveiliging.md) | Accounts, rollen, SSO, reverse proxy, wat wel en niet is afgedekt |
| [docs/apps-maken.md](docs/apps-maken.md) | Eigen apps toevoegen: het volledige templateformaat |
| [docs/netwerken.md](docs/netwerken.md) | Stacks een eigen IP geven met macvlan of ipvlan |
| [docs/backups.md](docs/backups.md) | Wat er wél en niet in een backup zit, terugzetten, bewaarbeleid |
| [docs/updates.md](docs/updates.md) | Update-kanalen en de Forgejo-registry inrichten |
| [docs/synchroniseren.md](docs/synchroniseren.md) | Code van je apparaat naar de server via Forgejo |
| [docs/forgejo-actions-setup.md](docs/forgejo-actions-setup.md) | Runners instellen |

## Eigen apps toevoegen

Wijs Server Up naar je eigen git-repo met app-sjablonen (Instellingen → App
Store → Repository), of voeg een map toe onder `apps/`:

```
apps/mijn-app/
├── template.json          metadata en de vragen bij het installeren
└── files/
    └── compose.yaml       het compose-bestand met << variabelen >>
```

Het volledige formaat staat in [docs/apps-maken.md](docs/apps-maken.md).

## Bijwerken en verwijderen

```bash
sh /opt/server-up/install.sh --update      # nieuwste versie ophalen en herstarten
sh /opt/server-up/install.sh --uninstall   # stoppen; je gegevens blijven staan
```

Draait Server Up vanaf een registry-image, dan kan bijwerken ook met een knop in
de interface — zie [docs/updates.md](docs/updates.md).

## Ontwikkelen

```bash
python3 -m venv venv && venv/bin/pip install -r server-up/requirements.txt pytest
venv/bin/python -m pytest tests -q          # de volledige suite
cd server-up && SU_DEV=1 python app.py      # lokaal draaien op poort 5000
```

De testsuite draait ook over alle app-sjablonen: elke app moet renderen naar
geldige compose-YAML, met gedeclareerde volumes en zonder onvervangen
variabelen. Voeg je een app toe, dan wordt die automatisch meegenomen.

De deploy-workflows draaien de tests in een container (`python:3.12-slim`), dus
op de runner is verder niets nodig dan Docker.

## Licentie en bijdragen

Zie `CHANGELOG.md` voor de geschiedenis. Werk op de `dev`-branch en bump
`VERSION` bij elke wijziging; een test bewaakt dat er een changelog-sectie bij
hoort.