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

.
├── 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:

./scripts/validate-appstore.sh

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

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

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

./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:

./scripts/validate-appstore.sh

Strikt riskdokumentationskontroll:

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

build-and-push-image.sh

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

./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).

./scripts/build-appstore-zip.sh

Bygg och publicera dist/ till main:

./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.

./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):

./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):

./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.

./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.