zima-apps/README.md

# zima-apps

Skelett för att bygga och underhålla ZimaOS/CasaOS-appar i ett eget appstore-repo.

## Mål

- Små, reviewbara appdefinitioner.
- Säkra default-värden (least privilege, pinned image-taggar, inga `latest`).
- Tydlig struktur för metadata, kategorier och rekommendationer.

## Struktur

```text
.
├── Apps/
│   └── _template/
│       ├── README.md
│       └── docker-compose.yaml
├── category-list.json
├── featured-apps.json
├── recommend-list.json
└── scripts/
    ├── build-appstore-zip.sh
    ├── build-and-push-image.sh
    ├── discover-zima-repos-and-apps.sh
    ├── map-unraid-images-to-zima-apps.sh
    └── validate-appstore.sh
```

## Viktiga antaganden

- Repo använder `docker-compose.yaml` enligt teamets standard.
- Upstream-exempel använder ofta `docker-compose.yml`.
- Om en extern pipeline kräver exakt `.yml` behöver vi lägga till en konverterings/rename-step vid publicering.

## Snabbstart

1. Kopiera `Apps/_template` till `Apps/<app-id>`.
2. Sätt unikt `name` i compose-filen (endast gemener + `-`).
3. Pinna image till explicit version eller digest (inte `latest`).
4. Kör validering:

```bash
./scripts/validate-appstore.sh
```

Inför release/publicering, kör strikt validering för högrisk-inställningar:

```bash
./scripts/validate-appstore.sh --enforce-risk-docs
```

Bygg och publicera app-specifika custom images (Docker Hub namespace `joafri` som default):

```bash
./scripts/build-and-push-image.sh --app-id caddy-autogen --tag 0.1.0
```

Scriptet läser `Apps/<app-id>/docker-compose.yaml` och bygger alla services som har `build:` om `--component` inte anges.
`--component` kan användas för en enskild service (service-namn eller context-path).
Arkitekturer hämtas från `x-casaos.architectures`; builden kör fail-open per arkitektur och visar varningar i slutet för misslyckade arch-builds.

## Scripts

### `validate-appstore.sh`

Basvalidering:

```bash
./scripts/validate-appstore.sh
```

Strikt riskdokumentationskontroll:

```bash
./scripts/validate-appstore.sh --enforce-risk-docs
```

### `build-and-push-image.sh`

Bygger och pushar appens custom images till Docker Hub (`joafri` som default).

```bash
./scripts/build-and-push-image.sh --app-id caddy-autogen --tag 0.2.0
```

Viktiga flaggor:

- `--component <value>`: bygg endast en service (service-namn eller context-path).
- `--repo <namespace>`: byt namespace (default `joafri`).
- `--no-push`: bygg utan push.

Beteende:

- Läser `Apps/<app-id>/docker-compose.yaml`.
- Bygger alla services med `build:` om `--component` inte anges.
- Läser arkitekturer från `x-casaos.architectures`.
- Bygger per arkitektur och skapar manifest-tag.
- Fail-open per arkitektur (varning i slutet om någon arch misslyckas).

### `build-appstore-zip.sh`

Bygger appstore-zip (inklusive `.yaml` -> `.yml` export i staging).

```bash
./scripts/build-appstore-zip.sh
```

Bygg och publicera `dist/` till `main`:

```bash
./scripts/build-appstore-zip.sh --push
```

Viktiga flaggor:

- `--push`: byter till `main`, `git add dist/`, commit `Updated appstore`, push `origin main`.
- `--strict-images`: fail-closed om någon image i apparna saknas online.

Image-verifiering:

- Scriptet verifierar alla `image:` i `Apps/*/docker-compose.yaml` (skippar `_template`) via registry-manifest.
- Standardläge: fail-open (varningar skrivs ut, zip byggs ändå).
- CI/Gitea-runner (`CI=true` eller `GITEA_ACTIONS=true`): scriptet blir automatiskt strikt och returnerar felkod om någon image saknas.

### `discover-zima-repos-and-apps.sh`

Hämtar appstore-repon från en ZimaOS-host via SSH (auto scan av kända CasaOS/ZimaOS-paths), validerar repo-zippar och skriver en inventerings-YAML.

```bash
./scripts/discover-zima-repos-and-apps.sh \
  --host 10.0.1.10 \
  --user root \
  --out artifacts/zima-repo-app-inventory.yaml
```

Med explicit extra repo-URL (om host-scan missar något):

```bash
./scripts/discover-zima-repos-and-apps.sh \
  --host 10.0.1.10 \
  --repo-url https://example.org/my-appstore.zip \
  --out artifacts/zima-repo-app-inventory.yaml
```

Endast manuella repo-URL:er (utan SSH-scan):

```bash
./scripts/discover-zima-repos-and-apps.sh \
  --host 10.0.1.10 \
  --skip-host-scan \
  --insecure-tls \
  --repo-url https://example.org/my-appstore.zip \
  --out artifacts/zima-repo-app-inventory.yaml
```

`--insecure-tls` ska bara användas när CA-kedja saknas i den miljö där scriptet körs.

Output innehåller:

- `repositories[]`: repo-URL, källa (host-scan/manual), status och felorsak.
- `apps[]`: `app_id`, `title`, `repo_url` och normaliserade `images`.

### `map-unraid-images-to-zima-apps.sh`

Mappar en lista av Unraid-image-referenser mot inventerings-YAML från discovery-scriptet.

```bash
./scripts/map-unraid-images-to-zima-apps.sh \
  --unraid-images /tmp/unraid-images.txt \
  --inventory artifacts/zima-repo-app-inventory.yaml \
  --out artifacts/unraid-to-zima-map.yaml
```

Output innehåller:

- `mapping[]` per image med `match_status` = `found`, `missing` eller `ambiguous`.
- `matched_apps[]` med träfforsaker (`image_exact`, `image_basename`, `name_alias`).
- `summary` för total/found/missing/ambiguous.

## Säkerhetsriktlinjer

- Undvik privilegierad container, host network och `docker.sock` om det inte är absolut nödvändigt.
- Håll mounts snäva och appspecifika (`/DATA/AppData/$AppID/...`).
- Sätt `security_opt: ["no-new-privileges:true"]` där det är möjligt.
- Dokumentera avvikelser från säkra default-värden i appens `README.md`.