docudjeex/content/fr/3.serveex/91.advanced/2.arcane.md

title, description

title	description
Arcane	Installer Arcane, une interface web moderne de gestion Docker et Compose, comme alternative plus avancée à Dockge avec gestion multi-hôtes et connexion OIDC.

:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}

::note{to="/serveex/core/docker#installer-dockge-pour-gérer-et-déployer-les-conteneurs"}

Arcane est une alternative avancée à Dockge : il peut gérer plusieurs hôtes Docker distants depuis une seule instance, et prend en charge la connexion OIDC nativement plutôt que de dépendre d'un proxy de forward-auth séparé. ::

Arcane est une interface web auto-hébergée pour gérer les conteneurs, images, volumes et stacks Compose de Docker.

• Documentation d'Arcane
• Arcane sur GitHub

::note{to="https://docs.linuxserver.io/images/docker-socket-proxy/"}

Arcane a besoin d'accéder au socket Docker pour gérer les conteneurs, ce qui équivaut à un accès root sur votre hôte. Plutôt que de monter le socket directement, ce tutoriel place Docker Socket Proxy devant, en n'autorisant que les permissions d'API dont Arcane a réellement besoin. Quoi que vous utilisiez, assurez-vous qu'Arcane lui-même ne soit jamais joignable sans authentification. ::

Installation

::file-tree

tree: /: - srv: - docker: - arcane: - compose.yaml - .env - data/

::

::steps{level="3"}

Générer une clé de chiffrement

openssl rand -base64 32

Gardez le résultat, vous en aurez besoin pour le fichier .env ci-dessous.

Déployer la stack

Ouvrez Dockge, cliquez sur compose, nommez la stack arcane, et ajoutez la configuration suivante. Elle inclut le socket proxy : arcane ne touche jamais directement à /var/run/docker.sock, seul docker-socket-proxy le fait, et il n'autorise que les permissions dont Arcane a besoin (conteneurs, images, réseaux, volumes, exec, build/commit), sur leur propre réseau interne :

---
services:
  arcane:
    image: ghcr.io/getarcaneapp/manager:latest
    container_name: arcane
    restart: unless-stopped
    cgroup: host
    env_file:
      - .env
    volumes:
      - /srv/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 est l'autorisation d'écriture globale nécessaire pour créer et supprimer conteneurs, images, réseaux et volumes ; ALLOW_START/ALLOW_STOP/ALLOW_RESTARTS couvrent séparément les actions sur le cycle de vie des conteneurs. Tout le reste (Swarm, secrets, configs, auth) est laissé à sa valeur par défaut 0, puisque ce site ne les utilise pas. ::

::tip{icon=""} ✨ Ajoutez le label Watchtower pour automatiser les mises à jour :

---
services:
  arcane:
    #...
    labels:
      - com.centurylinklabs.watchtower.enable=true

::

Renseigner vos variables d'environnement

Remplissez le fichier .env :

APP_URL=https://arcane.mondomaine.fr
ENCRYPTION_KEY=
DOCKER_HOST=tcp://docker-socket-proxy:2375
PUID=1000
PGID=1000

Variable	Valeur	Exemple
APP_URL{lang=properties}	L'URL publique par laquelle vous joindrez Arcane (voir l'exposition plus bas), sans port	https://arcane.mondomaine.fr
ENCRYPTION_KEY{lang=properties}	La clé générée ci-dessus	Q2pVEqsTNRkJSO9SkJzU3KZ2...
DOCKER_HOST{lang=properties}	Pointe Arcane vers le socket proxy plutôt qu'un socket monté	tcp://docker-socket-proxy:2375
PUID / PGID{lang=properties}	Vos identifiants d'utilisateur et de groupe, via id votreutilisateur	1000

Déployez la stack. L'interface locale est disponible sur http://ipdevotreserveur:3552.

Terminé !

::

::caution

Si ça ne marche pas : vérifiez les règles de votre pare-feu. ::

Exposer Arcane avec SWAG

Le principal intérêt de cette installation est de pouvoir accéder à Arcane à distance depuis tous vos appareils. Nous allons l'exposer avec SWAG.

::warning

La connexion locale d'Arcane n'a pas d'authentification multifacteur. Ne l'exposez que si vous utilisez Pocket ID (voir plus bas) ou Authentik pour la connexion. Sinon, ne l'exposez pas avec SWAG. Utilisez plutôt un VPN comme Wireguard, surtout vu le niveau d'accès qu'Arcane a sur votre hôte. ::

::note

Nous partons du principe que vous avez le sous-domaine arcane.mondomaine.fr avec un CNAME pointant vers mondomaine.fr dans votre zone DNS. Et bien sûr, à moins d'utiliser Cloudflare Zero Trust, le port 443 de votre box doit être redirigé vers le port 443 de votre serveur dans les règles NAT. ::

::steps{level="3"}

Ajouter le réseau d'Arcane à SWAG

Allez dans Dockge et modifiez le fichier compose de SWAG en y ajoutant le réseau d'Arcane :

---
services:
  swag:
     container_name: # ...
      # ... 
     networks:              # Rattache le conteneur au réseau personnalisé 
      # ...           
      - arcane              # Nom du réseau déclaré

networks:                   # Définit le réseau personnalisé
  # ...
  arcane:                   # Nom du réseau déclaré
    name: arcane_default    # Nom réel du réseau externe
    external: true          # Le marque comme défini à l'extérieur

Redéployez la stack et attendez que SWAG soit pleinement opérationnel.

::note

Nous partons ici du principe que le nom du réseau d'Arcane est arcane_default. Vous pouvez vérifier la connexion en visitant le tableau de bord de SWAG sur http://ipdevotreserveur:81. ::

Créer le fichier subdomain.conf

Dans les dossiers de Swag, créez le fichier arcane.subdomain.conf :

::tip{icon="" to="/serveex/files/file-browser-quantum"} ✨ Astuce : utilisez File Browser Quantum pour naviguer et modifier les fichiers plutôt que des commandes dans le terminal. ::

sudo nano /srv/docker/swag/config/nginx/proxy-confs/arcane.subdomain.conf

Collez la configuration suivante :

## 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

Les mises à jour en direct d'Arcane passent par un websocket, d'où les en-têtes Upgrade/Connection ci-dessus, en plus de l'inclusion habituelle de proxy.conf. ::

Appuyez sur :kbd{value="Ctrl+O"}, puis :kbd{value="Enter"} pour enregistrer, et :kbd{value="Ctrl+X"} pour quitter.

Terminé !

::

Et voilà ! Arcane est maintenant accessible depuis internet.

Connecter un hôte distant

Arcane peut gérer plusieurs hôtes Docker depuis une seule instance. Chaque hôte distant fait tourner un conteneur agent léger qui se reconnecte à Arcane. Plutôt que d'exposer cette connexion sur internet, nous la ferons passer par le VPN WireGuard déjà mis en place plus tôt, ainsi le trafic de l'agent ne quitte jamais votre réseau privé.

::note{to="/serveex/core/wireguard#client-server-setup"}

Ceci suppose que l'hôte Arcane et l'hôte distant font déjà tourner leur propre client WireGuard, connectés à votre VPN comme décrit dans Client Server Setup. Notez l'adresse VPN que wg-easy a attribuée à l'hôte Arcane (par exemple 10.8.0.3) ; c'est l'adresse que visera l'agent distant ci-dessous. ::

::steps{level="3"}

Ajouter l'environnement distant dans Arcane

Dans Arcane, allez dans Environments > Add Environment. Arcane génère un Agent Token à usage unique et le bout de configuration compose à déployer sur l'hôte distant.

Déployer l'agent sur l'hôte distant

Sur l'hôte distant, ouvrez Dockge, cliquez sur compose, nommez la stack arcane-agent, et ajoutez la configuration suivante, en remplaçant le token par celui qu'Arcane vous a donné et l'URL par l'adresse VPN de votre hôte Arcane :

---
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_votretoken
      - MANAGER_API_URL=http://10.8.0.3:3552
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /srv/docker/arcane-agent/data:/app/data

::note

En « mode edge » : l'agent se connecte vers Arcane plutôt que l'inverse, il fonctionne donc derrière un NAT sans rien rediriger sur la box de l'hôte distant. Utiliser l'adresse VPN plutôt qu'un domaine public fait que cette connexion reste sur le tunnel WireGuard même si l'agent est techniquement en mode « edge ». Contrairement au manager ci-dessus, l'agent a besoin du vrai socket Docker monté directement, puisque c'est lui qui exécute réellement les commandes sur cet hôte ; il n'existe pas d'option socket-proxy documentée pour lui. ::

Déployez la stack.

Vérifier la connexion

De retour dans Arcane, le nouvel environnement devrait apparaître comme connecté en quelques secondes. Basculez dessus depuis le sélecteur d'environnement pour gérer les conteneurs et les stacks de cet hôte.

Terminé !

::

Connecter Pocket ID

Arcane gère OIDC nativement, vous pouvez donc exiger une connexion Pocket ID avant de laisser qui que ce soit gérer vos conteneurs, plutôt qu'avec (ou en plus de) les comptes propres à l'application.

::steps{level="3"}

Enregistrer Arcane comme client OIDC

Enregistrez un client OIDC dans Pocket ID nommé arcane, avec cette URL de callback :

https://arcane.mondomaine.fr/auth/oidc/callback

Activer OIDC dans Arcane

Modifiez le fichier .env d'Arcane et ajoutez :

OIDC_ENABLED=true
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
OIDC_ISSUER_URL=https://id.mondomaine.fr
OIDC_SCOPES=openid email profile
OIDC_PROVIDER_NAME=Pocket ID

Variable	Valeur
OIDC_CLIENT_ID{lang=properties}	Le client ID copié depuis Pocket ID
OIDC_CLIENT_SECRET{lang=properties}	Le client secret copié depuis Pocket ID
OIDC_ISSUER_URL{lang=properties}	L'URL publique de Pocket ID, sans slash final ; Arcane découvre le reste via .well-known/openid-configuration

Redéployez la stack.

::tip{icon=""} ✨ Pour aller directement sur Pocket ID et masquer le formulaire de connexion local, mettez OIDC_AUTO_REDIRECT_TO_PROVIDER=true, ou désactivez complètement la connexion locale dans Settings > Authentication pour un accès uniquement OIDC. ::

Terminé !

::

Et voilà ! Arcane propose désormais une option « Login with Pocket ID » à côté du formulaire de connexion local.

::tip{icon="" to="/serveex/advanced/authentik"} ✨ Vous pouvez utiliser Authentik plutôt que Pocket ID :

1. Dans Authentik, créez une application et un provider OAuth2/OpenID Connect nommé Arcane, avec une redirect URI (de type Strict) valant https://arcane.mondomaine.fr/auth/oidc/callback.
2. Notez les Client ID et Client Secret du provider.
3. Dans le .env d'Arcane, mettez OIDC_ISSUER_URL=https://authentik.mondomaine.fr/application/o/arcane/, puis renseignez le Client ID et le Client Secret. ::