Umbrel App Store Packages

To be compatible with the Umbrel App Store, every app package must be manageable via a web browser. The primary goal is to ensure users can complete setup and usage without needing SSH, CLI access, log scraping, or manual file edits.

Key Requirements:

• Web-based Interface: Apps should open to a web UI, setup flow, login page, or status page upon installation.
• Clear Next Steps: The UI must provide a clear path for the user to proceed.
• UmbrelOS Integration: Apps should utilize sensible defaults, browser-based setup, and predictable updates.
• Data Handling: Apps must handle user data carefully and provide a clear default path, even if advanced controls are available.

Developers can display Umbrel App Store badges on their own websites, READMEs, or release notes to link users to their app on the Umbrel store.

App-specific Badges

To link directly to your specific app, use the following URL pattern:

• Dark Mode: https://apps.umbrel.com/api/app/<app-id>/badge-dark.svg
• Light Mode: https://apps.umbrel.com/api/app/<app-id>/badge-light.svg

Generic Badges

To link to the general Umbrel App Store, use:

• Dark Mode: https://apps.umbrel.com/badge-dark.svg
• Light Mode: https://apps.umbrel.com/badge-light.svg

<!-- Example for an app with ID 'immich' -->
[![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)

Librephotos requires specific directory mappings to persist photos, media, database files, and logs. These paths are relative to the ${APP_DATA_DIR} environment variable.

Backend Volumes

• ${APP_DATA_DIR}/data/photos $\rightarrow$ /data: Stores photo files.
• ${APP_DATA_DIR}/data/protected_media $\rightarrow$ /protected_media: Stores protected media files.
• ${APP_DATA_DIR}/data/logs $\rightarrow$ /logs: Stores application logs.
• ${APP_DATA_DIR}/data/cache $\rightarrow$ /root/.cache: Stores application cache.

Database Volumes

• ${APP_DATA_DIR}/data/db $\rightarrow$ /var/lib/postgresql/data: Persists the PostgreSQL database files.

The DCRPulse application is composed of three main services that must be started in a specific order to ensure health and connectivity:

1. dcrd: The core daemon. It must be healthy before other services start. It uses a healthcheck that performs a JSON-RPC getinfo call via curl.
2. dcrwallet: Depends on dcrd being service_healthy. It manages the wallet and connects to dcrd via RPC. Its health is verified by checking connectivity to ports 9110 and 9111 using nc.
3. dashboard: The user interface. It depends on both dcrd and dcrwallet being service_healthy. It provides access to the data via the app_proxy.

Data Persistence: All services share the same volume mapping: ${APP_DATA_DIR}/data mapped to /app-data. The dashboard service mounts this volume as read-only (ro).

The EE Gateway is composed of two primary services that share a common data volume located at ${APP_DATA_DIR}/data (mounted as /data inside containers). They use file-based Inter-Process Communication (IPC) rather than network communication:

• UI Service: Writes config.json to the shared volume.
• Worker Service: Reads config.json and writes state.json and packets.db to the shared volume.

Credentials Management: Credentials are not passed via environment variables. Users enter an encryptedenergy.com API token during the UI setup wizard. This token is written to config.json in the shared volume, which the worker reads during every scan cycle.

The Plane deployment is composed of several specialized Docker services that work together to provide the full application experience:

• api: The core backend service handling requests.
• web: The frontend user interface.
• worker: A Celery worker for background task processing.
• beat-worker: A Celery beat service for scheduled tasks.
• migrator: A one-time service that runs database migrations (python manage.py migrate).
• live: Handles real-time communication/updates.
• space: A service (likely for file/asset management) that includes a healthcheck via HTTP.
• admin: An administrative interface.
• db: PostgreSQL database.
• redis: Valkey/Redis for caching and message brokering.
• rabbitmq: Message broker for Celery.
• minio: S3-compatible object storage for file uploads.
• nginx: Reverse proxy for the application.

To prevent overlapping subnet routes from routing local LAN replies through the tailscale0 interface (which can make the Umbrel unreachable on its local LAN IP), the service explicitly disables accept-routes during startup.

The startup command executes tailscale web --listen 0.0.0.0:8240 in the background and runs a retry loop (up to 30 attempts) to execute tailscale set --accept-routes=false before finally executing tailscaled.

To enable full functionality for the worker service, specific host hardware access is required:

Bluetooth Access

• Network Mode: Must use network_mode: host to access the host's Bluetooth stack.
• Capabilities: Requires NET_ADMIN and NET_RAW to manage and read from the radio.
• D-Bus: Requires a read-only bind-mount of /var/run/dbus to communicate with the host's bluetoothd.

GPS Access (Optional)

To use a USB GPS dongle, the following configuration is used to allow access to character devices with major numbers 188 (USB serial) and 166 (CDC ACM):

• Cgroup Rules: device_cgroup_rules must permit access to these majors.
• Device Passthrough: The host's /dev must be bind-mounted into the container's /dev to make the device nodes visible.

When deploying Frigate, consider the following settings for hardware access and memory management:

• Privileged Mode: The web service uses privileged: true, which may be necessary for certain hardware acceleration setups.
• Shared Memory (shm_size): The shm_size is set to "128mb". This value should be updated based on the number and resolution of your cameras.
• Cache Optimization: To reduce SSD/SD Card wear, you can enable a tmpfs mount for /tmp/cache.

    shm_size: "128mb" # update for your cameras based on calculation above
    # - type: tmpfs
    #   target: /tmp/cache
    #   tmpfs:
    #     size: 1000000000