---
title: Arcane
description: 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](https://github.com/getarcaneapp/arcane) est une interface web auto-hébergée pour gérer les conteneurs, images, volumes et stacks Compose de Docker.

![Arcane](/img/serveex/arcane.png)

- [Documentation d'Arcane](https://getarcane.app/docs/)
- [Arcane sur GitHub](https://github.com/getarcaneapp/arcane)

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

```bash [Terminal]
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 :

```yaml [compose.yaml]
---
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 :

```yaml [compose.yaml]
---
services:
  arcane:
    #...
    labels:
      - com.centurylinklabs.watchtower.enable=true
```
::

### Renseigner vos variables d'environnement

Remplissez le fichier `.env` :

```properties [.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](/serveex/security/pocket-id) (voir plus bas) ou [Authentik](/serveex/advanced/authentik) pour la connexion. Sinon, ne l'exposez pas avec SWAG. Utilisez plutôt un VPN comme [Wireguard](/serveex/core/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](/general/networking/dns). Et bien sûr, [à moins d'utiliser Cloudflare Zero Trust](/serveex/security/cloudflare), le port `443` de votre box doit être redirigé vers le port `443` de votre serveur dans les [règles NAT](/general/networking/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 :

```yaml [compose.yaml]
---
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.
::

```bash [Terminal]
sudo nano /srv/docker/swag/config/nginx/proxy-confs/arcane.subdomain.conf
```

Collez la configuration suivante :

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

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](/serveex/core/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 :

```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_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](/serveex/security/pocket-id#registering-an-oidc-client) nommé `arcane`, avec cette URL de callback :

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

### Activer OIDC dans Arcane

Modifiez le fichier `.env` d'Arcane et ajoutez :

```properties [.env]
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.
::
