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
    └── 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.

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.