# AppStore guidelines

How to build a good listing for the Yundera AppStore: how Maison runs an app, the conventions
the store follows, worked examples, and recommendations.

**[CONTRIBUTING.md](CONTRIBUTING.md) is the checklist a listing must pass.** It is what a
review, human or Touchstone, decides go / no-go on. This document explains how to meet it, and
names the requirement each section serves as `` `requirement-id` ``. Anything here that is not a
requirement is a recommendation: worth following, and never a reason on its own to refuse an app.

Maison's own docs are the reference for how each `x-compose-app` key behaves:

- [`docs/x-compose-app.md`](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md) — the app manifest
- [`docs/migrations.md`](https://github.com/Yundera/Maison/blob/main/docs/migrations.md) — data migrations
- [`docs/app-env.md`](https://github.com/Yundera/Maison/blob/main/docs/app-env.md) — the variables an app receives

- [Testing and submitting](#testing-and-submitting)
- [Repository layout](#repository-layout)
- [The compose file](#the-compose-file)
- [Data and permissions](#data-and-permissions)
- [Resources](#resources)
- [Routing: `routes` and the shared network](#routing-routes-and-the-shared-network)
- [Publishing host ports](#publishing-host-ports)
- [Authentication](#authentication)
- [Maison and `x-compose-app`](#maison-and-x-compose-app)
- [Rationale (`rationale.md`)](#rationale-rationalemd)
- [Images and languages](#images-and-languages)

## Testing and submitting

*Requirements:* `install` `app-url` `works-immediately` `auth-gate` `clean-boot` `zero-config` `data-persistence`

1. **Get the compose working by hand.** Start from a plain `docker-compose.yml` and make it
   run with `docker compose up -d` on any machine.
2. **Run it on a PCS.** Copy the app folder to `/DATA/AppData/<app>/` on a PCS. Add the
   metadata, write a `.env` with the [system variables](#system-variables), and run
   `docker compose up -d` there over SSH. This is what Maison does at install time: it copies
   your compose byte-for-byte and never edits it. The only files it adds are the app's `.env`
   and a `docker-compose.override.yml` holding the extra domains the box answers on. If the
   app works by hand with a real `.env`, it works as an installed app.
3. **Test the listing.** Push the app to `Apps/<AppName>/` on your fork. Then add your fork as
   a store in Maison (**Settings → App stores**) using its archive URL:
   ```
   https://github.com/<you>/AppStore/archive/refs/heads/<branch>.zip
   ```
   Install from that store. This tests what step 2 cannot: the metadata, the icon, the
   `seed/` tree, `folders`, `secrets` and `steps`. Then test uninstall + reinstall, and an
   update over the previous version's data.
4. **Open a PR** against `main`, with the [CONTRIBUTING.md](CONTRIBUTING.md) checklist filled in. Asset paths are
   relative, so nothing needs rewriting when the PR is merged.

Test on amd64 and arm64 when the image supports both.

## Repository layout

```
AppStore
├─ Apps/                 # one folder per app
├─ category-list.json    # store categories
├─ recommend-list.json   # apps recommended on the store front
├─ store.json            # store name shown in Maison
├─ psd-source/           # PSD templates for icons, thumbnails and screenshots
└─ scripts/              # helpers (gen-thumbnail.sh)
```

An app folder:

```
Apps/MyApp
├─ docker-compose.yml   # required
├─ icon.png             # required
├─ screenshot-1.png     # required; more are welcome
├─ thumbnail.png        # optional, see Images and languages
├─ seed/                # optional: the app's initial files, mirroring /DATA/AppData/<app>/
├─ scripts/             # optional: `.sh` files a script entry names with `file:`
└─ rationale.md         # required when the app takes an exception
```

## The compose file

*Requirements:* `name-regex` `pinned-image-tag`

- The top-level `name` is the **store app ID**. It must be unique across the store and match
  `^[a-z0-9][a-z0-9_-]*$`. Use the same value for `x-compose-app.id` and as the data folder
  name under `/DATA/AppData/`.
- Pin every image to a specific version.
  [Why `:latest` is wrong](https://github.com/IceWhaleTech/CasaOS-AppStore/issues/167).
- Locale keys are lowercase: `en_us`, `fr_fr`.

### Store info

*Requirements:* `app-metadata-coherence` `description` `architectures`

The store card and the dashboard tile are described in `x-compose-app`:

```yaml
x-compose-app:
  schema_version: 2
  id: syncthing                   # = the compose `name`
  title:                          # a plain string, or one entry per locale
    en_us: Syncthing
  tagline:
    en_us: Continuous file synchronisation between your devices.
  description:
    en_us: Syncthing synchronizes files between two or more computers in real time.
  developer: Syncthing
  category: Backup
  icon: icon.png                  # a path beside the compose
  thumbnail: thumbnail.png
  screenshots:
    - screenshot-1.png
  architectures: [amd64, arm64]
  tips:                           # Markdown, shown from the tile menu
    en_us: |
      Anything the user should know after installing.
  routes:                         # how the app is reached; see Routing
    - { service: syncthing, name: syncthing, upstream-port: 8384 }
```

**Mirror the same values in an `x-casaos` block.** Maison reads `x-compose-app` and ignores
`x-casaos` when both are present. CasaOS, and Maison builds older than `x-compose-app`-only
support, read only `x-casaos`, and an app without it disappears from their catalog. Keep the
two blocks equal:

| `x-compose-app` | `x-casaos` |
|---|---|
| `id` | `store_app_id` |
| `title`, `tagline`, `description`, `developer`, `category`, `icon`, `thumbnail`, `architectures` | same names |
| `screenshots` | `screenshot_link` |
| `tips` | `tips.before_install` |
| `routes` (the first one) | `hostname` (`<name>-${domain}`) / `index` (its `path`) |
| — | `webui_port` (the exposed web UI port) |
| — | `main` (the first route's service; CasaOS only, Maison does not read it) |
| `requires: [public-ip]` | `tags: [..., "needs-public-ip"]` |
| `resources` | — (`min_memory`, in MB, is the closest; prefer `resources`) |
| `cost`, `accounts`, `inputs`, `audience` | — (no CasaOS equivalent; say it in `description` too) |
| — | `tags` (topical tags have no `x-compose-app` key) |

Rules:

- **Don't raise `schema_version` above 2.** A Maison build that predates the declared version
  drops the whole `x-compose-app` block, including `folders` and `secrets`.
- Don't write the per-service `x-casaos.envs` / `volumes` / `ports` / `devices` description
  lists. Nothing reads them. Anything the user must know goes in `description`, `tips` or
  `rationale.md`.
- `requires` and `resources` are described in [Requirements](#requirements). `min_memory` (MB)
  is superseded by `resources.min.memory`.
- `cost`, `accounts`, `inputs` and `audience` are described in
  [What the user brings](#what-the-user-brings).

Field reference: [Maison `x-compose-app.md` › Fields](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#fields).

### System variables

*Requirements:* `portable-references`

Maison writes these into the app's `.env` at install and refreshes them on every start.
Maison never edits your compose file, so a variable reaches your app only if your compose
references it.

| Variable | Value |
|---|---|
| `APP_NET` | The shared network apps join (`pcs` on a PCS). Always write `${APP_NET:-pcs}`. |
| `DATA_ROOT` | The data folder as the **Docker host** sees it, normally `/DATA`. Always write `${DATA_ROOT:-/DATA}` as the prefix of every bind source. |
| `APP_DOMAIN` | The domain root, e.g. `alice.nsl.sh`. Use it for what is really the domain (`admin@${APP_DOMAIN}`), not to spell the app's own address. |
| `APP_URL` / `APP_HOST` | The app's own address: an origin (`https://myapp-alice.nsl.sh`, no trailing slash) and its host. Set by a Maison that knows the app's routes, so always write it with today's spelling as the fallback: `${APP_URL:-https://myapp-${APP_DOMAIN}}`. See `own-address` in CONTRIBUTING. |
| `ROUTE_<NAME>_URL` / `ROUTE_<NAME>_HOST` | The same for each further host the app routes (`hubsassets` → `ROUTE_HUBSASSETS_HOST`). |
| `APP_PUBLIC_IP_DASH` | The public IPv4 with dashes, as the box's IP-based domains spell it. |
| `APP_EMAIL` | The admin email, `admin@<domain>`. |
| `AppID` | The app's compose `name`. |
| `PUID` / `PGID` | The owner of user files, usually `1000:1000`. |
| `TZ` | The system timezone. |
| `APP_DEFAULT_PASSWORD` | **Legacy, do not use.** One password shared by every app on the box. Installed apps keep it; new apps declare their own [secrets](#3-credentials). |

`APP_NET` and `DATA_ROOT` differ between deployments, so writing them as references keeps
the app portable. The `:-default` keeps a hand-run `docker compose up` working before
Maison has written a `.env`. In this document, `/DATA/...` is shorthand for the data folder.
In a bind source, always write the variable.

```yaml
services:
  myapp:
    environment:
      BASE_URL: ${APP_URL:-https://myapp-${APP_DOMAIN}}
      TZ: $TZ
    volumes:
      - ${DATA_ROOT:-/DATA}/AppData/$AppID/data:/app/data
```

Full list and precedence: [Maison `app-env.md`](https://github.com/Yundera/Maison/blob/main/docs/app-env.md).

## Data and permissions

*Requirements:* `data-under-datadir` `permissions` `state-persistence` `broad-mount-disclosure`

```
/DATA/
├── AppData/
│   └── <app>/          # the app folder: docker-compose.yml, .env, and all app data
├── Documents/          # user files, owned by PUID:PGID
├── Downloads/
├── Gallery/
└── Media/
```

**The app folder** (`/DATA/AppData/<app>/`) holds the compose, its `.env` and every byte of
app state: config, databases, caches. It is what Maison backs up, archives on uninstall and
restores. Map all persistent data into it.

**User folders** (`Documents`, `Downloads`, `Gallery`, `Media`) are browsed and edited by
people. Anything an app writes there must be owned by `PUID:PGID` and have readable names.

### `user:`

Maison does not rewrite your compose, so a service with no `user:` runs as whatever its
image says, often root. Say what you mean:

| The service writes to | Use |
|---|---|
| A user folder (alone, or together with its app folder) | `user: $PUID:$PGID`. Mandatory. |
| Only its own app folder | `user: $PUID:$PGID` preferred, so the owner can edit the config. Root is acceptable. |
| Needs root and also writes to user folders | Split it into two services, or justify it in `rationale.md`. |

A directory the app needs before its first start must be declared under
[`folders`](#folders) so it exists with the right owner. Otherwise Docker creates a missing
bind source as an empty root-owned directory, and an app running as `PUID:PGID` then gets
"permission denied" on first start.

```yaml
services:
  filemanager:
    image: filebrowser/filebrowser:v2.63.2
    user: $PUID:$PGID
    volumes:
      - ${DATA_ROOT:-/DATA}/AppData/$AppID/config:/config
      - ${DATA_ROOT:-/DATA}/Documents:/srv/documents
      - ${DATA_ROOT:-/DATA}/Media:/srv/media:ro      # read-only when the app only reads
```

### Persistence

- **Reinstall must reuse existing data.** Every step that creates a default must first check
  whether the data already exists. Use `seed/` (create-if-absent), or a [step](#5-imperative-work-steps)
  guarded on the data itself (`[ -e "$APP_DIR/…" ] && exit 0`).
- **Container startup must never erase or overwrite user data.**
- **Upgrades must not corrupt or downgrade data.** The store serves only the latest version, so
  a user can jump several releases in one update. If the image cannot convert the data on its
  own, ship a [data migration](#version-data_version-and-migrations).

## Resources

*Requirements:* `cpu-shares` `log-limits`

**`cpu_shares` is mandatory on every service.** It is a relative weight that only matters
under load, and it is a top-level service field (not under `deploy:`):

| Weight | Use for | Examples |
|---|---|---|
| 100 | Reserved for the system | — |
| 90 | Admin tools that must stay responsive | dashboards, monitoring |
| 80 | Interactive web front ends, proxies, AppShield sidecars | most web UIs |
| 70 | Interactive apps with heavy background work | Nextcloud, databases behind an interactive app |
| 50 | Default | most services |
| 30 | Background services | backup jobs, schedulers |
| 20 | Heavy batch work | ML inference, transcoding |
| 10 | Reserved for system maintenance | — |

**A memory limit is recommended on every service.** It stops one misbehaving app from
pushing the whole box into swap. Size it from observed use with headroom, rather than from
the image's documentation.

```yaml
services:
  myapp:
    image: myapp:1.2.3
    cpu_shares: 80
    deploy:
      resources:
        limits:
          memory: 512M
```

**A log limit is mandatory on every service.** Docker's default `json-file` log never
rotates, and the PCS sets no host-wide default: the limit has to be in the compose. Declare
it once as an `x-logging` anchor before `services:` and reference it from each service. Keep
`max-size` meaningful on its own: Podman honours it but may ignore `max-file`. Raise it only
for an app whose logs you need to keep, and say why in a comment.

```yaml
x-logging: &logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  myapp:
    image: myapp:1.2.3
    cpu_shares: 80
    logging: *logging
```

## Routing: `routes` and the shared network

*Requirements:* `routes-wiring` `container-name`

A listing says **what** is reachable, never **how**. Each host the app answers on is one entry of
`x-compose-app.routes`; the box's routing setting decides the rest, and Maison writes it — on a
Yundera PCS, Caddy labels on every domain the box has (its own, nip.io, sslip.io, the ip zone);
at home, a published port; behind someone else's proxy, nothing but a route table. So a listing
carries no proxy label, no domain and no TLS setting.

```yaml
name: immich
services:
  immich:
    image: ghcr.io/immich-app/immich-server:v1.135.3
    container_name: immich
    expose:
      - 2283
    networks:
      - pcs
      - immich-internal
  immich-db:
    image: postgres:16.13-alpine
    container_name: immich-db
    networks:
      - immich-internal       # never on pcs: only its siblings talk to it

networks:
  pcs:
    name: ${APP_NET:-pcs}
    external: true
  immich-internal:
    driver: bridge

x-compose-app:
  routes:
    - { service: immich, name: immich, upstream-port: 2283 }

x-casaos:
  main: immich
  webui_port: 2283
```

| Field | Meaning |
|---|---|
| `service` | The service that answers. Default: the only service. |
| `name` | The host's leading label (`immich` → `immich-alice.nsl.sh` on a PCS). Default: the app id. |
| `upstream-port` | The port **inside** the container. Must be in its `expose:`. |
| `path` | Where the web UI opens (`/webui/`), for the first route. Default `/`. |
| `upstream-scheme`, `insecure-upstream` | `https` and `true` for a backend that only speaks self-signed HTTPS. |

The rules that must hold together:

- The **first route is the web UI**: the tile opens it, and its address is `APP_URL`. There is
  no `webui-host` / `webui-path` beside `routes`.
- `x-casaos.main` names the first route's service, and `x-casaos.webui_port` its port. CasaOS
  takes the app's identity and health from it; Maison does not read it.
- Every service attached to `pcs` sets `container_name`: lowercase letters, digits and `-`,
  not starting with a digit. The proxy resolves the upstream by container name.
- A route's name starts with the app id. Never take a name the platform uses itself: `auth`,
  `local-auth`, `auth-console`, `mesh-console`, `maison`, `admin`.
- Any port works. The URL stays clean whatever the backend port is.

An app that serves more than one hostname (its own Dex, for example) gives each its own route
(`Apps/Outline`); a route other than the first reads its address back as `ROUTE_<NAME>_URL`.
Anything beyond host → one port — dispatch by path, an auth hook, a redirect, a header fix —
is the app's own nginx router (`in-app-router` in CONTRIBUTING; `Apps/Seafile`,
`Apps/Vaultwarden`).

### Shared-network hygiene

*Requirements:* `network-isolation`

`pcs` is one flat network shared by every app on the box, and so is its DNS: service names and
container names resolve across apps. Two apps that each attach a service called `db` can
cross-resolve, and one app's web tier can end up talking to another app's database.

- **Attach only what needs outside reachability**: route services, and anything
  another app talks to. Databases, caches and workers go on an app-internal
  `driver: bridge` network.
- **Prefix what you attach**: use `outline-dex`, not `dex`, for both the service name and
  `container_name`.

## Publishing host ports

*Requirements:* `no-published-web-port`

`expose:` covers every HTTP port. **Never publish a web UI port.** The platform's proxy already
reaches the container over `pcs`, so a published UI port is a second way in that skips the certificates
and the login gate. On an AppShield app, never publish the backend's HTTP port.

**`ports:` is legitimate for traffic an HTTP proxy cannot carry**, when peers or clients must
dial the box directly:

| App | Published | Why |
|---|---|---|
| `Apps/Crafty` | `25500-25600/tcp`, `19132/udp` | Minecraft Java + Bedrock |
| `Apps/Factorio` | `34197/udp` | Factorio multiplayer |
| `Apps/Hubs` | `40000-40050/tcp+udp` | WebRTC media |
| `Apps/Kubo` | `4001/tcp+udp` | IPFS swarm |
| `Apps/MetaWatch` | `4003/tcp`, `4004/tcp` | libp2p (share, search) |
| `Apps/Radicle` | `8776/tcp` | Radicle peer-to-peer |
| `Apps/WireGuardEasy` | `51820/udp` | WireGuard |
| `Apps/AnnasTorrents` | `6881/tcp+udp` | BitTorrent peers + DHT |
| `Apps/qBittorrent` | `6881/tcp+udp` (commented out) | same, but the client works without it |

Samba publishes nothing by default: SMB belongs on a VPN address, which the owner adds through
the app's override.

- Publish **only** the non-HTTP ports, and add a comment beside each one saying what it is for.
- Use fixed ports that stay clear of the host's own (`22`, `80`, `443`). Two apps that publish
  the same port cannot run side by side.
- A published port is open to the internet with no SSO in front. Make sure nothing else the
  container listens on is reachable through it.
- **Ship the port enabled if the app needs it to work.** Comment it out only when it is a pure
  enhancement, and say in `tips` what to uncomment.

## Requirements

*Requirements:* `requires-public-ip` `resources-declared` `architectures`

What the app needs from the box. Maison uses it to decide what the store shows on each box:

```yaml
x-compose-app:
  architectures: [amd64, arm64]
  requires: [public-ip]               # public-ip | gpu-nvidia | gpu-dri
  resources:
    min:         { memory: 2G }       # only for a real floor
    recommended: { cpu: 2, memory: 4G }
```

- **`requires`** lists what the app **cannot work without**. Maison hides the app on a box
  that lacks one, and asks the owner to confirm before installing it anyway.
  - `public-ip`: inbound connections from the internet reach the host. A PCS behind CGNAT, or
    one routed through the mesh-router WireGuard tunnel, gets its HTTPS routes from the gateway
    but has no reachable address for raw TCP/UDP. There the app installs and starts, then
    quietly fails: a torrent client with no inbound peers, a game server nobody can join. Every
    app that publishes a port on every address needs it, and `maison lint` checks this.
  - `gpu-nvidia`: the app reserves an NVIDIA GPU (`deploy.resources.reservations.devices`).
  - `gpu-dri`: the app needs `/dev/dri` for video acceleration.
  - An app that only runs **better** with something lists nothing. A media server that falls
    back to CPU transcoding does not `require` a GPU.
- **`resources`** states the box the app wants, in compose sizes (`512M`, `4G`).
  - `recommended`: below it the store shows a note. Declare it on any app whose service limits
    add up to 2G or more, or that has an uncapped service. Base it on those limits plus the
    `rationale.md` notes.
  - `min`: below it, installing asks for confirmation. Set it only for a floor the app
    documents, such as Immich's 4G.
- Keep the CasaOS mirror: `needs-public-ip` stays in `x-casaos.tags`. CasaOS shows it, and a
  Maison that reads only `x-casaos` translates it to `requires: [public-ip]`.

## What the user brings

*Requirements:* `user-prerequisites`

[Requirements](#requirements) say what the **box** must have. These four fields say what the
**user** must bring. They are independent: declare each one that applies.

```yaml
x-compose-app:
  cost: paid                          # free (default) | freemium | paid
  accounts:
    - provider: foundryvtt.com        # as a user would recognise it
      url: https://foundryvtt.com/
  inputs:
    - env: FOUNDRY_USERNAME
      label: { en_us: "foundryvtt.com username" }
      required: true
    - env: FOUNDRY_PASSWORD
      label: { en_us: "foundryvtt.com password" }
      secret: true
      required: true
  audience: technical                 # everyone (default) | technical
```

- **`cost`**: `paid` when the app is not useful until something is bought (a licence, an AI
  provider's subscription or API credit, a Usenet provider). `freemium` when it is useful for
  free and sells extras (Plex Pass). Omit it for a free app. Maison shows a badge; it never hides
  the app.
- **`accounts`**: every third-party account the user needs, an identity provider the user
  doesn't control: plex.tv, foundryvtt.com, Anthropic, Trello, a Discord or Telegram bot. Not an
  account on another app of the same box. Maison shows it; it never hides the app. This is what
  the audit's third-party exception reads (`zero-config`, `works-immediately`); no `rationale.md`
  is needed for it.
- **`inputs`**: values only the user can provide and the app cannot start usefully without: an
  account's credentials, a key a vendor issued, a claim token. Maison asks for them in the install
  dialog, writes them to the app's `.env` under `env`, and shows **Setup needed** on the tile while
  a `required` one is empty. The compose reads them as `${KEY:-}`. Mark keys and passwords
  `secret: true`. Anything Maison can generate is a `secrets` entry, never an input.
  Don't send the user to the Env tab in `tips` for a value an input can ask for.
- **`audience: technical`**: root- or host-level apps (a root shell, a host-root file browser, a
  host-network VPN, anything given the Docker socket to administer the box) and developer or
  AI-agent tooling (MCP servers, coding agents). It hides the app unless the owner turned on
  *Show technical apps*. It is about who the app is for, not about risk: an app that mounts
  `/DATA/Media` or `/DATA/Documents` — a file browser, a media player — is an everyday app.

## Authentication

*Requirements:* `auth-default` `appshield-wiring`

A login gate enabled by default is **mandatory**. Acceptable gates:

- **AppShield** (recommended): an SSO sidecar that plugs into the PCS's built-in login.
- The app's own login, protected by a [generated credential](#3-credentials).
- An onboarding flow that creates the first account on first visit (e.g. Jellyfin). This
  needs a `rationale.md` explaining why the window before the first account is created is
  acceptable: that the app's own login is mandatory once the account exists, why no
  credential can be generated for it, and what happens to a later sign-up (refused, or held
  for the admin's approval). `Apps/UptimeKuma` and `Apps/Ollama` are examples.

What `auth-default` asks is that a login is **there** as shipped, not who provides it. An app
whose own login is mandatory does not need AppShield in front of it as well.

A public website with no login also needs a `rationale.md`.

### AppShield

Put the `ghcr.io/yundera/appshield` container in front of the app. Make the sidecar the route's
service and keep the backend off the routes. The sidecar registers itself as an
OIDC client with the PCS's `auth-registrar` on first login, so there are no client IDs,
secrets or issuer URLs to configure.

References: `Apps/Spliit` (plain web UI), `Apps/Beacon` and `Apps/BrowserMCP` (MCP servers
with OAuth for machine clients).

```yaml
name: myapp
services:
  myapp-proxy:
    image: ghcr.io/yundera/appshield:3.2.0
    container_name: myapp        # = the compose name; the OIDC client id derives from it
    hostname: myapp              # = container_name; the registrar names the app from it
    restart: unless-stopped
    environment:
      BACKEND_HOST: "myapp-backend"
      BACKEND_PORT: "8080"
      LISTEN_PORT: "80"
      OIDC_REGISTRAR_URL: "http://auth-registrar:9092"
      REDIRECT_HOST_SUFFIXES: "${APP_HOST_SUFFIXES:-${APP_DOMAIN}}"
    expose:
      - 80
    depends_on:
      - myapp-backend
    cpu_shares: 80
    deploy:
      resources:
        limits:
          memory: 128M
    networks:
      - pcs                      # the proxy reaches the sidecar
      - myapp-internal           # the sidecar reaches the backend

  myapp-backend:
    image: myapp/myapp:1.2.3
    container_name: myapp-backend
    restart: unless-stopped
    expose:
      - 8080                     # no route, no ports: reachable only through the sidecar
    cpu_shares: 50
    deploy:
      resources:
        limits:
          memory: 512M
    networks:
      - myapp-internal

networks:
  pcs:
    name: ${APP_NET:-pcs}
    external: true
  myapp-internal:
    driver: bridge

x-compose-app:
  routes:
    - { service: myapp-proxy, name: myapp, upstream-port: 80 }

x-casaos:
  main: myapp-proxy              # the sidecar, never the backend
  webui_port: 80
```

| Variable | Required | Purpose |
|---|---|---|
| `BACKEND_HOST` / `BACKEND_PORT` | yes | The protected container's name and port. |
| `LISTEN_PORT` | yes | The port AppShield listens on. Matches `expose` and the route's `upstream-port`. |
| `OIDC_REGISTRAR_URL` | yes | `http://auth-registrar:9092`. Its presence enables SSO. |
| `REDIRECT_HOST_SUFFIXES` | yes | The primary domain only, as above. The gate sends the registrar its callback path and adopts the hosts the registrar returns, so it does not need — and must not guess — the platform's other zones. This one names the canonical host: the OAuth issuer, and where a login from an unrecognised host is sent. |
| `OAUTH_RESOURCE` | optional | Enables AppShield's OAuth 2.1 broker on exactly the path in the URL (e.g. `${APP_URL:-https://myapp-${APP_DOMAIN}}/mcp`). This is the machine/API path for MCP servers. |
| `OAUTH_SCOPE` | optional | The scope the resource advertises (default `access`; MCP apps use `mcp`). |
| `OAUTH_DATA_DIR` | optional | Set to `/data/oauth` and bind-mount `${DATA_ROOT:-/DATA}/AppData/<app>/oauth` there, so registered clients survive redeploys. |

What a review checks for an AppShield app is `appshield-wiring` in
[CONTRIBUTING.md](CONTRIBUTING.md#appshield-wiring--the-sso-sidecar-is-wired-so-it-cannot-be-bypassed).
The two that catch people out are `hostname:` and `x-casaos.main`:

- `auth-registrar` identifies the app by its container's PTR record and rejects redirect URIs
  that don't match it. If `hostname:` is missing, Docker uses the random container ID and
  registration fails at first login. The service name itself may differ from the container name.
- If `x-casaos.main` names the backend, CasaOS takes the app's health from the backend: the
  tile can show green while the public route returns 502.

**Don't copy these from older apps:**

- `AUTH_HASH` / `/?hash=…`: a CasaOS-era token. Maison never generates it, so it resolves to
  an empty string.
- `ALLOWED_PATHS` for machine clients: with no hash, this leaves the path open to anyone. Use
  `OAUTH_RESOURCE`.
- `CREDENTIAL_VALIDATE_URL`: pointed at a CasaOS bridge that no longer exists.
- `USER` / `PASSWORD: $APP_DEFAULT_PASSWORD` as an extra basic-auth gate. If you need one, use
  an app [secret](#3-credentials).

On the PCS, `auth-registrar` and the login service run in the mesh template's `auth` stack.
If they are missing, the sidecar logs `ENOTFOUND auth-registrar` at first login.

## Maison and `x-compose-app`

`x-compose-app` is Maison's definition of an app. Maison reads **one block or the other,
never both**:

```
compose has x-compose-app  →  x-compose-app only (x-casaos beside it is ignored)
otherwise                  →  x-casaos, translated whole (plain CasaOS apps)
```

So a field that exists only in this store's `x-casaos` block is invisible to Maison. That is
why [store info](#store-info) lives in `x-compose-app` first.

Declare `schema_version: 2`, which `folders` and `steps` require. The other keys (`secrets`,
`variables`, `credentials`, `files`, `lifecycle`, `backup`, `migrations`) are
additive and don't raise it.

### The stack-up sequence

**Every** `docker compose up` Maison runs goes through this sequence: install, start, update,
and saving the app's settings:

```
folders → secrets → variables → setup steps → seed → files
        → docker compose up -d → started steps
```

An update that raises `data_version` also runs each pending [migration](#version-data_version-and-migrations)
once, between `variables` and the setup steps.

An install is this same sequence: nothing runs only on install. Work for a fresh install is a
`run: once` [step](#5-imperative-work-steps).

Everything before `docker compose up` is **fatal**: an app whose secret could not be
generated, whose config could not be rendered, or whose setup step failed, does not start.
A failing started step is logged and retried on the next up.

Reference: [`x-compose-app.md` › The stack-up sequence](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#the-stack-up-sequence).

### `folders`

*Requirements:* `declared-folders`

```yaml
x-compose-app:
  schema_version: 2
  folders:
    - /DATA/AppData/$AppID/config            # shorthand: owner PUID:PGID, mode 0755
    - path: /DATA/AppData/$AppID/db
      user: "999"
      group: "999"
      mode: "0700"                           # must be quoted
    - path: /DATA/Media
      recursive: true                        # also re-own what is already inside
```

Maison creates each folder with its owner before any image is pulled and before every up.
It does **not** read `volumes:` to guess which bind sources are directories, so a directory
your app needs is a directory your app declares. Paths are written with `/DATA`, which Maison
maps itself. A relative path, a path outside `/DATA`, or a variable that resolves to nothing
fails the up. Use `recursive: true` only to reclaim a tree the app did not create, and never
on a large media folder that is already correct.

Reference: [`x-compose-app.md` › Folders](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#folders).

### First-run setup

Prefer the first option that fits, in this order.

#### 1. Files: `seed/`

`Apps/<AppName>/seed/` mirrors the app folder. Maison copies it at install and writes each file
**create-if-absent on every up**. A missing file comes back; a file the app or the user edited
is left alone.

```
Apps/MyApp/seed/config/init.sql       → /DATA/AppData/myapp/config/init.sql
Apps/MyApp/seed/config/app.yml.tmpl   → /DATA/AppData/myapp/config/app.yml   (rendered)
```

A `.tmpl` file is rendered with the app's variables, and an unresolved `${VAR}` fails the
install. Other files are copied byte-for-byte, keeping the exec bit. `docker-compose.yml`, the
override and `.env` may not appear in `seed/`. Seed files replace fetching assets from
jsDelivr: the store is already on the box.

#### 2. Values: `secrets` and `variables`

*Requirements:* `no-hardcoded-credentials` `per-app-secrets`

```yaml
x-compose-app:
  secrets:                                          # generated once, kept forever
    MYAPP_SECRET_KEY: hex:32
    MYAPP_DB_PASSWORD: alnum:32                     # internal, nobody types it
    MYAPP_ADMIN_PASSWORD: password:24               # a person logs in with it
    MYAPP_ADMIN_HASH: bcrypt:${MYAPP_ADMIN_PASSWORD}
  variables:                                        # re-rendered on every up
    MYAPP_URL: ${APP_URL:-https://myapp-${APP_DOMAIN}}
```

The generators are `hex:N`, `base64:N`, `alnum:N`, `password:N`, `uuid` and `bcrypt:TEXT`.
A secret is written to the app's `.env` once and survives restarts, updates and restores.
Use **one secret per purpose**: the database password is never the login password.

Never generate a credential in a step: declare it under `secrets`. A key no generator can
produce (an RSA keypair) is the exception; see `Apps/Wger`.

**Converting an app that used `$APP_DEFAULT_PASSWORD`.** Installed boxes already initialised
their database with that value, so a fresh secret would not match it. Seed the secret from the
old value instead:

```yaml
  secrets:
    MYAPP_DB_PASSWORD: ${APP_DEFAULT_PASSWORD}|alnum:32
```

Installed apps keep their value; fresh installs get a generated one.

Reference: [`x-compose-app.md` › Secrets and variables](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#secrets-and-variables).

#### 3. Credentials

*Requirements:* `credentials-shown`

Show the login Maison generated. It appears, masked and with copy buttons, the first time the
app is opened and from its tile menu:

```yaml
x-compose-app:
  credentials:
    - label: Administrator
      username: admin
      password: ${MYAPP_ADMIN_PASSWORD}
      change:
        apply: script
        script: |
          compose exec -e MYAPP_ADMIN_PASSWORD myapp \
            myapp-cli user set-password admin
```

Add `change` when the password can be replaced after install. The owner then changes it from
the app's **Security** tab in Maison:

- `apply: env`: the app re-reads the variable on **every** start. Maison writes `.env` and
  recreates the container. If the value only reaches a container through a rendered file, give
  that container a label carrying the secret so the recreate happens (`Apps/Outline`,
  `Apps/Filestash`).
- `apply: script`: the app keeps its own copy (a user table) but has a command to change it.
  The [script entry](#the-script-entry) runs against the running app and gets the **new**
  value in the secret's own variable (`OLD_<NAME>` holds the previous one). Pass it with the bare `-e NAME` form so it
  never appears on a command line, and exit non-zero when nothing changed (`Apps/Nextcloud`,
  `Apps/Guacamole`, `Apps/WireGuardEasy`).
- No `change`: the value is read only at first boot and nothing can reset it.

`change.policy` (length, charset, required classes) is optional. Only a value declared under
`secrets` can be changed.

`tips` no longer needs a password table.

Reference: [`x-compose-app.md` › Changing a credential](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#changing-a-credential).

#### 4. A file that tracks the deployment: `files`

`seed/` is create-if-absent. When a config embeds a value that can change, such as a domain,
declare it so it is re-rendered on every up:

```yaml
x-compose-app:
  files:
    - path: /DATA/AppData/myapp/element/config.json
      from: element/config.json.tmpl    # a path in seed/
      ensure: always                    # `once` (default) = create-if-absent
      mode: "0640"
```

#### 5. Imperative work: `steps`

*Requirements:* `step-idempotency` `step-security` `step-scope`

What is left once the four declarations above are used: work that needs the app's own binary
(seeding its database), a running service (an API call, `occ`), another program's output
(waiting for it to write its config, then patching it), or the host.

```yaml
x-compose-app:
  steps:
    - name: init-db
      at: setup            # setup | started
      run: always          # once (default) | always
      script: |
        [ -e "$APP_DIR/db/database.db" ] && exit 0
        docker run --rm --user "$PUID:$PGID" -v "$APP_DIR/db:/db" \
          filebrowser/filebrowser:v2.63.23 config init --database /db/database.db
    - name: configure
      at: started
      run: once
      script: |
        compose exec nextcloud php occ background:cron
```

| `at` | Runs | On failure |
|---|---|---|
| `setup` | Before the stack starts: after `secrets` and `variables`, before `seed` and `files`. | **fatal**: the app does not start |
| `started` | After `docker compose up` returns. The containers have started; the app may still be booting, so wait for it. | logged; retried on the next up |

| `run` | |
|---|---|
| `once` | Until it succeeds once. The marker is `.init/<name>` in the app folder, so it travels with the backup, but an uninstall-keep-data removes it. When the step must follow the *data*, use `always` and guard on the data. |
| `always` | On every up: install, start, update, config save. It must be idempotent. |

Steps run in the order written, `setup` ones first.

#### The script entry

A step, a [migration](#version-data_version-and-migrations) step and a
[credential change](#3-credentials) all run the same thing: a **script entry**, through the
same runner. Only *when* it runs differs. What a script can do in one place, it can do in the
other two.

| Key | |
|---|---|
| `script` | Inline bash. |
| `file` | Instead of `script`: a `.sh` under the app's `scripts/` folder (`file: scripts/patch.sh`), copied with the app on install and update. For anything long enough to want its own file and `shellcheck`. |
| `images` | Images the script runs, pulled with the app's own images before anything is stopped. Optional; required in practice for a migration, which runs after the stop. |
| `timeout` | Go duration. Defaults: step 10m, migration 2h, credential change 2m. |

| In | Its own keys | Runs | On failure | Extra variables |
|---|---|---|---|---|
| `steps` | `name`, `at`, `run` | every up | `setup`: the app does not start. `started`: logged, retried | — |
| `migrations` | `id`, `name` (or `blocked`) | once, in the update that crosses `id` | the update is rolled back | `MIGRATION_ID`, `DATA_VERSION_FROM`, `DATA_VERSION_TO` |
| `credentials[].change` | `apply: script`, `policy` | when the owner changes the password | nothing changes | `<NAME>` (the new value), `OLD_<NAME>` |

`MAISON_OUTPUT` and `MAISON_ENV` (below) exist in all three places. `$MAISON_ENV` always
reaches the `.env`; `$MAISON_OUTPUT` reaches whatever runs or renders after the script in
the same up, so it has no reader in a credential change.

**Where a script runs.** `bash -euo pipefail` **inside the Maison container**, in the app folder,
with `docker` talking to the **host** daemon. The environment holds the app's `.env`, the
[system variables](#system-variables), `AppID`, `APP_DIR` (the app folder), `DATA_ROOT`,
`COMPOSE_PROJECT_NAME` / `COMPOSE_FILE`, `MAISON_OUTPUT` / `MAISON_ENV`, and the extra
variables above. The script is not interpolated: write `$VAR`, never `$$VAR`.
Don't use `${VAR:?}`, which `docker compose` rejects when it reads the file.

**Paths.** Maison mounts `DATA_ROOT` at the same path the host uses, so `$APP_DIR/db` is
right both for the shell (`[ -e … ]`, `cat`) and for `docker run -v`. Write `$APP_DIR`, not
`/DATA/AppData/<app>`.

**Talking to the app.** `compose` is `docker compose` bound to the app's project:
`compose exec <service> …`, `compose restart <service>`. `exec` never allocates a TTY and
passes stdin, so `printf … | compose exec database psql …` works.

**Running a tool in an image.** Pass values with `-e`, never by splicing them into the inner
script, and quote the heredoc so nothing is expanded twice:

```bash
docker run --rm -i --entrypoint sh --user "$PUID:$PGID" \
  -v "$APP_DIR/config:/out" -e CRAFTY_ADMIN_PASSWORD \
  registry.gitlab.com/crafty-controller/crafty-4:4.10.7 -s <<'SH'
set -e
printf '{"password":"%s"}' "$CRAFTY_ADMIN_PASSWORD" > /out/default.json
SH
```

**Ownership.** A file written from the script's own shell belongs to Maison's user. Appending
(`>>`) keeps the owner; `sed -i`, `>` on a new file and `mv` don't. Edit a file the app owns
from a container run as `--user "$PUID:$PGID"`, or inside the app with `compose exec`.

**Handing values on.** Write `KEY=value` lines to one of two files:

| File | Reaches | Lifetime |
|---|---|---|
| `$MAISON_OUTPUT` | later steps, `.tmpl` files and `files` | this up only; recomputed next time |
| `$MAISON_ENV` | the app's `.env`, so the compose and every later up | kept. **Adds a key only when the `.env` lacks it**, so a user edit or a generated keypair is never overwritten. |

```bash
hash=$(printf 'admin:YaCy:%s' "$YACY_ADMIN_PASSWORD" | md5sum | cut -d' ' -f1)
echo "YACY_ADMIN_HASH=$hash" >> "$MAISON_OUTPUT"   # used by seed/…/yacy.conf.tmpl
echo "RADICLE_OWNER=" >> "$MAISON_ENV"             # an empty setting shown in App settings › Env
```

Assign a command substitution to a variable first, as above: `set -e` catches a failed
`hash=$(…)`, not a failed `echo "$(…)"`.

**Commands.** Only a fixed set is available (`bash`, `docker`, `compose`, coreutils, `sed`,
`grep`, `find`, `md5sum`, `wget`, …). `openssl`, `curl`, `python`, `jq` and `git` are not: run
them in a pinned image. Host-scoped commands (`sysctl`, `ip`, `mount`, …) would only affect the
Maison container, so they are refused.

**Changing the host** goes through the Docker socket. Pin the image, and justify it in
`rationale.md`:

| To change | Recipe |
|---|---|
| Kernel parameters | `docker run --rm --privileged --network=host <image> sysctl -w <key>=<value>` |
| Network state | `docker run --rm --privileged --network=host <image> ip ...` |
| Files, users, `/etc` | `docker run --rm -v /:/host <image> chroot /host sh -c '...'` |
| Kernel modules | `docker run --rm --privileged <image> modprobe ...` |

**CasaOS.** `pre-install-cmd` / `post-install-cmd` run only for a compose with no
`x-compose-app`, as a `setup` / `started` step with `run: once`.

Worked examples: `Apps/FileBrowser` (a tool in an image), `Apps/Gitea` (`compose exec` and
waiting for the app), `Apps/YaCy` and `Apps/SeafileDrive` (`$MAISON_OUTPUT`), `Apps/Wger` and
`Apps/Hubs` (`$MAISON_ENV`), `Apps/Seafile` (patching what the app wrote),
`Apps/WireGuardEasyHost` (the host, and a step in a `file:`).

A shipped step is reviewed against `step-idempotency`, `step-security` and `step-scope`
in [CONTRIBUTING.md](CONTRIBUTING.md#4-first-run-setup-and-steps).

Reference: [`x-compose-app.md` › Steps](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#steps).

### The tile: `links`, `view`, `parent`

```yaml
x-compose-app:
  links:                        # extra buttons on the detail view, absolute URLs
    - name: Documentation
      url: https://docs.example.org
  view: service                 # apps (default) | service | system — the grid, nothing more
  parent: jellyfin              # nest this app under another app's tile
```

- The tile opens the first route (`routes`, under Routing) at its `path`. An app with no web
  UI declares no route.
- An app with no web UI lands in `service` on its own. Leave `view` alone unless the app is a
  platform piece, such as Terminal, the owner's host shell. A platform piece is `system` whether it
  ships preinstalled or comes from the store. Say why in `rationale.md`.
- `parent` is for apps that only make sense beside another one, such as a companion indexer or
  a request front end. It is presentation only. If the parent is not installed, the app shows
  as an ordinary tile.

Reference: [`x-compose-app.md` › Views](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#views).

### `lifecycle`

*Requirements:* `lifecycle-rationale`

```yaml
x-compose-app:
  lifecycle:
    stoppable: false      # Stop refused; updated without stopping; left out of "Update all"
    uninstallable: false  # Uninstall refused
    updatable: false      # outside Maison's update system entirely
```

All three default to `true`. They exist for platform stacks: the dashboard, the gateway, an
admin app that something other than Maison keeps up to date. **A store app needs a
`rationale.md` entry to set any of them to `false`.** An app the user cannot stop, remove or
update is a review question, not a default.

Reference: [`x-compose-app.md` › Lifecycle](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#lifecycle-what-the-operator-may-do-to-the-app).

### Backups

Maison backs up the app folder whole. Declare regenerable data so it isn't copied off-box every
night:

```yaml
x-compose-app:
  backup:
    exclude:
      - cache/                  # <app folder>/cache
      - data/transcodes/
      - "**/thumbs/"            # any depth; must be quoted
```

An excluded directory comes back **empty** after a restore, so list only what the app rebuilds
by itself, and declare it in `folders` if it must exist before start. Only directories are
accepted: no file globs, no negations, nothing outside the app folder.

`backup.skip: true` drops the app from backups entirely. Use it only when nothing in its folder
is worth keeping.

Reference: [`x-compose-app.md` › Backup exclusions](https://github.com/Yundera/Maison/blob/main/docs/x-compose-app.md#backup-exclusions).

### `version`, `data_version` and migrations

*Requirements:* `migrations-wellformed` `migration`

```yaml
x-compose-app:
  version: "2.4.0"      # optional, display only
  data_version: 2       # only once the app needs its first migration
  migrations:
    - id: 2
      name: postgres-15-to-17
      image: pgautoupgrade/pgautoupgrade:17.6-trixie
      environment:
        PGAUTO_ONESHOT: "yes"
        POSTGRES_USER: myapp    # = the postgres service's user; the default `postgres` fails
        POSTGRES_DB: myapp
      volumes:
        - /DATA/AppData/${AppID}/db:/var/lib/postgresql/data
```

**`version`** is optional and only displayed. Updates are detected from the compose file,
not from this field. If you set it, use the main app's image tag without a leading `v` or
variant suffix (`ghost:6.59.0-alpine` → `"6.59.0"`), quote it, and keep it in step with the tag.
For an AppShield app, use the backend's version.

**`data_version`** is the shape of the app's data: an integer that starts at 1 and rises by
exactly one per migration. Leave it out until the first migration is needed (absent means 1).

**Most updates need no migration**, because the image converts its own data on first start.
Ship one when it can't: a PostgreSQL major version, Odoo 18 → 19, a config file that moved, an
app that must boot every intermediate major version.

A step is exactly one of:
- a [script entry](#the-script-entry): `script:` inline, or `file: scripts/0002-….sh`, with
  every image it runs listed under `images:` so they are pulled while the old version still
  serves (`Apps/Guacamole`: one `docker run` of pgautoupgrade; `Apps/Odoo`: a file);
- **`blocked:`** (a message; the update is refused before anything is pulled).

Store rules:

- **Every install today starts at data version 1**, whatever version it runs: no install had a
  marker before migrations existed. So a step must **read the data and exit 0 when it is
  already converted**, the way `pgautoupgrade` checks `PG_VERSION`. Exit 0 means "applied";
  there is no "try next time".
- Use `blocked` only when the step lands together with the image bump that needs it. It cannot
  look at the data, so it would also refuse installs that are already converted. When old data
  cannot be converted automatically, use a script that checks and fails: the update is rolled
  back and the app keeps its old version. `Apps/Odoo` is the worked example (step 2 refuses
  Odoo 18 databases; step 3 is the `pgautoupgrade` above).
- **When to merge:** Maison runs steps from **v1.1.58**. Older builds ignore them and update
  straight onto the new image. So if the step lands **with** the image bump that needs it,
  wait until v1.1.58+ is on the fleet. If the store **already** ships the new image (a
  conversion that was missed), merge at once: the migration only adds protection.
- **The invariant to review against:** a fresh install at data version N must end up where an
  older install plus every migration up to N ends up. A change to what `seed/`, `files`,
  `folders` or a `run: once` step produce never reaches existing installs unless a migration carries it.

An update with pending steps always takes a rollback point, and is rolled back as a whole if
a step fails.

Reference: [Maison `migrations.md`](https://github.com/Yundera/Maison/blob/main/docs/migrations.md).

### Keys Maison writes itself

`store-ref` and `generated-routes` appear in an installed app's override file (older
installs may also carry `store` / `store-app-id`). Don't use those names for your own fields.

## Rationale (`rationale.md`)

An app that takes an exception ships `Apps/<AppName>/rationale.md`. Reviewers read it first.

It is required when the app:
- runs as root with access to user folders, or mounts anything outside `/DATA/AppData/<app>/`
  and the user folders;
- ships with no login enabled by default, or relies on first-visit onboarding;
- changes the host from a step;
- sets any `lifecycle` key to `false`;
- deviates from anything else in this document.

```markdown
# <AppName> — Rationale

## What exception is requested
<e.g. "runs as root", "no login", "mounts /DATA/Downloads read-write">

## Why it is necessary
<upstream constraint, runtime requirement, …>

## Mitigations
<resource limits, read-only mounts, disabled features, …>

## Alternatives considered
<each alternative and why it did not work>

## Data protection
<what protects user data given this exception>
```

Keep it short and factual. A reviewer should be able to decide in a minute.
`Apps/Stirling-PDF/rationale.md` is a full example.

## Images and languages

*Requirements:* `assets` `description`

Asset fields name files beside the compose (`icon: icon.png`, `screenshots: [screenshot-1.png]`).
Maison serves them from the store copy already on the box. An absolute URL still works but
is not the normal form.

| Image | Spec |
|---|---|
| `icon.png` | Required. 192×192, transparent background. |
| `screenshot-N.png` | At least one required. 1280×720, PNG or JPG, as small as possible. |
| `thumbnail.png` | Optional. 784×442 with a rounded-corner mask. Supply it only as a purpose-made tile; otherwise omit it and the store uses `screenshot-1.png`. Featured apps should have one. |

Use the [PSD templates](psd-source) to make these.

**Languages:** English (`en_us`) is mandatory for `title`, `tagline` and `description`. French
(`fr_fr`), Korean (`ko_kr`), Chinese (`zh_cn`) and Spanish (`es_es`) are recommended for
`tagline` and `description`.

## Feedback

Suggestions about this process are welcome via GitHub issues.