Unraid AppOps Gateway

A self-hosted operations dashboard that brings application discovery, connector health, policy-controlled actions and an auditable activity history together. Designed for operators managing Unraid and Portainer installations.

Capabilities

Discover services, review inventory and deliberately bring applications under management.
Configure Portainer, optional Unraid and application-specific connectors through /setup.
Inspect health, notification rules, diagnostics and SQLite-safe backups.
Apply typed action policies; blocked destructive operations remain blocked.
Use Authentik or tenant-specific Microsoft Entra OpenID Connect with persisted users and server-enforced roles.
Integrate optional Home Assistant voice commands and separately authenticated MCP/n8n clients.
Use deployment and enrollment control planes with pre-registered identities and immutable revisions.

The gateway does not require direct Docker socket access and exposes no arbitrary shell endpoint. Connector credentials are write-only through the API and encrypted at rest. Optional integrations require their own endpoints and scoped credentials.

Human access

Human API access requires a signed-in user. The shared operator-token unlock and anonymous-admin switch have been removed. No administrator is preconfigured. New users start read-only and administrators assign additional roles in Settings → Security.

For native OIDC, use an HTTPS frontend, configure a confidential Authentik provider or a tenant-specific Entra application, and register the exact callback URL (https://<app-host>/api/auth/callback/authentik or https://<app-host>/api/auth/callback/entra). An existing Entra federation can remain an Authentik source via APPOPS_AUTHENTIK_ENTRA_SOURCE. Put each client secret in its protected file under ./data; do not place secret values in .env, browser storage or source control. Set the initial administrator with either an explicit provider subject (APPOPS_AUTH_ADMIN_SUBJECTS) or a one-time Authentik verified-email bootstrap (APPOPS_AUTH_ADMIN_EMAILS). Remove the email bootstrap after the first administrator signs in. Leave both settings empty until you choose the intended administrator.

An existing Authentik outpost can also provide identity when AppOps trusts its exact peer network. Enable APPOPS_OPERATOR_PROXY_AUTH, list only the proxy peer in APPOPS_OPERATOR_PROXY_TRUSTED_NETWORKS, have the proxy overwrite client-supplied X-authentik-* identity headers, and prevent direct access to the backend port. Group headers do not grant AppOps roles. The backend enforces the access contract; hiding a control in the UI is not an authorization boundary.

Local evaluation

Requirements: Docker Engine with Compose, an HTTPS origin reachable through a trusted reverse proxy or VPN, and an identity provider (or a correctly bounded Authentik outpost).

cp .env.example .env
mkdir -p data
# Create data/secret-key and the selected OIDC client-secret file with restrictive permissions.
docker compose up --build -d

The Compose sample binds AppOps to 127.0.0.1:1216, persists ./data, and disables MCP/n8n until explicitly configured. Replace the example HTTPS origins, configure the provider and first administrator, and create protected key files before signing in. Without valid OIDC or trusted-proxy configuration, human API requests fail closed. Do not expose the backend directly to the internet. Review connector permissions and test a backup restore before production use. See Security policy.

First operator workflow

Configure one connector, inspect its health and review the discovered application inventory. Deliberately select the applications to manage, then inspect the available typed actions and their policies before executing an operation. Check the recorded outcome in the activity history.

Missing optional connectors mean partial coverage. Do not interpret a successful gateway health check as proof that every application is reachable. Keep connector scope narrow and investigate a denied operation before changing policy.

flowchart LR
  Operator[Authenticated operator] --> Gateway[AppOps API and policies]
  Gateway --> Connectors[Configured typed connectors]
  Connectors --> Targets[Managed applications]
  Gateway --> State[SQLite state and activity history]

Development

React 19, TypeScript, Vite, Tailwind and TanStack Query form the frontend. FastAPI provides the backend and serves the built frontend; SQLite persists state. Python dependencies are pinned in backend/requirements.txt.

corepack enable
pnpm install --frozen-lockfile
pnpm dev
pnpm check-types
pnpm lint
pnpm test:frontend
pnpm build
python -m pip install -r backend/requirements.txt
python -m pytest backend/tests -q

The current frontend uses the live backend facade; the historical mock-mode setting is no longer an offline demo switch. Evaluate the full local container with an empty data directory and no live connectors to explore setup safely.

Publication and licensing

Unraid-AppOps-Gateway-Public is a curated snapshot maintained from the private canonical repository. Updates are published automatically after changes merge to canonical main; private history, operational evidence and internal Actions are excluded. The public source manifest records the exact source revision.

No project-wide license has been selected or included. Public visibility does not grant an open-source license. Third-party dependencies retain their own terms. Contact the owner before redistributing or reusing the project.

5.5 KiB Raw Blame History