Add agent-first app packaging guidance and linting

- Add agent-facing README, AGENTS.md, CLAUDE.md, and repo-local skills for packaging, updating, and testing apps
- Store skills in .claude/skills/ so Claude Code can discover them natively, while AGENTS.md keeps the same instructions reachable for Codex and other agents
- Add first-party app package linter with manifest, compose, image, port, persistence, and PR-output checks
- Add GitHub Actions lint workflow plus concise PR and issue templates for app submissions and package issues
This commit is contained in:
nmfretz committed 2026-06-18 21:23:16 +10:00
1 parent b1dfd86b59
commit e0a982b877
14 files changed
+2689 -473

No files matched your search

+395
View File
@@ -0,0 +1,395 @@
---
name: umbrel-package-app
description: Use when packaging a new app for the Umbrel App Store, including upstream discovery, manifest and compose authoring, Umbrel runtime rules, persistence, and readiness for testing.
---
# Umbrel Package App
Create an Umbrel App Store package for a self-hosted app.
Keep changes scoped to the requested app unless the task explicitly requires shared changes.
## App Store Gates
- The package must open to a useful web UI, setup page, or status/connection page. If upstream is headless or CLI-only, add a browser page that shows service state, connection details, QR codes, or next steps. Users must not need SSH or CLI access for normal use.
- The app must have maintained images that support `linux/amd64` and `linux/arm64`.
- The package must be able to persist user data and required config under `${APP_DATA_DIR}`.
- Host access should be exceptional, minimal, and product-essential. App Store packages must not mount the host Docker socket or otherwise control Umbrel's Docker daemon. Privileged mode, host networking, broad host mounts, device mounts, and extra capabilities need careful justification, especially when combined.
Host Docker socket access is effectively host-root access: a container with the socket can control other containers and mount host paths. Other host privileges can also turn a packaging mistake or app compromise into a device-wide problem, especially because Umbrel runs on a user's personal server alongside their data and other apps.
## Upstream Discovery
Before writing files, understand the upstream app well enough to package it deliberately:
- Find the canonical project, website, repo, docs, license, support channel, and current stable release.
- Read the upstream Docker or self-hosting docs, including any example compose files.
- Identify the service topology: web service, internal listen port, sidecars, persistent paths, required config, and generated secrets.
- Understand the first-run experience: setup flow, login, default credentials, external accounts, companion clients, hardware, or domain/HTTPS assumptions.
- Surface packaging risks early, especially unclear licensing, stale images, fixed public URL assumptions, manual-only setup, or broad host access.
## Package Files
Create one top-level directory named after the app ID:
```text
<app-id>/
umbrel-app.yml
docker-compose.yml
exports.sh # only when needed
hooks/ # only when needed
data/.../.gitkeep # only for empty bind-mount source dirs
```
After creating the package shell, inspect similar apps in this repo for naming, app_proxy wiring, persistence paths, generated secrets, templates, hooks, widgets, and framework-specific env vars. Follow established Umbrel patterns where they fit.
## Manifest
`umbrel-app.yml` is the app manifest. umbrelOS reads it into the app-store registry, checks `manifestVersion` compatibility before install, exposes its metadata in the UI, and uses `port` plus `path` to build the app launch URL.
Use current app packages in this repo as the manifest contract. Some fields are required by umbrelOS at runtime, while others are expected for App Store metadata, review, or publishing. For new packages, use this field order:
```yaml
manifestVersion:
id:
category:
name:
version:
tagline:
description:
releaseNotes:
developer:
website:
dependencies:
repo:
support:
port:
gallery:
path:
defaultUsername:
defaultPassword:
submitter:
submission:
```
- `manifestVersion` is Umbrel app-framework compatibility, not the app's upstream version. Use `1` by default. For example, if a package relies on app-framework behavior introduced in umbrelOS 1.3, use `manifestVersion: 1.3` so older umbrelOS versions refuse the install.
- `id` is the stable app package identifier. It must exactly match the top-level directory name, use lowercase kebab-case, and be recognizable, for example `home-assistant`. umbrelOS uses it for app data, dependency references, and generated container names, so do not change it after release.
- If the app implements another Umbrel app's dependency contract, put `implements:` immediately after `id`. Use it only for real drop-in providers, for example a Bitcoin node package that can satisfy apps depending on `bitcoin`. See Dependencies for the required exports contract.
- `name` is the user-facing app name shown in the App Store and on the Umbrel home screen. Use the upstream/product name users recognize.
- `tagline`, `category`, and `description` are App Store copy. Use the current store taxonomy and make sure the wording makes sense for someone installing the app on Umbrel.
- Put important first-run setup or security notes near the top of `description`.
- Use folded YAML with `>-` for multi-line `description` and `releaseNotes`. Single line breaks are folded into spaces. To create a Markdown paragraph break, use two blank lines in the YAML source. For Markdown bullet lists, use a blank line before the list and between list items so YAML preserves the line breaks.
```yaml
description: >-
First paragraph.
Second paragraph.
- Added a faster setup flow
- Fixed login after restart
```
- `version` is the upstream app/package version users recognize. Use the released upstream version in upstream's format. If upstream has no release version, use the short commit SHA for the exact upstream commit being packaged. Do not use `latest` or a Docker image digest.
- `port` is the host-facing browser port umbrelOS uses for the app URL. For normal `app_proxy` web apps, it is the port assigned to `app_proxy`, not the app container's internal listen port, and must be unique across the App Store.
- Put the app container's real listening port in `app_proxy.environment.APP_PORT`. Example: if the web container listens on `8080` and the app should open at `http://umbrel.local:3456`, use manifest `port: 3456` and `APP_PORT: 8080`.
- `path` is appended to the app URL. Use `path: ""` for apps that launch at the root. For subpath apps, start with a leading slash and do not include the host or port, for example `path: "/admin"`.
- Use `releaseNotes: ""` for new packages.
- Include accurate `developer`, `website`, `repo`, and `support` values. In the App Store, `developer` links to `website`.
- Use `dependencies:` only for other Umbrel apps the package requires at runtime. Values are app IDs, for example `bitcoin` or `electrs`. Do not list same-package services such as Postgres, Redis, workers, or optional integrations.
- Use `permissions:` only for recognized platform or shared-storage access the app actually needs. See Permissions.
- Use `gallery: []` for new packages. The Umbrel team adds gallery images before merge; official App Store image assets are hosted in a separate assets repo.
- Omit `icon` for official App Store packages. Official icons are hosted with the other App Store image assets outside this package repo. Community app stores may use `icon` in the manifest.
- `defaultUsername` and `defaultPassword` are displayed to the user in Umbrel when non-empty. They do not configure the app.
- Use real credentials that work after install. Use `""` for values that do not exist, such as apps with first-run account creation or no login.
- `deterministicPassword: true` makes Umbrel display the per-install `APP_PASSWORD` value as the app password. Set it only when the package actually configures the app login/admin password to `${APP_PASSWORD}`.
- Use `widgets:` for optional cards on the Umbrel home screen that show live app status, progress, recent activity, or quick actions. Add them only when the app has a real server-side JSON endpoint; see Widgets.
- Use `backupIgnore:` only for app data that should be excluded from Umbrel backups; see Backups.
- Set `submitter` to the contributor name as it should appear in the App Store metadata.
- Set `submission` to the pull request URL.
### Dependencies
Manifest `dependencies:` are runtime dependencies on other Umbrel apps.
- Umbrel requires the dependency app, or a selected app that `implements` it, to be installed before installing the dependent app.
- The dependency value remains the app ID being depended on, even when alternatives exist. For example, an app that needs an Electrum server depends on `electrs`; Umbrel can let the user satisfy it with another installed app that implements `electrs`.
- Use `implements:` only when an app can stand in for another Umbrel app's dependency contract. Any app can be implemented this way, but the implementing app must satisfy the same exported variables, endpoints, credentials, paths, protocols, and optional capabilities that dependent apps expect from the original app.
- The implementing app should export the canonical variables for the app it implements, not only its own app-specific variables. For example, an app that implements `bitcoin` must export the `APP_BITCOIN_*` contract used by dependent apps, and an app that implements `electrs` must export the `APP_ELECTRS_*` contract used by dependent apps.
- Existing examples in this repo include Bitcoin node alternatives that implement `bitcoin` by exporting node IP, data dir, RPC user/password/port, P2P port, network, Electrs-compatible network name, and any supported ZMQ, Tor, IPC, or hidden-service values.
- Existing Electrum server alternatives implement `electrs` by exporting `APP_ELECTRS_NODE_IP` and `APP_ELECTRS_NODE_PORT`, and by providing an Electrum protocol endpoint compatible with apps that depend on `electrs`.
- Test `implements:` with representative dependent apps before relying on it. Do not use it as a category, tag, or loose similarity marker.
- During lifecycle commands, Umbrel sources `exports.sh` from selected direct and transitive dependencies before the app's own exports.
- Apps selected as dependencies cannot be uninstalled while dependent apps are installed.
- Do not use manifest dependencies for services inside the same `docker-compose.yml`; model those as compose services instead.
### Permissions
Manifest `permissions:` declares platform or shared-storage access the app needs. Permission values used in this repo include:
- `GPU` requests GPU device access. When the device has `/dev/dri`, umbrelOS adds `/dev/dri` to every service in the app, so use it only when the app has a real GPU acceleration or hardware transcoding path.
- `STORAGE_DOWNLOADS` indicates the app needs access to Umbrel's shared Downloads storage. Use it only when the compose file mounts Downloads or one of its subdirectories.
- Do not add empty or speculative permissions. The manifest should match what the package actually uses.
### Backups
Users can enable backups in umbrelOS. App packages should assume persisted app data is backed up by default.
- `backupIgnore:` is a package-level exclusion list for files inside `${APP_DATA_DIR}` that should not be restored from backup.
- Use `backupIgnore:` when restoring the data is unnecessary or unsafe: regenerated/redownloadable data, high-churn output that bloats backups, or state that upstream says is dangerous to restore stale.
- Examples include caches, logs, thumbnails, indexes, blockchain data, model downloads, temporary worker state, and protocol state such as Lightning channel databases when stale restore can be dangerous.
- Entries are relative to `${APP_DATA_DIR}`. Use simple paths or `*` globs only, for example `data/cache/*` or `data/logs/*`.
- Do not exclude primary user content, uploads, ordinary app databases, wallet seeds or keys, required config, encryption keys, or anything needed to restore the app to the user's expected state.
- Do not use `backupIgnore:` to exclude an entire app from backups. Users control whole-app backup exclusion in umbrelOS.
### Widgets
Widgets are glanceable cards on the Umbrel home screen for app status, progress, recent activity, or quick actions. Manifest `widgets:` registers optional widgets users can add to the Umbrel home screen.
- Do not add placeholder widgets. Add a widget only when the package exposes useful live status or controls through JSON.
- Each widget needs a local `id`, `type`, `refresh`, `endpoint`, `link`, and `example`. Umbrel prefixes the manifest ID at runtime as `<app-id>:<widget-id>`, so keep the manifest `id` local to the app, for example `status` or `sync`.
- Supported app widget types are `text-with-buttons`, `text-with-progress`, `two-stats-with-guage`, `three-stats`, `four-stats`, `list`, and `list-emoji`.
- The `endpoint` must be `service:port/path` with no scheme. The host must exactly match a service key in `docker-compose.yml`. Umbrel builds `http://<endpoint>`, resolves the service to the container IP, and fetches it server-side.
- The endpoint must return JSON matching the widget `type`, including a `refresh` duration such as `5s`, `30s`, or `1m`. The live response drives the rendered widget; the manifest `example` is sample data for the widget selector.
- The endpoint is not fetched through `app_proxy` and does not receive browser cookies or an app login session. Use a small unauthenticated internal endpoint or widget sidecar when the app UI/API requires auth.
- Keep `link` relative to the app path, or use `""` to launch the app root.
- Widget-only services usually do not need raw host `ports:`.
## Compose
`docker-compose.yml` defines the containers umbrelOS installs and runs for the app. umbrelOS patches the file before install to inject container names, rewrite compatibility storage mounts, and apply platform permissions such as GPU access.
### app_proxy
Use `app_proxy` for normal browser-based apps.
- Define an `app_proxy` service with environment only.
- Treat manifest `port` and app_proxy `APP_PORT` as different values: manifest `port` is the host-facing app_proxy port; `APP_PORT` is the internal web service port.
- Set `APP_HOST` to the Umbrel-injected container name: `<app-id>_<service-name>_1`.
- Set `APP_PORT` to the internal port the web service listens on.
- Do not publish the web UI with raw `ports:` when app_proxy is sufficient.
- Keep app_proxy auth enabled by default. Do not add `PROXY_AUTH_ADD: "true"` because that is already the framework default.
- With app_proxy auth enabled, users already signed in to Umbrel can open the app without another Umbrel login prompt. Users who are not signed in must authenticate with Umbrel first.
- Umbrel auth protects the route with the user's Umbrel login, including Umbrel 2FA when enabled.
- Umbrel auth can also protect an app before the user has created the app's own account during first-run setup.
- Set `PROXY_AUTH_ADD: "false"` only when the whole app must bypass Umbrel auth, such as an app with its own login that Umbrel auth would break or an app that is intentionally public.
- For companion apps, mobile clients, webhooks, federation, or protocol endpoints that cannot send Umbrel auth cookies, keep Umbrel auth enabled and use `PROXY_AUTH_WHITELIST` only for the required paths.
- Common whitelist examples are `/api/*`, `/webhook/*`, `/.well-known/*`, `/public/*`, `/assets/*`, or a narrow protocol route such as `/api/lnurl/*`.
- Treat whitelisted paths as public. Keep them as narrow as possible and make sure the app's own auth, token, signature, or protocol rules protect anything sensitive.
- Use `PROXY_AUTH_BLACKLIST` to protect sensitive paths inside a broader whitelist.
### Services
- Model each long-running process as one compose service: web app, worker, database, cache, search, queue, etc.
- Use sidecars when upstream expects separate databases, caches, workers, search, or queues; do not collapse them into one container just to reduce service count.
- Let Umbrel inject `container_name`; set it only when the app cannot work with Umbrel's injected name, and leave a short comment explaining why.
- Use `depends_on` and healthchecks when a service must wait for a database, cache, or init job to be ready.
- Use `restart: on-failure` by default for long-running services. One-shot init, migration, or bootstrap services may omit `restart:` when automatic restart would be wrong, or use `restart: on-failure` when retrying is safe. Use another restart policy only when upstream needs it and the reason is clear.
- Use `init: true` when the process needs a real init process for signal handling or child-process cleanup.
- Umbrel installs committed package directories under `${APP_DATA_DIR}` owned by UID/GID `1000:1000`. Running services as `user: "1000:1000"` keeps runtime-created files writable across restarts and updates when the image supports arbitrary UIDs.
- Do not force `user: "1000:1000"` on images that need their bundled user, root entrypoint, or permission-fixing startup. If upstream exposes `PUID`/`PGID`, `UID`/`GID`, or similar settings, use that supported path and verify the app can write to its mounted data after first start and restart.
- Treat the shared Docker network as untrusted. Do not rely on "no host-published port" as the only protection for databases, caches, admin APIs, or framework secrets. Generate stable per-install secrets; see `APP_SEED`, `APP_PASSWORD`, and `derive_entropy` under Umbrel Environment Variables.
- Add public URL, trusted proxy, CSRF/CORS, or root path settings only when the app otherwise redirects to the wrong host, rejects proxied requests, or serves broken asset/API paths behind `app_proxy`.
- When a canonical browser URL is required, point it at the Umbrel launch origin, usually `http://${DEVICE_DOMAIN_NAME}:${APP_PROXY_PORT}`. Keep trusted origins narrow; do not disable CSRF/CORS or use `*` unless the upstream protocol requires it.
### Persistence
Containers are recreated on restart and update. Anything the user expects to keep must be bind-mounted from app data.
- Use bind mounts under `${APP_DATA_DIR}/data/...` for app-owned mutable state: databases, uploads, user content, config, generated keys/secrets, plugins, and indexes that should survive restart.
- Do not leave upstream Docker named volumes for durable state. Convert them to `${APP_DATA_DIR}/data/...` bind mounts.
- Do not rely on files written only inside the container filesystem. If losing a path would reset accounts, config, uploads, wallets, databases, or app identity, bind-mount it.
- Keep runtime-created state under `data/`. Use the app-data root for package/lifecycle files and top-level rendered templates, not user data or databases.
- Use `${UMBREL_ROOT}/data/storage/downloads...` only for intentional shared Downloads access, and include `STORAGE_DOWNLOADS` in `permissions:`.
- Keep that compatibility Downloads mount path in app packages. Current umbrelOS rewrites it to `${UMBREL_ROOT}/home/Downloads...` when patching compose, while older umbrelOS versions expect the old path.
- Commit every host-side `${APP_DATA_DIR}/data/...` bind-mount source directory the app needs on first start. If the directory would otherwise be empty, keep it in git with `data/.../.gitkeep`; umbrelOS removes `.gitkeep` before runtime, so the container sees an empty directory.
- Be careful with file bind mounts such as `${APP_DATA_DIR}/data/config.yml:/app/config.yml:ro`. The host source file must exist before `docker compose up`; otherwise Docker may create a directory at that path and break the app. Commit the file, render it from a top-level template, or create it in a hook before start.
### Networking And Ports
Umbrel injects the external `umbrel_main_network` as the compose `default` network at runtime. Do not add a top-level `networks:` block for ordinary packages; use service-level `networks: default:` only when a tested static IP or alias is needed.
- Use Docker DNS names for same-app traffic, not container IPs. For `app_proxy`, set `APP_HOST` to the Umbrel-injected container name `<app-id>_<service-name>_1`; for other sidecar URLs, use the service name or injected container name used by nearby apps.
- Do not publish the web UI with raw `ports:` when `app_proxy` can front it.
- Publish raw `ports:` only for non-HTTP protocols, companion-client endpoints, server-to-server protocol ports, or integrations that must connect without `app_proxy`.
- Use explicit host mappings for raw ports, including protocol when needed, for example `"9735:9735"` or `"8448:8448/tcp"`. Do not use short syntax that lets Docker choose a random host port.
- Manifest `port` and raw host-published compose ports share the host port space. Keep them from colliding with other app ports or umbrelOS public ports such as `80`, `443`, and `2000`.
- The linter catches literal ports and simple static same-app `exports.sh` port values. If it flags an unresolved host port, verify the port manually and call it out in the PR when relevant.
- Internal container ports and app_proxy `APP_PORT` values do not need to be unique.
- Use `network_mode: host` only when required for LAN discovery, multicast/broadcast, low-level networking, or an upstream image that cannot work behind bridge networking. Host-network apps cannot use normal `app_proxy` routing; manifest `port` must match a host listener.
- Do not mount the host Docker socket, for example `/var/run/docker.sock`, or proxy access to Umbrel's Docker daemon.
- Do not use `privileged: true`, broad host mounts, device mounts, or extra capabilities to work around ordinary app configuration. If host access is genuinely required, keep it as narrow as the app allows.
### Images
- Every runtime image must be a prebuilt, maintained image that supports both `linux/amd64` for x86_64 PCs/servers and `linux/arm64` for 64-bit ARM devices such as Raspberry Pi 4/5. Do not use compose `build:` in App Store packages.
- Images must be publicly pullable without registry credentials, private registry access, GitHub package permissions, or local build context.
- Pin every image as `registry/repo:version-or-commit@sha256:<digest>`. Keep the human-readable tag and digest together; the tag should identify the upstream release, commit, or wrapper build.
- Use the multi-arch manifest-list/index digest for the tag, not an architecture-specific image digest. Verify with `docker buildx imagetools inspect <image>:<tag>` and confirm both `linux/amd64` and `linux/arm64` are present.
- Do not use `latest`, moving branch tags, unversioned distro tags when a versioned tag exists, or digest-only references without a tag. If upstream only publishes `latest`, first look for a commit/date tag or a better image source; if none exists, use `latest@sha256:<digest>` only as a last resort and document why a stable tag is unavailable.
- Pin every image used by every service, including databases, caches, workers, migration/init jobs, widget helpers, and one-shot utilities.
- Prefer official upstream images when they are maintained and multi-arch. Use a wrapper image only when packaging requires Umbrel-specific glue that cannot live in compose, templates, or hooks, or when upstream does not publish an acceptable multi-arch image.
## Umbrel Environment Variables
Umbrel sources app/dependency env, renders top-level templates, and runs compose through the app lifecycle. Use Umbrel-provided env instead of hardcoded install paths, device hostnames, or generated secret files.
Values available after app env is sourced:
- `APP_ID`: app ID from the manifest and directory name.
- `APP_VERSION`: manifest `version`.
- `APP_MANIFEST_FILE`: installed `umbrel-app.yml` path for the app.
- `APP_DATA_DIR`: installed app data root, `${UMBREL_ROOT}/app-data/<app-id>`.
- `APP_DOMAIN`: local `.local` domain for the Umbrel device; use with a port when upstream needs a browser-facing app URL.
- `APP_HIDDEN_SERVICE`: app Tor hidden-service hostname when Umbrel remote Tor access is enabled. It may be a placeholder such as `not-enabled.onion` or `notyetset.onion` before a hidden service exists.
- `APP_PROXY_HOSTNAME`: internal hostname of the generated `app_proxy` service.
- `APP_PROXY_PORT`: manifest `port`, the host-facing app URL port.
- `APP_SEED`: stable per-install derived value for the app; see Generated Secrets.
- `APP_PASSWORD`: stable per-install derived value for local app credentials when the package wires the app login/admin password to this value; see Generated Secrets.
- `DEVICE_HOSTNAME`: device hostname without `.local`.
- `DEVICE_DOMAIN_NAME`: device `.local` domain, usually used for browser-facing URLs such as `http://${DEVICE_DOMAIN_NAME}:${APP_PROXY_PORT}`.
- `UMBREL_ROOT`: Umbrel data root on the host.
- `NETWORK_IP`: Umbrel Docker network base IP; use `${NETWORK_IP}/16` when upstream needs the Umbrel app subnet, for example trusted proxy or RPC allowlist config.
- `TOR_PROXY_IP`: Umbrel Tor SOCKS proxy IP on the Docker network.
- `TOR_PROXY_PORT`: Umbrel Tor SOCKS proxy port.
- `TOR_DATA_DIR`: Umbrel Tor data directory on the host.
Generated secrets:
- `derive_entropy <label>` returns a deterministic HMAC-SHA256 hex value derived from Umbrel's device seed and the label. The same Umbrel install and label produce the same value across restarts and updates; different labels produce different values.
- `APP_SEED` is `derive_entropy "app-<app-id>-seed"`. Use it directly only when upstream needs one stable random-looking app seed or secret.
- `APP_PASSWORD` is `derive_entropy "app-<app-id>-seed-APP_PASSWORD"`. Use it only for local app login/admin credentials that Umbrel should be able to display through `deterministicPassword: true`.
- For multiple independent stable secrets, call `derive_entropy` in `exports.sh` with purpose-specific labels, for example `app-<app-id>-seed-postgres-password` and `app-<app-id>-seed-jwt-secret`.
- Use derived values for package-generated local secrets such as database passwords, database root/admin passwords, JWT/session/encryption secrets, or bootstrap admin passwords actually wired into the app.
- Do not reuse one derived value across unrelated secret fields.
- Do not use derived values as provider API keys, OAuth secrets, SMTP passwords, cloud storage tokens, webhook tokens, cryptocurrency wallet seeds/private keys, or user recovery secrets.
- Derived values are long hex strings. Verify upstream accepts that format and length before using one as a password, token, or key.
- Do not use internal compatibility constants such as `AUTH_PORT`, `MANAGER_IP`, or `UMBREL_AUTH_SECRET` as app secrets.
Dependency apps may export additional variables through their own `exports.sh`. Umbrel sources direct and transitive dependency exports before the app's own env is finalized. Read the dependency package before using its values, and consume the exact `APP_<DEPENDENCY>_*` contract it exports.
During `exports.sh`, Umbrel also provides context for the app whose exports file is being sourced:
- `EXPORTS_APP_ID`: ID of the app whose `exports.sh` is currently being sourced. This may be a dependency app, not the app being installed or started.
- `EXPORTS_APP_DIR`: installed app root for `EXPORTS_APP_ID`.
- `EXPORTS_APP_FILE`: path to the current `exports.sh` file.
- `EXPORTS_APP_DATA_DIR`: data directory for `EXPORTS_APP_ID`, equivalent to `${EXPORTS_APP_DIR}/data`.
- `EXPORTS_TOR_DATA_DIR`: Umbrel Tor data directory for exports-time use.
- `app_entropy_identifier`: stable per-app label, `app-<app-id>-seed`, used by Umbrel's built-in entropy derivation.
In `exports.sh`, use `EXPORTS_APP_ID`, `EXPORTS_APP_DIR`, and `EXPORTS_APP_DATA_DIR` for the app currently being sourced. Do not rely on `APP_ID` or `APP_DATA_DIR` there.
## `exports.sh`
`exports.sh` is sourced by Umbrel when preparing app and dependency env. Omit it unless the package needs computed values, generated secrets, host/device-derived values, or an app/dependency contract.
Use this shape:
```sh
export APP_EXAMPLE_DATA_DIR="${EXPORTS_APP_DATA_DIR}/server"
export APP_EXAMPLE_POSTGRES_PASSWORD="$(derive_entropy "${app_entropy_identifier}-postgres-password")"
export APP_EXAMPLE_SESSION_SECRET="$(derive_entropy "${app_entropy_identifier}-session-secret")"
```
Rules:
- Treat `exports.sh` as sourced shell, not an executable script. It does not need a shebang or executable bit, and it must not call `exit`, change directories for later code, or change shell options.
- Export only values other package files or dependent apps need. Keep helper variables unexported.
- Prefix package-owned exports as `APP_<APP_ID_WITH_UNDERSCORES>_...`. For `implements:`, also export the canonical `APP_<IMPLEMENTED_ID>_...` contract expected by dependent apps.
- Use `EXPORTS_APP_DIR` and `EXPORTS_APP_DATA_DIR` when referencing this app's installed files or data. Do not use `APP_DATA_DIR` for the app being sourced.
- Keep exports deterministic and idempotent. Prefer `derive_entropy` over generating random values or writing secret files. Only write/source a persisted file when required for an existing contract or upstream-generated material.
- Do not run Docker commands, call upstream services, perform migrations, or create/chown directories here; use compose, templates, committed `data/` scaffolding, or hooks for lifecycle work.
- `exports.sh` is sourced by Umbrel's app script while that script is running with `set -euo pipefail`. Guard optional files and commands, provide defaults for optional values, and avoid noisy output except actionable warnings.
- Static exports are fine for dependency contracts, shared ports, extra Tor ports, or values reused across package files. Do not add `exports.sh` just to name a constant used once.
## Templates
Top-level `*.template` files are processed with `envsubst` during install/start/update. The output file is written beside the template with `.template` removed.
Use templates for config files that need Umbrel env vars. Commit the `.template` source, not rendered output. Do not commit generated files containing install-specific values or secrets.
Be careful templating shell scripts: `envsubst` will also substitute normal shell variables such as `$i`, `$pid`, or `${timeout}` unless they are escaped or avoided.
## App Lifecycle And Updates
Umbrel installs and runs apps from `app-data/<app-id>`, not directly from the app-store repo. Package files are copied into app data, `.gitkeep` files are removed, top-level templates are rendered there, and containers start from the installed copy.
Packaging implications:
- App and dependency env is sourced before templates render and before containers start. Dependency `exports.sh` files are sourced before the app's own env is finalized.
- Persist user state with `${APP_DATA_DIR}/data/...` bind mounts. Container filesystems are recreated across restart and update.
- Updates copy only `docker-compose.yml`, top-level `*.template`, `exports.sh`, `torrc`, and `hooks` from the app-store package into installed app data.
- `umbrel-app.yml` is copied separately during the update flow.
- Files outside the update whitelist may exist on fresh installs but be missing on existing installs after update.
- Keep required runtime files in paths that are installed or updated deliberately: compose env, top-level templates, checked-in scaffolding under `data/`, or hook-managed migrations.
- When adding or moving required bind-mount source directories, commit the directory for fresh installs and add a hook migration if existing installs need it created during update.
- Hooks are lifecycle escape hatches. Prefer compose, templates, and committed scaffolding when they can express the behavior.
## Hooks
Optional hook scripts live in top-level `hooks/`, must be executable, and must use one of these exact names:
- `pre-install`: before app env is sourced, templates render, or containers start.
- `post-install`: after the app has started.
- `pre-start`: whenever the app starts, after app env is sourced and templates render, but before containers start.
- `post-start`: after containers start.
- `pre-stop`: whenever the app stops, before containers stop; app env has not been sourced for the stop command.
- `post-stop`: after containers stop.
- `pre-update`: after the app stops, before update files are copied and before app env is sourced for the update.
- `post-update`: after update files are copied and the app has started.
Most hook work should be a `pre-start` hook: it runs after app env and templates are ready, before containers start, and also runs on normal starts/restarts after install and update. Use other hooks only when their timing is specifically required.
Use this basic shape for new hook files:
```sh
#!/usr/bin/env bash
set -euo pipefail
APP_DIR="${APP_DATA_DIR:-$(readlink -f "$(dirname "${BASH_SOURCE[0]}")/..")}"
DATA_DIR="${APP_DIR}/data"
```
Hook rules:
- Keep hooks small, idempotent, and safe to run more than once.
- Use hooks for narrow existing-install migrations, ownership fixes, or generated config that cannot be handled cleanly by compose, templates, or committed `data/` scaffolding.
- Do not add hooks for ordinary new-app directory scaffolding.
- Do not redefine `APP_DATA_DIR` to mean `${APP_DATA_DIR}/data`; use local names such as `APP_DIR` and `DATA_DIR`.
- `pre-install`, `pre-stop`, and `pre-update` run before app env is sourced. If they need app paths, derive them from the hook location.
- Hook failures may not stop the app lifecycle, so do not hide required setup in a hook when compose, templates, or package scaffolding can express it directly.
## Lint Before Testing
Run the repo linter before Umbrel testing:
```sh
npm run lint:apps -- <app-id> --check-images
```
The linter covers manifest shape, app IDs, host port conflicts, image pinning, public pullability, multi-arch support, compose wiring, app_proxy basics, permissions, persistence paths, hooks, templates, and obvious committed runtime artifacts.
Fix errors before testing. Warnings do not always block a PR, but they must be intentional and explained in the PR when relevant.
Also run:
```sh
git diff --check
```
## Test Through Umbrel
Use `umbrel-test-app`. A package is not ready until it installs through Umbrel, opens in a browser, creates real app state when applicable, verifies default credentials or onboarding behavior, restarts, and preserves data.
## PR Readiness
- Keep the diff scoped to one app unless the task explicitly requires shared changes.
- Do not include generated secrets, rendered templates, runtime data, screenshots, or unrelated files.
- In the PR body, include the app/version, upstream project URL, image source, testing performed, and any host access, permissions, default credentials, or notable setup behavior.
- Include app screenshots and the app logo/source logo in the PR body for App Store review. Do not commit screenshots, gallery assets, or icon assets for official App Store submissions; the Umbrel team will create and host final App Store assets.
+175
View File
@@ -0,0 +1,175 @@
---
name: umbrel-test-app
description: Use when testing or verifying an Umbrel App Store package, including linting, Umbrel device or local umbrelOS test environments, fresh install and update-path testing, browser verification, logs, persistence, dependencies, and PR evidence.
---
# Umbrel Test App
Verify app packages through Umbrel's app lifecycle: install, update when relevant, browser access, restart, persistence, and logs.
For package changes discovered during testing, use `umbrel-package-app` or `umbrel-update-app` as relevant.
## Testing Standard
- Run static checks for every package change.
- Runtime verification through Umbrel is the standard for App Store packages. Test through Umbrel before opening a PR whenever possible.
- Use the Fresh Install and Update Path sections below for the runtime checks that apply.
- If runtime testing is not available, say that clearly in the PR notes. Do not present linting, image pulls, or raw Docker Compose testing as Umbrel verification.
## Static Checks
Run before Umbrel testing:
```sh
npm run lint:apps -- <app-id> --check-images
git diff --check
```
Fix linter errors before runtime testing. Warnings do not always block a PR, but intentional warnings must be understood and explained when relevant.
## Test Environments
Record the environment and architecture actually tested.
- Umbrel device: best runtime signal, especially for apps with hardware access, LAN discovery, host networking, broad permissions, or heavy storage behavior.
- Local umbrelOS test environment: useful for smoke testing through umbrel-dev or containerized umbrelOS.
- Architecture: test both `amd64` and `arm64` when available. `arm64` coverage is especially important for Raspberry Pi 4/5 users. If only one architecture is available, still run image multi-arch checks and state the tested architecture.
Containerized umbrelOS example:
```sh
docker run --name umbrelos-test \
--privileged \
--interactive \
--tty \
--network host \
--volume umbrelos-test:/data \
ghcr.io/getumbrel/umbrelos:<current-umbrelos-version> \
/sbin/init
```
Use a disposable named volume per test run or app when practical. This setup is known to work with OrbStack on macOS. Other Docker hosts may need different flags, and WSL may not support the required privileged systemd, host networking, cgroup, and nested Docker behavior.
## Interact With Umbrel
Use the Umbrel UI or Umbrel's local APIs to drive testing.
The UI is the best way to verify user-facing behavior: app store rendering, install/update buttons, dependency prompts, launch behavior, default credential dialogs, and the app opening from the Umbrel home screen.
After SSHing into the Umbrel or local test environment, use Umbrel's `umbreld client` tRPC helper for repeatable lifecycle actions and logs:
```sh
ssh umbrel@umbrel.local
APP_ID=<app-id>
# Confirm Umbrel sees the synced package and manifest version.
umbreld client appStore.registry.query
# Inspect installed app metadata, including credentials shown by Umbrel.
umbreld client apps.list.query
# Install or update through Umbrel.
umbreld client apps.install.mutate --appId "$APP_ID"
umbreld client apps.update.mutate --appId "$APP_ID"
# Restart or manually control the app.
umbreld client apps.restart.mutate --appId "$APP_ID"
umbreld client apps.start.mutate --appId "$APP_ID"
umbreld client apps.stop.mutate --appId "$APP_ID"
# Check lifecycle state and logs.
umbreld client apps.state.query --appId "$APP_ID"
umbreld client apps.logs.query --appId "$APP_ID"
```
For apps with dependencies, install the selected dependency provider before installing the dependent app. The UI enforces this; direct tRPC calls do not.
```sh
DEPENDENCY_APP_ID=<dependency-provider-app-id>
umbreld client apps.install.mutate --appId "$DEPENDENCY_APP_ID"
```
For apps that support dependency alternatives, pass the chosen installed provider during install or change it after install:
```sh
umbreld client apps.install.mutate --appId "$APP_ID" --alternatives '{"<dependency-id>":"<provider-app-id>"}'
umbreld client apps.setSelectedDependencies.mutate --appId "$APP_ID" --dependencies '{"<dependency-id>":"<provider-app-id>"}'
```
Do not treat programmatic success as full verification. A ready state, successful mutation, or clean logs only proves Umbrel completed that lifecycle step; the app still needs to open through Umbrel and perform a meaningful workflow.
## Make The Package Available
Umbrel must see the package through an app-store source before testing.
For an Umbrel device, sync the app package into the official App Store source directory:
```sh
APP_ID=<app-id>
STORE_PATH=/home/umbrel/umbrel/app-stores/getumbrel-umbrel-apps-github-53f74447
rsync -av --delete --exclude=".gitkeep" \
"$HOME/dev/umbrel/umbrel-apps/${APP_ID}/" \
"umbrel@umbrel.local:${STORE_PATH}/${APP_ID}/"
```
Keep `--delete` scoped to one app directory so the app-store source matches the working copy. `--exclude=".gitkeep"` matches Umbrel's install behavior: `.gitkeep` files keep empty package directories in git, but umbrelOS removes them before runtime.
## Fresh Install
For a new app package, or when an update changes first-run behavior, test a fresh install:
1. If the app has dependencies, install the selected dependency provider through Umbrel first.
2. Install the app through Umbrel.
3. Wait for Umbrel to report the app as ready.
4. Open the app from the Umbrel home screen or `app_proxy` route, not a raw internal container port.
5. Verify the web UI, setup page, or status page loads.
6. Verify declared default credentials, deterministic password behavior, or first-run account creation through Umbrel metadata and browser login.
7. Verify the app's main user-facing functionality. Complete real workflows where practical, such as creating a note, uploading a test file, adding a feed, saving a setting, inviting a user, or confirming a status/API page reports correctly.
8. If the package uses `PROXY_AUTH_WHITELIST`, `PROXY_AUTH_BLACKLIST`, or disables Umbrel auth, verify the intended public/client/API paths work and sensitive paths are still protected.
9. Restart the app through Umbrel.
10. Reopen the app and confirm state, login/onboarding, and the artifact/action persist.
11. Inspect settled logs for actionable errors.
## Update Path
For existing app updates, test an actual update path:
1. Install the currently shipped package through Umbrel.
2. Create or identify persisted state before updating.
3. Point Umbrel at the updated app store package and confirm Umbrel sees the new manifest `version`.
4. Run the update through Umbrel.
5. Wait for Umbrel to report the app as ready.
6. Open the app through Umbrel and verify migrations, login/onboarding, persisted state, and main user-facing functionality.
7. If the update changes bind mounts, data paths, templates, hooks, exports, database/search/index sidecars, runtime users, permissions, dependencies, `app_proxy`, auth, or default credentials, verify that behavior specifically.
8. Restart the app and verify it still opens and preserves data.
9. Inspect settled logs for actionable errors.
If the update path could not be tested from the currently shipped package, state that clearly in the PR notes.
## Evidence
Record enough detail for a reviewer to understand what was proved:
- app ID and version tested
- environment: Umbrel device or local umbrelOS test environment
- architecture tested: `amd64` or `arm64`
- fresh install and/or update path tested
- dependencies/providers or alternatives used, if any
- browser route opened
- main functionality tested
- restart and persistence result
- intentional linter warnings
- runtime caveats or untested paths, including required external accounts, paid services, hardware, large downloads, or destructive workflows that could not be fully tested
Do not include generated secrets, tokens, cookies, app-proxy credentials, private URLs, or sensitive user data in PR notes, logs, screenshots, or summaries.
## Do Not Accept As Proof
- Raw `docker compose up` as the only runtime test.
- Successful image pull as proof the app works.
- `apps.state == ready` without opening the app.
- A login page as proof when credentials, onboarding, or app setup changed.
- Fresh install only for an existing app update.
- Screenshots from an agent browser session as reviewer-visible proof unless they are saved, checked for secrets, and attached or linked in the PR.
+87
View File
@@ -0,0 +1,87 @@
---
name: umbrel-update-app
description: Use when updating an existing Umbrel App Store package, including upstream version bumps, package fixes, metadata-only App Store changes, manifest version and release notes, image verification, update-path safety, linting, Umbrel testing, and PR readiness.
---
# Umbrel Update App
Update an existing Umbrel App Store package while preserving the installed app contract.
This skill contains the normal update workflow. Consult `umbrel-package-app` only when changing manifest structure, compose wiring, env vars, persistence, permissions, dependencies, `app_proxy`, hooks, or other packaging behavior. Use `umbrel-test-app` for runtime verification.
Keep changes scoped to the requested app unless the task explicitly requires shared changes.
## What Umbrel Sees
- Umbrel shows an available app update when the app-store manifest `version` for an installed `id` differs from the installed app's `version`.
- `releaseNotes` from the app-store manifest render in the update dialog for that available update. Write them for users upgrading an existing install.
- Changing manifest `version` makes Umbrel offer an update; changing image references in `docker-compose.yml` is what makes the installed app run new container code.
- Do not bump manifest `version` by itself for an upstream app update. If the app code should change, update the relevant image tag/digest or package files too.
- Do not change images, compose, templates, exports, hooks, or other runtime behavior without bumping manifest `version`. Existing installs will not see an available update unless the manifest version changes.
## Update Gate
Before an upstream or runtime update, prove there is a real, packageable update target.
- Identify the currently packaged version, image tags/digests, service names, `app_proxy` target, persisted paths, hooks, exports, dependencies, permissions, and default credentials.
- Use the authoritative upstream stable release/source for the app's current channel. Do not chase prerelease, nightly, enterprise, or otherwise different-channel builds unless the package already follows that channel or the task explicitly requests it.
- Match the container image to the upstream target. A registry tag is enough only when the publisher and version mapping are understood; for moving tags, verify the digest changed and the image actually contains the intended app version.
- Verify changed images are packageable for Umbrel: public pull, release/commit/wrapper tag plus matching digest, multi-arch manifest-list/index digest, and `linux/amd64` plus `linux/arm64` support.
- Read upstream upgrade notes, migration guides, Docker/self-hosting docs, and compose/env examples for changes that affect the Umbrel package.
## Package Changes
Most upstream app updates only need `version`, `releaseNotes`, and changed image tag/digest references. Add compose, env, hook, template, permission, dependency, or persistence changes only when the upstream update requires them.
- Never change `id` for a released app. It is the app identity and data path.
- For metadata-only App Store changes, leave manifest `version` unchanged unless installed users need an available update.
- Change `manifestVersion` only when the package requires behavior from a newer umbrelOS version; it controls install compatibility for new installs.
- Set manifest `version` to the upstream version users recognize. If upstream has no release version, use the short commit SHA for the exact upstream commit being packaged.
- Write concise Umbrel-user `releaseNotes` for existing app updates. Include user-visible features, fixes, security notes, migration or breaking-change actions, and an upstream release-notes link when available. Omit upstream CI, docs-only, build, and internal dependency churn unless it affects the Umbrel package.
- Update image tag and digest together for every image that changes. Keep a tag that identifies the release, commit, or wrapper build, and pin the digest for that same tag.
- Carry through upstream-required compose, env, config, data path, port, proxy, healthcheck, and migration changes.
- Treat image publisher switches, `app_proxy` changes, runtime user changes, new hooks/exports, permissions, storage path changes, dependency changes, and database/search/index sidecar jumps as higher-risk. Use evidence and explain them in the PR.
- If the update adds required files, directories, templates, or migrations, handle existing installs with Update-Safe Files And Migrations.
- When upstream documents upgrade checkpoints or required migrations, evaluate them against versions previously shipped in this repo, not only the version currently on `master`. Umbrel users may skip app-store updates.
- Removing hooks, templates, exports, or checked-in scaffolding affects fresh installs, but existing installs may keep old copied files. If an old copied file must stop running or being used, remove or neutralize it with an update-safe hook.
## Update-Safe Files And Migrations
App updates copy only `docker-compose.yml`, top-level `*.template`, `exports.sh`, `torrc`, `hooks`, and `umbrel-app.yml` from the app-store package into installed app data.
- Files outside that set are fresh-install only unless a copied file or hook creates/copies them during update.
- Fresh installs receive newly committed package directories because umbrelOS copies the full app template into app data and strips `.gitkeep`. Keep otherwise-empty new bind-mount source directories in git with `.gitkeep`.
- Put required update-time config in `docker-compose.yml`, a top-level `*.template`, `exports.sh`, or `hooks/`.
- When adding a new bind-mount source directory, commit it for fresh installs and add an idempotent executable `hooks/pre-start` migration for existing installs. The hook should create the directory and `chown` it to the UID/GID the target container needs before containers start.
- When changing a bind mount, map the old host path to the old container path before editing. If the new mount points at a different host path, write a narrow migration that preserves existing data instead of creating an empty replacement directory.
- For file bind mounts, make sure the host file exists before `docker compose up`. On updates, create it from a top-level template or `pre-start` hook; otherwise Docker may create a directory at the file path and break the app.
- Use `pre-start` for most update migrations because app env and templates are ready, containers are still stopped, and the hook also runs on future starts. Use `post-update` only for cleanup that is safe after the updated app has started.
- Keep migrations idempotent with sentinel files or existence checks. Hook failures may not stop the lifecycle, so verify the app still works through the real Umbrel update path.
## Lint Before Testing
Run the repo linter before Umbrel testing:
```sh
npm run lint:apps -- <app-id> --check-images
```
Fix linter errors before runtime testing. Warnings do not always block a PR, but intentional warnings must be understood and explained when relevant.
Also run:
```sh
git diff --check
```
## Test Through Umbrel
Use `umbrel-test-app`. Existing app updates should verify an actual update path, not only a fresh install. The package is not ready until the updated app opens, preserves existing user data, handles default credentials or onboarding correctly, restarts, and continues to work after the update. If the update path could not be tested from the currently shipped package, state that clearly in the PR notes.
## PR Readiness
- Keep the diff scoped to the requested app.
- Do not include generated secrets, rendered templates, runtime data, screenshots, or unrelated files.
- Include the old version, new version, upstream release/source link, testing performed, environment and architecture tested, and any breaking changes or migration behavior in the PR body.
- Explain intentional changes to permissions, host access, dependencies, ports, default credentials, app path, or persistence.
- Explain intentional linter warnings instead of hiding them with unrelated package changes.
+61
View File
@@ -0,0 +1,61 @@
name: App request
description: Suggest an app for the Umbrel App Store
title: "App request: "
body:
- type: markdown
attributes:
value: |
Want to see an app on Umbrel? Open a request here so Umbrel, the community, and the app's developers can see the demand.
The best path is for the app's official developers to submit or help maintain the Umbrel package. Popular requests may also be picked up by Umbrel or community contributors.
If you want to help, share this request with the app's developers or open an issue in their project asking if they'd like to submit an Umbrel package.
- type: input
id: app
attributes:
label: App name
validations:
required: true
- type: input
id: upstream
attributes:
label: Upstream project
description: Website, GitHub repo, or official docs.
validations:
required: true
- type: input
id: docker
attributes:
label: Official Docker image
description: Leave blank if unknown.
- type: dropdown
id: web-ui
attributes:
label: Does it have a browser UI or status page?
options:
- "Yes"
- "No"
- "I don't know"
validations:
required: true
- type: textarea
id: fit
attributes:
label: Why does it fit Umbrel?
validations:
required: true
- type: dropdown
id: packaging-help
attributes:
label: Who can help package or maintain this app?
options:
- I can submit a PR
- The app's developers may be able to help
- I am only suggesting the app
validations:
required: true
- type: textarea
id: notes
attributes:
label: Packaging notes
description: Known ports, persisted data, dependencies, special permissions, or architecture support.
+11
View File
@@ -0,0 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: Umbrel Support
url: https://umbrel.com/support
about: Get official help from Umbrel.
- name: Umbrel Community
url: https://community.umbrel.com/
about: Get help from the Umbrel community.
- name: Umbrel Community Discord
url: https://discord.gg/efNtFzqtdx
about: Chat with the Umbrel community.
+86
View File
@@ -0,0 +1,86 @@
name: App package issue
description: Report an Umbrel packaging problem with an app
title: "Package issue: "
body:
- type: markdown
attributes:
value: |
Use this for problems with how an app installs, updates, starts, opens from Umbrel, persists data, or connects to Umbrel dependencies.
If you are using a coding agent, it can help inspect Umbrel app logs, config, and package files before opening the issue.
If you are not sure whether this is a packaging issue, Umbrel Support or the Umbrel community can help narrow it down first. You can find those links in the issue chooser.
If the app opens normally and the issue is inside the app itself, the app's developers are usually the best place to report it.
- type: input
id: app-id
attributes:
label: App ID
description: The app folder name, if known.
validations:
required: true
- type: input
id: umbrelos-version
attributes:
label: umbrelOS version
validations:
required: true
- type: dropdown
id: architecture
attributes:
label: Device architecture
options:
- amd64
- arm64
- I don't know
validations:
required: true
- type: dropdown
id: install-type
attributes:
label: When did this happen?
options:
- Fresh install
- App update
- App restart
- Normal use
validations:
required: true
- type: dropdown
id: area
attributes:
label: What failed?
options:
- Install
- Update
- Start
- Open from Umbrel
- Login or default credentials
- Data persistence
- Dependency connection
- Permissions or storage
- Other
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual behavior
validations:
required: true
- type: textarea
id: diagnosis
attributes:
label: Diagnosis or agent summary
description: If a coding agent looked at this, paste its short summary here.
- type: textarea
id: logs
attributes:
label: Logs or screenshots
description: Include relevant Umbrel app logs if available. Remove secrets, tokens, cookies, private URLs, and personal data.
+41
View File
@@ -0,0 +1,41 @@
<!--
Title format:
- Add <app name>
- Update <app name> to <version>
- Fix <app name> <issue>
-->
## Type
New app / App update / Metadata only
## App
App ID:
Upstream project:
Version:
## Summary
What changed and why?
## Verification
Umbrel testing performed:
Environment tested:
- [ ] Umbrel device
- [ ] Local umbrelOS test environment
- [ ] Not runtime tested
Architecture tested:
- [ ] amd64
- [ ] arm64
Known lint warnings or caveats:
## Notes
Permissions, dependencies, migrations, default credentials, or caveats:
For new apps, include screenshots and a logo reference. Umbrel will create the final App Store gallery assets.
+14 -2
View File
@@ -1,13 +1,25 @@
name: Lint apps
on:
pull_request_target:
pull_request:
branches:
- master
permissions:
contents: read
jobs:
lint-apps:
name: Lint apps
runs-on: ubuntu-latest
steps:
- uses: sharknoon/umbrel-app-linter-action@d0b39f9ec5867fd001b05d5ddd6037dcc35f41bd
- uses: actions/checkout@v6
with:
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-node@v6
with:
node-version: 22
cache: npm
- run: npm ci --ignore-scripts
- run: npm run lint:apps -- --changed "origin/${{ github.base_ref }}...HEAD" --check-images --format github
+1745
View File
File diff suppressed because it is too large. Load diff
+9
View File
@@ -0,0 +1,9 @@
# Umbrel Apps Agent Guide
Before changing app packages, use the relevant skill in `.claude/skills/`.
- Add a new app: `umbrel-package-app`
- Update an existing app: `umbrel-update-app`
- Test or verify an app package: `umbrel-test-app`
Keep changes scoped to the requested app unless the task explicitly requires shared changes.
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+27 -471
View File
@@ -1,485 +1,41 @@
# Umbrel App Framework
# Umbrel App Store Packages
If you can code in any language, you already know how to develop an app for Umbrel. There is no restriction on the kinds of programming languages, frameworks, or databases that you can use. Apps run inside isolated [Docker](https://docs.docker.com/) containers, and the only requirement is that they should serve a web-based UI.
This repository contains the app packages published in the official Umbrel App Store. Each top-level directory is an app package consumed by umbrelOS.
> Some server apps might not have a UI at all. In that case, the app should serve a simple web page listing the connection details, QR codes, setup instructions, and anything else needed for the user to connect. The user is never expected to have CLI access on Umbrel.
Browse the store at https://apps.umbrel.com.
To keep this document short and easy, we won't go into the app development itself, and will instead focus on packaging and testing an existing app.
## Contributing
Let's jump into action by packaging [BTC RPC Explorer](https://github.com/janoside/btc-rpc-explorer), a Node.js based app, for Umbrel.
Before adding or updating app packages, read `AGENTS.md`.
There are 4 steps:
`AGENTS.md` routes app packaging, updates, and testing to the repo-local skills in `.claude/skills/`. Those skills are the source of truth for packaging rules and verification steps.
1. [🛳 Containerizing the app using Docker](#1-containerizing-the-app-using-docker)
1. [☂️ Packaging the app for umbrelOS](#2-%EF%B8%8Fpackaging-the-app-for-umbrelos)
1. [🛠 Testing the app on umbrelOS](#3-testing-the-app-on-umbrelos)
1. [Test using an umbrelOS development environment on your local machine](#31-test-using-an-umbrelos-development-environment-on-your-local-machine)
1. [Test using umbrelOS running on a physical device](#32-test-using-umbrelos-running-on-a-physical-device)
1. [🚀 Submitting the app](#4-submitting-the-app)
___
## App Store Standard
## 1. 🛳&nbsp;&nbsp;Containerizing the app using Docker
Every app package should open to a web UI, status page, or setup page that makes the app usable without SSH or CLI access.
1\. Let's start by cloning BTC RPC Explorer on our system:
Beyond that, apps should feel natural on umbrelOS: sensible defaults, browser-based setup, predictable updates, and careful handling of user data. Some apps need special setup or expose advanced controls, but the default path should be understandable from the browser.
```sh
git clone --branch v2.0.2 https://github.com/janoside/btc-rpc-explorer.git
cd btc-rpc-explorer
## App Store Badges
After an app is published, developers can use generated Umbrel App Store badges in their own README, website, or release notes.
App-specific badges, using Immich as an example:
[![Get Immich on umbrelOS](https://apps.umbrel.com/api/app/immich/badge-dark.svg)](https://apps.umbrel.com/app/immich)
[![Get Immich on umbrelOS](https://apps.umbrel.com/api/app/immich/badge-light.svg)](https://apps.umbrel.com/app/immich)
```text
https://apps.umbrel.com/api/app/<app-id>/badge-dark.svg
https://apps.umbrel.com/api/app/<app-id>/badge-light.svg
```
2\. Next, we'll create a `Dockerfile` in the app's directory:
Generic badges:
```Dockerfile
FROM node:12-buster-slim AS builder
[![Get it on umbrelOS](https://apps.umbrel.com/badge-dark.svg)](https://apps.umbrel.com)
[![Get it on umbrelOS](https://apps.umbrel.com/badge-light.svg)](https://apps.umbrel.com)
WORKDIR /build
COPY . .
RUN apt-get update
RUN apt-get install -y git python3 build-essential
RUN npm ci --production
FROM node:12-buster-slim
USER 1000
WORKDIR /build
COPY --from=builder /build .
EXPOSE 3002
CMD ["npm", "start"]
```text
https://apps.umbrel.com/badge-dark.svg
https://apps.umbrel.com/badge-light.svg
```
### A good Dockerfile:
- [x] Uses a lightweight base image - this results in less storage consumption and faster app installs.
- [x] Uses [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) for smaller image size.
- [x] Excludes development files in the final image.
- [x] Has only one service per container.
- [x] Doesn't run the service as root.
- [x] Uses remote assets that are verified against a checksum.
- [x] Results in deterministic image builds.
3\. We're now ready to build the Docker image of BTC RPC Explorer. Umbrel supports both 64-bit ARM and x86 architectures, so we'll use `docker buildx` to build, tag, and push multi-architecture Docker images of our app to Docker Hub. This way, the same app can be installed on both ARM and x86 devices.
```sh
docker buildx build --platform linux/arm64,linux/amd64 --tag getumbrel/btc-rpc-explorer:v2.0.2 --output "type=registry" .
```
> You need to enable ["experimental features"](https://docs.docker.com/engine/reference/commandline/cli/#experimental-features) in Docker to use `docker buildx`.
___
## 2. ☂️&nbsp;&nbsp;Packaging the app for umbrelOS
1\. Let's fork the [getumbrel/umbrel-apps](https://github.com/getumbrel/umbrel-apps) repo on GitHub, clone our fork locally, create a new branch for our app, and then switch to it:
```sh
git clone https://github.com/<YOUR-GITHUB-USERNAME>/umbrel-apps.git
cd umbrel-apps
```
2\. It's now time to pick an ID for our app. An app ID should only contain lowercase alphabetical characters and dashes, and should be human readable and recognizable. For this app we'll go with `btc-rpc-explorer`.
We need to create a new subdirectory in the apps directory with the same name as our app ID and move into it:
```sh
mkdir btc-rpc-explorer
cd btc-rpc-explorer
```
3\. Within the app's directory, we'll now create the skeleton for our app with the following files:
- `docker-compose.yml` - Used to start and stop your app's Docker containers
- `umbrel-app.yml` - An app manifest file so that Umbrel knows the name and version of the app
- `exports.sh` - A shell script to export environment variables used within `docker-compose.yml` and share with other installed apps
We'll now create a `docker-compose.yml` file in this directory to define our application.
> New to Docker Compose? It's a simple tool for defining and running Docker applications that can have multiple containers. Follow along with the tutorial, we promise it's not hard if you already understand the basics of Docker.
Let's copy-paste the following `docker-compose.yml` template into a text editor and modify it according to our app.
```yml
version: "3.7"
services:
app_proxy:
environment:
# <app-id>_<web-container-name>_1
# e.g. 'btc-rpc-explorer_web_1'
# Note that the '_1' at the end is needed
APP_HOST: <web-container-dns-name>
APP_PORT: <web-container-port-number>
web:
image: <docker-image>:<tag>@sha256:<digest>
restart: on-failure
stop_grace_period: 1m
ports:
# You do not need to expose the port that your app's web server is listening on if you're using the app_proxy service.
# This is handled by the APP_HOST and APP_PORT environment variables in the service above.
#
# If you need to expose additional ports, you can do so like this, replacing <port> with the port number:
- <port>:<port>
volumes:
# Uncomment to mount your data directories inside
# the Docker container for storing persistent data
# - ${APP_DATA_DIR}/foo:/foo
# - ${APP_DATA_DIR}/bar:/bar
#
# Uncomment to mount LND's data directory as read-only
# inside the Docker container at path /lnd
# - ${APP_LIGHTNING_NODE_DATA_DIR}:/lnd:ro
#
# Uncomment to mount Bitcoin Core's data directory as
# read-only inside the Docker container at path /bitcoin
# - ${APP_BITCOIN_DATA_DIR}:/bitcoin:ro
environment:
# Pass any environment variables to your app for configuration in the form:
# VARIABLE_NAME: value
#
# Here are all the Umbrel provided variables that you can pass through to
# your app
# System level environment variables
# $DEVICE_HOSTNAME - Umbrel server device hostname (e.g. "umbrel")
# $DEVICE_DOMAIN_NAME - A .local domain name for the Umbrel server (e.g. "umbrel.local")
#
# Tor proxy environment variables
# $TOR_PROXY_IP - Local IP of Tor proxy
# $TOR_PROXY_PORT - Port of Tor proxy
#
# App specific environment variables
# $APP_HIDDEN_SERVICE - The address of the Tor hidden service your app will be exposed at
# $APP_PASSWORD - Unique plain text password that can be used for authentication in your app, shown to the user in the Umbrel UI
# $APP_SEED - Unique 256 bit long hex string (128 bits of entropy) deterministically derived from user's Umbrel seed and your app's ID
# If your app has more services, like a database container, you can define those
# services below:
# db:
# image: <docker-image>:<tag>@sha256:<digest>
# ...
```
Our app manifest YAML file tells Umbrel details about our app such as the name, description, dependencies, port number to access the app, etc.
> There are currently two manifest versions: `1` and `1.1`. Version `1` is the basic version and is sufficient for most apps. However, if your app requires the use of hooks (scripts that are run at different stages of the app lifecycle), you need to use version `1.1`. Hooks allow you to perform custom actions at different stages of the app's lifecycle, such as before the app starts (pre-start), after the app installs (post-install), and more. If your app doesn't need to use hooks, you can stick with manifest version `1`.
```yml
manifestVersion: 1
id: btc-rpc-explorer
category: finance
name: BTC RPC Explorer
version: "3.3.0"
tagline: Simple, database-free blockchain explorer
description: >-
BTC RPC Explorer is a full-featured, self-hosted explorer for the
Bitcoin blockchain. With this explorer, you can explore not just the
blockchain database, but also explore the functional capabilities of your
Umbrel.
It comes with a network summary dashboard, detailed view of blocks, transactions, addresses, along with analysis tools for viewing stats on miner activity, mempool summary, with fee, size, and age breakdowns. You can also search by transaction ID, block hash/height, and addresses.
It's time to appreciate the "fullness" of your node.
releaseNotes: >-
Dark mode is finally here! Easily switch between your preferred mode
in one click.
This version also includes lots of minor styling improvements, better
error handling, and several bugfixes.
developer: Dan Janosik
website: https://explorer.btc21.org
dependencies:
- bitcoin
- electrs
repo: https://github.com/janoside/btc-rpc-explorer
support: https://github.com/janoside/btc-rpc-explorer/discussions
port: 3002
gallery:
- 1.jpg
- 2.jpg
- 3.jpg
path: ""
defaultUsername: ""
defaultPassword: ""
submitter: Umbrel
submission: https://github.com/getumbrel/umbrel/pull/334
```
When submitting a new app, leave the `gallery` and `releaseNotes` fields empty. Use the following values:
```yml
gallery: []
releaseNotes: ""
```
The `dependencies` section within the app manifest gives Umbrel a list of app IDs that must be already installed in order for the user to install BTC RPC Explorer and also function.
The `exports.sh` shell script is a simple script to export environmental variables that your `docker-compose.yml` can read. These environment variables are also accessible when other apps start through their `docker-compose.yml` files. Most applications will not require this feature.
If we (for example) wanted to share BTC RPC Explorer's Address API with other apps; that would look like this:
```sh
export APP_BTC_RPC_EXPLORER_ADDRESS_API="electrumx"
```
4\. For our app, we'll update `<docker-image>` with `getumbrel/btc-rpc-explorer`, `<tag>` with `v2.0.2`, `<digest>` with `f8ba8b97e550f65e5bc935d7516cce7172910e9009f3154a434c7baf55e82a2b`, and `<port>` with `3002`. Since BTC RPC Explorer doesn't need to store any persistent data and doesn't require access to Bitcoin Core's or LND's data directories, we can remove the entire `volumes` block.
> The digest is a unique, immutable identifier for the Docker image. This will supersede the tag in the `docker-compose.yml` file. The reason we want to pull an image by its digest, is that we are guaranteed to get the exact same image every time, and this image will be the same image that was tested and verified to work on umbrelOS. It is important to make sure that this digest is the multi-architecture digest, and not the digest for a specific architecture.
BTC RPC Explorer is an application with a single Docker container, so we don't need to define any other additional services (like a database service, etc) in the compose file.
> If BTC RPC Explorer needed to persist some data we would have created a new `data` directory next to the `docker-compose.yml` file. We'd then mount the volume `- ${APP_DATA_DIR}/data:/data` in the `docker-compose.yml` to make the directory available at `/data` inside the container.
Updated `docker-compose.yml` file:
```yml
version: "3.7"
services:
app_proxy:
environment:
APP_HOST: btc-rpc-explorer_web_1
APP_PORT: 8080
web:
image: getumbrel/btc-rpc-explorer:v2.0.2@sha256:f8ba8b97e550f65e5bc935d7516cce7172910e9009f3154a434c7baf55e82a2b
restart: on-failure
stop_grace_period: 1m
environment:
BTCEXP_PORT: 8080
```
5\. Next, let's set the environment variables required by our app to connect to Bitcoin Core, Electrum server, and for app-related configuration ([as required by the app](https://github.com/janoside/btc-rpc-explorer/blob/master/.env-sample)).
So the final version of `docker-compose.yml` would be:
```yml
version: "3.7"
services:
app_proxy:
environment:
APP_HOST: btc-rpc-explorer_web_1
APP_PORT: 8080
web:
image: getumbrel/btc-rpc-explorer:v2.0.2
restart: on-failure
stop_grace_period: 1m
environment:
PORT: 8080
# Bitcoin Core connection details
BTCEXP_BITCOIND_HOST: $APP_BITCOIN_NODE_IP
BTCEXP_BITCOIND_PORT: $APP_BITCOIN_RPC_PORT
BTCEXP_BITCOIND_USER: $APP_BITCOIN_RPC_USER
BTCEXP_BITCOIND_PASS: $APP_BITCOIN_RPC_PASS
# Electrum connection details
BTCEXP_ELECTRUMX_SERVERS: "tcp://$APP_ELECTRS_NODE_IP:$APP_ELECTRS_NODE_PORT"
# App Config
BTCEXP_HOST: 0.0.0.0
DEBUG: "btcexp:*,electrumClient"
BTCEXP_ADDRESS_API: electrumx
BTCEXP_SLOW_DEVICE_MODE: "true"
BTCEXP_NO_INMEMORY_RPC_CACHE: "true"
BTCEXP_PRIVACY_MODE: "true"
BTCEXP_NO_RATES: "true"
BTCEXP_RPC_ALLOWALL: "false"
BTCEXP_BASIC_AUTH_PASSWORD: ""
```
6\. We're pretty much done here. The next step is to commit the changes, push it to our fork's branch, and test out the app on Umbrel.
```sh
git add .
git commit -m "Add BTC RPC Explorer"
git push
```
___
## 3. 🛠&nbsp;&nbsp;Testing the app on umbrelOS
🚨 This is the current workflow for testing an app on umbrelOS 1.x. The app framework is under active development and this workflow will change in the future. For testing on umbrelOS 0.5.4, please refer to the [previous version of this document](https://github.com/getumbrel/umbrel-apps/blob/9eae789b8512ef2a213805524e17f33d2128e33e/README.md).
### 3.1 Test using an umbrelOS development environment on your local machine
The umbrelOS development environment (umbrel-dev) requires a Docker environment that exposes container IPs to the host. This is how Docker natively works on Linux and can be done with OrbStack on macOS and WSL 2 on Windows.
1\. Install [OrbStack](https://orbstack.dev/) on macOS or [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install) with Docker Desktop on Windows.
2\. Clone the [getumbrel/umbrel](https://github.com/getumbrel/umbrel) repo.
From the root of the cloned repo, run the following command to view the available umbrel-dev commands:
```sh
npm run dev help
```
To start the development environment, run the following command:
```sh
npm run dev
```
> [!NOTE]
> If this is your first time running the development environment, it may take a while to build the OS image locally on your machine.
Once initialized, umbrelOS will be accessible at http://umbrel-dev.local.
3\. Copy the app's directory (with any .gitkeep files excluded) to the app-store directory on umbrel-dev.
To do this, we run the following command on our local machine:
```sh
rsync -av --exclude=".gitkeep" <path-to-your-forked-repo-on-local-machine>/btc-rpc-explorer umbrel@umbrel-dev.local:/home/umbrel/umbrel/app-stores/getumbrel-umbrel-apps-github-53f74447/
```
If you are asked for a password during the transfer, use the password that you set when you created your umbrelOS account.
4\. Install the app.
From the umbrelOS homescreen, go to the App Store and navigate to BTC RPC Explorer. Click on the "Install" button and wait for the app to install.
You can also install the app from the command line. umbrelOS provides a web terminal that can be accessed via Settings > Advanced Settings > Terminal > umbrelOS, or you can use the umbrel-dev scripts to install the app using the umbreld RPC server:
```sh
npm run dev client -- apps.install.mutate -- --appId btc-rpc-explorer
```
That's it! Our BTC RPC Explorer app should now be accessible at http://umbrel-dev.local:3002
To uninstall the app, you can right-click on the app's icon on your homescreen and click on the "Uninstall" button. You can also uninstall the app using the umbrel-dev scripts:
```sh
npm run dev client -- apps.uninstall.mutate -- --appId btc-rpc-explorer
```
> [!WARNING]
> When testing your app, make sure to verify that any application state that needs to be persisted is in-fact being persisted in volumes.
>
> A good way to test this is to restart the app (right-click on the app's icon on your homescreen and click on the "Restart" button). If any state is lost, it means that state should be mapped to a persistent volume.
>
> When stopping/starting the app, all data in volumes will be persisted and anything else will be discarded. When uninstalling/installing an app, even persistent data will be discarded.
### 3.2 Test using umbrelOS running on a physical device
You can get up and running with umbrelOS in a few different ways:
1. [Install umbrelOS on a Raspberry Pi 5](https://github.com/getumbrel/umbrel/wiki/Install-umbrelOS-on-a-Raspberry-Pi-5)
2. [Install umbrelOS on any x86 system](https://github.com/getumbrel/umbrel/wiki/Install-umbrelOS-on-x86-Systems)
3. [Install umbrelOS in a VM](https://github.com/getumbrel/umbrel/wiki/Install-umbrelOS-on-a-Linux-VM)
4. [Purchase an Umbrel Home](https://umbrel.com/umbrel-home)
Regardless of the method you choose, once you have umbrelOS up and running and have visited http://umbrel.local and created an account, you can follow the steps below to test your app.
1\. Copy the app's directory (with any .gitkeep files excluded) to the app-store directory on your umbrelOS device.
To do this, we run the following command on our local machine:
```sh
rsync -av --exclude=".gitkeep" <path-to-your-forked-repo-on-local-machine>/btc-rpc-explorer umbrel@umbrel.local:/home/umbrel/umbrel/app-stores/getumbrel-umbrel-apps-github-53f74447/
```
If you are asked for a password during the transfer, use the password that you set for your umbrelOS device when you created your account.
2\. Install the app on your umbrelOS device:
From your umbrelOS homescreen, go to the App Store and navigate to BTC RPC Explorer. Click on the "Install" button and wait for the app to install.
You can also install the app from the command line. umbrelOS provides a web terminal that can be accessed via Settings > Advanced Settings > Terminal > umbrelOS, or you can SSH into the device from your local machine via `ssh umbrel@umbrel.local` and use the same password you set for your umbrelOS device when you created your account.
```sh
umbreld client apps.install.mutate --appId btc-rpc-explorer
```
That's it! The app should now be accessible at http://umbrel.local:3002
To uninstall the app, you can right-click on the app's icon on your homescreen and click on the "Uninstall" button. You can also uninstall the app from the command line with:
```sh
umbreld client apps.uninstall.mutate --appId btc-rpc-explorer
```
> [!WARNING]
> When testing your app, make sure to verify that any application state that needs to be persisted is in-fact being persisted in volumes.
>
> A good way to test this is to restart the app (right-click on the app's icon on your homescreen and click on the "Restart" button). If any state is lost, it means that state should be mapped to a persistent volume.
>
> When stopping/starting the app, all data in volumes will be persisted and anything else will be discarded. When uninstalling/installing an app, even persistent data will be discarded.
___
## 4. 🚀&nbsp;&nbsp;Submitting the app
We're now ready to open a pull request on the main [getumbrel/umbrel-apps](https://github.com/getumbrel/umbrel-apps) apps repo to submit our app. Let's copy-paste the following markdown for the pull request description, fill it up with the required details, and then open a pull request.
```
# App Submission
### App name
...
### 256x256 SVG icon
_(Upload an icon with no rounded corners as it will be dynamically rounded with CSS.)_
_We will help finalize this icon before the app goes live in the Umbrel App Store._
...
### Gallery images
_(Upload 3 to 5 high-quality gallery images (1440x900px) of your app in PNG format, or just upload 3 to 5 screenshots of your app and we'll help you design the gallery images.)_
_We will help finalize these images before the app goes live in the Umbrel App Store._
...
### I have tested my app on:
- [ ] umbrelOS on a Raspberry Pi
- [ ] umbrelOS on an Umbrel Home
- [ ] umbrelOS on Linux VM
```
This is where the above information is used when the app goes live in the Umbrel App Store:
<img width="877" alt="image" src="https://github.com/getumbrel/umbrel-apps/assets/85373263/2297030f-909a-4e33-afac-398e30fc79c4">
> After you've submitted your app, we'll review your pull request, make some adjustments in the `docker-compose.yml` file, such as removing any port conflicts with other apps, pinning Docker images to their sha256 digests, assigning unique IP addresses to the containers, etc before merging.
🎉 Congratulations! That's all you need to do to package, test, and submit your app to Umbrel. We can't wait to have you onboard!
---
## Advanced configuration
### App Proxy
The Umbrel App Proxy automatically protects an app by requiring the user to enter their Umbrel password (either when they login into the main Web UI or by visiting an app directly e.g. `http://umbrel.local:3002`)
##### Disable
There could be cases where you wish to disable this authentication. That can be done by adding this env. var. to the `app_proxy` Docker Compose service:
```
PROXY_AUTH_ADD: "false"
```
##### Whitelist/blacklist
Some apps host a user-facing UI at the root of their web application and then an API at e.g. `/api`. And in this case we would like `/` to be protected by Umbrel and `/api` protected by the apps existing/inbuilt API token system. This can be achieved by adding this env. var. to the `app_proxy` Docker Compose service:
```
PROXY_AUTH_WHITELIST: "/api/*"
```
Another example could be that the root of the web application (`/`) should be publicly accessible but the admin section be protected by Umbrel. This can be achieved by adding these env. vars. to the `app_proxy` Docker Compose service:
```
PROXY_AUTH_WHITELIST: "*"
PROXY_AUTH_BLACKLIST: "/admin/*"
```
---
## FAQs
1. **How do I push app updates?**
Every time you release a new version of your app, you should build, tag, and push the new Docker images to Docker Hub. Then open a new PR on our main app repo (getumbrel/umbrel-apps) with your up-to-date docker image, and updated `version` and `releaseNotes` in your app's `umbrel-app.yml` file.
1. **I need help with something else**
Feel free to open an [issue](https://github.com/getumbrel/umbrel-apps/issues) on this GitHub repository.
+27
View File
@@ -0,0 +1,27 @@
{
"name": "umbrel-apps",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"dependencies": {
"yaml": "^2.8.1"
}
},
"node_modules/yaml": {
"version": "2.9.0",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
"integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
"license": "ISC",
"bin": {
"yaml": "bin.mjs"
},
"engines": {
"node": ">= 14.6"
},
"funding": {
"url": "https://github.com/sponsors/eemeli"
}
}
}
}
+10
View File
@@ -0,0 +1,10 @@
{
"private": true,
"type": "module",
"scripts": {
"lint:apps": "node .tools/lint-apps.mjs"
},
"dependencies": {
"yaml": "^2.8.1"
}
}