Aller au contenu principal

Installation

L'installation Docker exécute toute la plateforme sur un seul serveur Linux, sous la forme d'une stack Docker Compose. Vous n'écrivez pas cette stack vous-même : octopize-deploy-tool vous pose quelques questions, génère tous les fichiers (.env, docker-compose.yml, la configuration Nginx, les secrets et la configuration d'Authentik), puis la démarre.

Avant de commencer​

Passez en revue les prérequis communs aux deux modes d'auto-hébergement : matériel, identifiants du registre, nom de domaine, certificat TLS, serveur SMTP et flux réseau. Vérifiez ensuite le serveur lui-même :

  • Linux. Ubuntu 22.04 LTS ou supérieur est recommandé.
  • Une version récente de docker avec le plugin Compose (à l'heure de la rédaction, docker -v = 29.4.3 et docker compose version = v5.1.3), ainsi que curl.
  • L'utilisateur qui effectue le déploiement appartient au groupe docker, voir les étapes de post-installation de Docker.
  • Python 3.13 ou supérieur pour exécuter l'outil de déploiement. À défaut, exécutez l'outil depuis son image Docker.
Docker derrière un proxy HTTP

Si le démon ou le client Docker utilise un proxy HTTP, les conteneurs Avatar n'arrivent pas à communiquer entre eux, sans afficher d'erreur. Excluez le sous-réseau Compose en ajoutant "noProxy": "172.18.0.0/16" au bloc proxies.default de /etc/docker/daemon.json ou de ~/.docker/config.json. Ce paramètre ne s'applique qu'aux conteneurs nouvellement créés.

Déplacer le stockage de Docker vers une partition plus grande

Par défaut, Docker stocke les images dans /var/lib/docker, et chaque mise à jour ajoute des images. Pour utiliser une autre partition, définissez data-root dans /etc/docker/daemon.json :

{
  "data-root": "/data/docker"
}

Déplacez-y les volumes existants, puis redémarrez le démon :

sudo systemctl daemon-reload
sudo systemctl restart docker
attention

Ne supprimez pas le volume avatar_postgres_data : il contient la base de données.

Certificat TLS​

L'outil de déploiement demande le chemin d'un certificat PEM (la chaîne complète) et celui de sa clé privée non chiffrée. Indiquez des chemins absolus, et restreignez l'accès à la clé :

chmod 600 /etc/ssl/avatar/server.key
chmod 644 /etc/ssl/avatar/fullchain.crt
Convertir un bundle PKCS#12 (.pfx) en PEM
# Clé privée, puis déchiffrée (Nginx a besoin d'une clé non chiffrée)
openssl pkcs12 -in certificate.pfx -nocerts -out server.encrypted.key
openssl rsa -in server.encrypted.key -out /etc/ssl/avatar/server.key

# Certificat et chaîne intermédiaire, concaténés en une chaîne complète
openssl pkcs12 -in certificate.pfx -clcerts -nokeys -out server.crt
openssl pkcs12 -in certificate.pfx -cacerts -nokeys -chain -out chain.crt
cat server.crt chain.crt > /etc/ssl/avatar/fullchain.crt
Générer un certificat auto-signé (déploiements de test uniquement)

Une fois l'outil de déploiement installé :

octopize-deploy-tool tasks create-self-signed-cert \
  --domain avatar.company.com \
  --output-dir /etc/ssl/avatar

Cette commande écrit fullchain.crt et server.key. Ajoutez --ip-address pour des SAN de type adresse IP, et --valid-days pour modifier la durée de validité par défaut de 365 jours.

Installer​

Toutes les commandes utilisent ./app/avatar comme répertoire de déploiement. Choisissez le répertoire de votre choix, et utilisez le même pour toutes les commandes suivantes.

1. Se connecter au registre​

Exécutez la commande docker login qu'Octopize vous a envoyée. Elle ressemble à :

docker login -u='octopize+CUSTOMER_NAME' quay.io

2. Installer l'outil de déploiement​

pip install octopize-deploy-tool

Installez-le dans un environnement virtuel : la plupart des distributions refusent les installations dans le Python système. Vous pouvez aussi l'exécuter sans l'installer, avec uv : uvx octopize-deploy-tool --help.

3. Générer la configuration​

octopize-deploy-tool install --app-root ./app/avatar

L'outil demande :

  • le nom de domaine public, un nom d'environnement (par exemple mycompany-prod) et le nom de votre organisation,
  • les chemins du certificat TLS et de la clé privée,
  • les paramètres du serveur SMTP, ou s'il faut utiliser le service d'email d'Octopize,
  • l'adresse email de l'administrateur Authentik (akadmin),
  • s'il faut activer la télémétrie d'usage, et ses identifiants si vous les avez.

Il génère lui-même tous les secrets. Rien n'est encore démarré. Pour installer sans questions interactives, voir Installer sans questions interactives.

4. Démarrer la stack​

octopize-deploy-tool start --app-root ./app/avatar

Le premier démarrage télécharge les images, crée les volumes Docker et les bases de données, et configure Authentik. Il prend quelques minutes.

5. Créer les premiers utilisateurs​

octopize-deploy-tool tasks create-users --app-root ./app/avatar \
  --admins admin@company.com \
  --users alice@company.com,bob@company.com

Chaque utilisateur reçoit un email contenant un lien pour définir son mot de passe. Voir Gestion des utilisateurs pour ajouter des utilisateurs par la suite.

6. Vérifier le déploiement​

octopize-deploy-tool tasks provision-admin --app-root ./app/avatar
octopize-deploy-tool verify --app-root ./app/avatar --test-email you@company.com

provision-admin crée la clé d'API administrateur qu'utilise verify. verify contrôle l'état de santé de l'API et envoie un email de test. Connectez-vous ensuite sur https://<your-domain>/ avec l'un des comptes que vous avez créés.

Si une vérification échoue, voir Vérification et dépannage.

Où se trouve la configuration​

octopize-deploy-tool conserve la configuration dans le répertoire de déploiement (./app/avatar dans ces pages) :

./app/avatar/
├── user_config/              # à vous : l'outil ne l'écrase jamais
│   ├── config.example.yaml   # référence commentée, écrite par `install`
│   └── config.yaml           # facultatif, vos valeurs
├── .deployment_states/       # un emplacement par configuration (v1, v2, …), conservé pour le retour arrière
│   └── currently_deployed -> v2
└── generated_files/          # ce qu'exécute Docker Compose : généré, ne pas modifier
    ├── .env
    ├── docker-compose.yml
    ├── nginx/nginx.conf
    ├── authentik/
    └── .secrets/

Vous définissez les valeurs via le questionnaire ou dans un fichier YAML sous user_config/. L'outil les reporte dans generated_files/. Ne modifiez pas generated_files/ à la main : chaque update le régénère, et une modification manuelle bloque la mise à jour suivante jusqu'à ce que vous résolviez le conflit.

Modifier une valeur​

Placez uniquement les valeurs à modifier dans un fichier YAML, et passez-le à update. Tout le reste est conservé :

change.yaml
SMTP_HOST: smtp.company.com
SMTP_PORT: 587
octopize-deploy-tool update --app-root ./app/avatar --from-config change.yaml
octopize-deploy-tool start  --app-root ./app/avatar

update affiche le diff avant de l'appliquer. start recrée les conteneurs qui ont changé.

Installer sans questions interactives​

Pour installer sans questions interactives, par exemple depuis un outil d'automatisation, partez de user_config/config.example.yaml. Ce fichier minimal suffit :

user_config/config.yaml
PUBLIC_URL: avatar.company.com
ENV_NAME: company-prod
ORGANIZATION_NAME: MyCompany
NGINX_SSL_CERTIFICATE_PATH: /etc/ssl/avatar/fullchain.crt
NGINX_SSL_CERTIFICATE_KEY_PATH: /etc/ssl/avatar/server.key
octopize-deploy-tool install --app-root ./app/avatar \
  --from-config ./app/avatar/user_config/config.yaml --non-interactive

ORGANIZATION_NAME est obligatoire, bien que config.example.yaml ne le mentionne pas.

Exécuter l'outil de déploiement depuis Docker​

Si Python 3.13 n'est pas disponible, ou si PyPI est bloqué alors que quay.io ne l'est pas, utilisez l'image de l'outil. Elle a besoin que le socket Docker et le plugin Compose soient montés :

export CP=$(docker info -f '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}')
docker run -it --rm --user "$(id -u):$(id -g)" --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  -v "$(pwd)/app/avatar:/app-root" -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(which docker):/usr/local/bin/docker:ro" -v "$CP:$CP:ro" \
  quay.io/octopize/deploy-tool:latest install --app-root /app-root

Remplacez install par n'importe quelle autre commande. Lors des questions, saisissez les chemins de l'hôte (par exemple celui du certificat TLS), car Docker Compose les lit sur l'hôte. Le README de l'outil de déploiement fournit un bloc prêt à copier pour chaque commande.

Étapes suivantes​