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.

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.

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.