Add Arcane as an advanced Dockge alternative

2026-09-04 16:54:05 +02:00
parent 1337fae991
commit b401a678cb
5 changed files with 344 additions and 0 deletions
@@ -309,6 +309,10 @@ Install and deploy Vaultwarden
 ::card{icon="i-noto-key" title="SSO & MFA" to="/serveex/advanced/authentik"}
 Install and deploy Authentik
 ::
+
+::card{icon="i-noto-crystal-ball" title="Multi-host Docker manager" to="/serveex/advanced/arcane"}
+Install and deploy Arcane
+::
 ::

 ## Coming Soon
@@ -14,6 +14,8 @@ Authentik also supports multi-factor authentication, including TOTP (a code gene

 It's a great alternative to VPNs for securely exposing services, especially ones that lack MFA or login protection (e.g., the SWAG dashboard).

+Compared to the [TinyAuth](/serveex/security/tinyauth) + [Pocket ID](/serveex/security/pocket-id) combo used elsewhere on this site, Authentik is a heavier, more professional-grade platform: a single application handling both the forward-auth proxy and the OIDC provider roles, with built-in support for LDAP, SAML, and RBAC-style access policies (restricting who can reach which app, not just whether they're logged in), on top of its own admin UI for managing users, groups, and outposts. TinyAuth and Pocket ID stay lighter and simpler for a small homelab; Authentik is worth the extra setup once you need finer-grained access control or a broader protocol support than OIDC alone.
+
 Authentik has [extensive documentation](https://docs.goauthentik.io/docs/installation/docker-compose) and [great tutorials from Cooptonian](https://www.youtube.com/@cooptonian). Here, we’ll cover the basics using Dockge as an example.

 There are two main modes you should know:
@@ -0,0 +1,338 @@
+---
+title: Arcane
+description: Install Arcane, a modern Docker and Compose management web UI, as a more advanced alternative to Dockge with multi-host support and OIDC login.
+---
+
+
+:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}
+
+[Arcane](https://github.com/getarcaneapp/arcane) is a self-hosted web UI for managing Docker containers, images, volumes, and Compose stacks, in the same spirit as [Dockge](/serveex/core/docker#installer-dockge-pour-gérer-et-déployer-les-conteneurs). Compared to Dockge, Arcane is more full-featured: it can manage several remote Docker hosts from a single instance, and it supports OIDC login natively instead of relying on a separate forward-auth proxy.
+
+![Arcane](/img/serveex/arcane.png)
+
+- [Arcane documentation](https://getarcane.app/docs/)
+- [Arcane on GitHub](https://github.com/getarcaneapp/arcane)
+
+::note
+
+Arcane needs access to the Docker socket to manage containers, which is effectively root access to your host. Instead of mounting the socket directly, this guide sits [Docker Socket Proxy](https://docs.linuxserver.io/images/docker-socket-proxy/) in front of it, only allowing the specific API permissions Arcane actually needs. Whatever you use, make sure Arcane itself is never reachable without authentication.
+::
+
+## Installation
+
+::file-tree
+---
+tree:
+  /:
+    - docker:
+      - arcane:
+        - compose.yaml
+        - .env
+        - data/
+---
+::
+
+::steps{level="3"}
+### Generate an encryption key
+
+```bash [Terminal]
+openssl rand -base64 32
+```
+
+Keep the output, you'll need it for the `.env` file below.
+
+### Deploy the stack
+
+Open Dockge, click `compose`, name the stack `arcane`, and add the following config. It includes the socket proxy: `arcane` never touches `/var/run/docker.sock` directly, only `docker-socket-proxy` does, and it only allows the specific permissions Arcane needs (containers, images, networks, volumes, exec, build/commit), on their own internal network:
+
+```yaml [compose.yaml]
+---
+services:
+  arcane:
+    image: ghcr.io/getarcaneapp/manager:latest
+    container_name: arcane
+    restart: unless-stopped
+    cgroup: host
+    env_file:
+      - .env
+    volumes:
+      - /docker/arcane/data:/app/data
+    networks:
+      - arcane-internal
+    ports:
+      - 3552:3552
+    depends_on:
+      - docker-socket-proxy
+
+  docker-socket-proxy:
+    image: lscr.io/linuxserver/socket-proxy:latest
+    container_name: arcane-docker-proxy
+    security_opt:
+      - no-new-privileges:true
+    networks:
+      - arcane-internal
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    environment:
+      - CONTAINERS=1
+      - IMAGES=1
+      - NETWORKS=1
+      - VOLUMES=1
+      - EXEC=1
+      - BUILD=1
+      - COMMIT=1
+      - INFO=1
+      - SYSTEM=1
+      - POST=1
+      - ALLOW_START=1
+      - ALLOW_STOP=1
+      - ALLOW_RESTARTS=1
+    restart: unless-stopped
+    read_only: true
+    tmpfs:
+      - /run
+
+networks:
+  arcane-internal:
+    name: arcane-internal
+```
+
+::note
+
+`POST=1` is the blanket write-enable needed for creating/removing containers, images, networks and volumes; `ALLOW_START`/`ALLOW_STOP`/`ALLOW_RESTARTS` cover container lifecycle actions separately. Everything else (Swarm, secrets, configs, auth) is left at its default `0`, since this site doesn't use them.
+::
+
+::tip{icon=""}
+✨ Add the Watchtower label to automate updates:
+
+```yaml [compose.yaml]
+---
+services:
+  arcane:
+    #...
+    labels:
+      - com.centurylinklabs.watchtower.enable=true
+```
+::
+
+### Set your environment variables
+
+Fill in the `.env` file:
+
+```properties [.env]
+APP_URL=https://arcane.mydomain.com
+ENCRYPTION_KEY=
+DOCKER_HOST=tcp://docker-socket-proxy:2375
+PUID=1000
+PGID=1000
+```
+
+| Variable | Value | Example |
+|----------|-------|---------|
+| `APP_URL`{lang=properties} | The public URL you'll use to reach Arcane (see exposure below), without a port | `https://arcane.mydomain.com` |
+| `ENCRYPTION_KEY`{lang=properties} | The key generated above | `Q2pVEqsTNRkJSO9SkJzU3KZ2...` |
+| `DOCKER_HOST`{lang=properties} | Points Arcane at the socket proxy instead of a mounted socket | `tcp://docker-socket-proxy:2375` |
+| `PUID` / `PGID`{lang=properties} | Your user and group ID, from `id yourusername` | `1000` |
+
+Deploy the stack. The local interface is available at `http://yourserverip:3552`.
+
+### Done !
+::
+
+::caution
+
+__If it fails:__ check your firewall rules.
+::
+
+## Exposing Arcane with SWAG
+The main benefit of this setup is being able to access Arcane remotely from all your devices. We'll expose it using SWAG.
+
+::warning
+
+Arcane's own local login has no multi-factor authentication. Only expose it if you're using [Pocket ID](/serveex/security/pocket-id) (see below) or [Authentik](/serveex/advanced/authentik) for login. Otherwise, don't expose it with SWAG. Use a VPN like [Wireguard](/serveex/security/wireguard) instead, especially given the level of access Arcane has over your host.
+::
+
+::note
+
+We assume you have the subdomain `arcane.mydomain.com` with a `CNAME` pointing to `mydomain.com` in your [DNS zone](/general/networking/dns). And of course, [unless you use Cloudflare Zero Trust](/serveex/security/cloudflare), your box's port `443` must be forwarded to your server's port `443` in [NAT rules](/general/networking/nat).
+::
+
+::steps{level="3"}
+### Add Arcane's network to SWAG
+
+Go to Dockge and edit SWAG's compose file by adding Arcane's network:
+
+```yaml [compose.yaml]
+---
+services:
+  swag:
+     container_name: # ...
+      # ... 
+     networks:              # Attach container to custom network 
+      # ...           
+      - arcane              # Name of the declared network
+
+networks:                   # Define the custom network
+  # ...
+  arcane:                   # Declared network name
+    name: arcane_default    # Actual external network name
+    external: true          # Marks it as externally defined
+```
+
+Redeploy the stack and wait for SWAG to be fully operational.
+
+::note
+
+Here we assume the Arcane network name is `arcane_default`. You can check the connection by visiting SWAG's dashboard at `http://yourserverip:81`.
+::
+
+### Create the subdomain.conf file
+
+In the Swag folders, create the file `arcane.subdomain.conf`:
+
+::tip{icon=""}
+✨ __Tip:__ Use [File Browser Quantum](/serveex/files/file-browser-quantum) to navigate and edit files instead of using terminal commands.
+::
+
+```bash [Terminal]
+sudo nano /docker/swag/config/nginx/proxy-confs/arcane.subdomain.conf
+```
+
+Paste the following configuration:
+
+```nginx [arcane.subdomain.conf]
+## Version 2023/12/19
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+
+    server_name arcane.*;
+
+    include /config/nginx/ssl.conf;
+
+    client_max_body_size 0;
+
+    location / {
+        include /config/nginx/proxy.conf;
+        include /config/nginx/resolver.conf;
+        set $upstream_app arcane;
+        set $upstream_port 3552;
+        set $upstream_proto http;
+        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+::note
+
+Arcane's live updates run over a websocket, hence the `Upgrade`/`Connection` headers above, on top of the usual `proxy.conf` include.
+::
+
+Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.
+
+### Done !
+::
+
+That's it! Arcane is now accessible from the internet.
+
+## Connecting a Remote Host
+Arcane can manage several Docker hosts from a single instance. Each remote host runs a lightweight **agent** container that connects back to Arcane. Rather than exposing that connection to the internet, we'll route it over the [WireGuard VPN](/serveex/security/wireguard) already set up earlier, so the agent traffic never leaves your private network.
+
+::note
+
+This assumes both the Arcane host and the remote host already run their own WireGuard client, connected to your VPN as described in [Client Server Setup](/serveex/security/wireguard#client-server-setup). Note the VPN address wg-easy assigned to the __Arcane host__ (e.g. `10.8.0.3`); that's the address the remote agent will target below.
+::
+
+::steps{level="3"}
+### Add the remote environment in Arcane
+
+In Arcane, go to _Environments > Add Environment_. Arcane generates a one-time __Agent Token__ and the compose snippet to deploy on the remote host.
+
+### Deploy the agent on the remote host
+
+On the remote host, open Dockge, click `compose`, name the stack `arcane-agent`, and add the following config, replacing the token with the one Arcane gave you and the URL with your Arcane host's VPN address:
+
+```yaml [compose.yaml]
+---
+services:
+  arcane-agent:
+    image: ghcr.io/getarcaneapp/agent:latest
+    container_name: arcane-agent
+    restart: unless-stopped
+    environment:
+      - EDGE_AGENT=true
+      - EDGE_TRANSPORT=poll
+      - AGENT_TOKEN=arc_yourtoken
+      - MANAGER_API_URL=http://10.8.0.3:3552
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /docker/arcane-agent/data:/app/data
+```
+
+::note
+
+This is "edge mode": the agent connects out to Arcane instead of the other way around, so it works from behind NAT without forwarding anything on the remote host's router. Using the VPN address instead of a public domain means that connection stays on the WireGuard tunnel even though the agent is technically in "edge" mode. Unlike the manager above, the agent needs the real Docker socket mounted directly, since it's the one actually running commands on that host; there's no documented socket-proxy option for it.
+::
+
+Deploy the stack.
+
+### Verify the connection
+
+Back in Arcane, the new environment should show as connected within a few seconds. Switch to it from the environment picker to manage that host's containers and stacks.
+
+### Done !
+::
+
+## Connecting Pocket ID
+Arcane supports OIDC natively, so you can require a Pocket ID login before letting anyone manage your containers, instead of (or alongside) the app's own accounts.
+
+::steps{level="3"}
+### Register Arcane as an OIDC client
+
+[Register an OIDC client in Pocket ID](/serveex/security/pocket-id#registering-an-oidc-client) named `arcane`, with this callback URL:
+
+```text
+https://arcane.mydomain.com/auth/oidc/callback
+```
+
+### Enable OIDC in Arcane
+
+Edit Arcane's `.env` file and add:
+
+```properties [.env]
+OIDC_ENABLED=true
+OIDC_CLIENT_ID=
+OIDC_CLIENT_SECRET=
+OIDC_ISSUER_URL=https://id.mydomain.com
+OIDC_SCOPES=openid email profile
+OIDC_PROVIDER_NAME=Pocket ID
+```
+
+| Variable | Value |
+|----------|-------|
+| `OIDC_CLIENT_ID`{lang=properties} | The client ID copied from Pocket ID |
+| `OIDC_CLIENT_SECRET`{lang=properties} | The client secret copied from Pocket ID |
+| `OIDC_ISSUER_URL`{lang=properties} | Pocket ID's public URL, no trailing slash; Arcane discovers the rest via `.well-known/openid-configuration` |
+
+Redeploy the stack.
+
+::tip{icon=""}
+✨ To skip straight to Pocket ID and hide the local login form, set `OIDC_AUTO_REDIRECT_TO_PROVIDER=true`, or disable local login entirely under _Settings > Authentication_ for OIDC-only access.
+::
+
+### Done !
+::
+
+That's it! Arcane now offers a "Login with Pocket ID" option alongside the local login form.
+
+::tip{icon=""}
+✨ You can use [Authentik](/serveex/advanced/authentik) instead of Pocket ID:
+
+1. In Authentik, create an application and an OAuth2/OpenID Connect provider named `Arcane`, with a redirect URI (type `Strict`) of `https://arcane.mydomain.com/auth/oidc/callback`.
+2. Note the provider's __Client ID__ and __Client Secret__.
+3. In Arcane's `.env`, set `OIDC_ISSUER_URL=https://authentik.mydomain.com/application/o/arcane/`, then fill in the Client ID and Client Secret.
+::