Aller au contenu

Manipulations manuelles — venv, account.yml et gestion des services (SSDV2)

Abstract

Cette page décrit les manipulations manuelles SSDV2 :
- chargement de l’environnement (profile.sh) et vérification du prompt (venv)
- lecture/écriture/suppression de clés dans account.yml via get_from_account_yml et manage_account_yml
- installation/désinstallation directe d’une application via launch_service et suppression_appli
- mise à jour d’image seule via update_container (sans playbook)
- application de l’authentification via apply_auth_label (label Traefik uniquement)
- sortie propre de l’environnement avec deactivate
⚠️ Toutes les opérations doivent être effectuées hors root.

TL;DR

1) ✅ Non-root uniquement
2) source profile.sh → vous voyez (venv)
3) Lire : get_from_account_yml [clé]
4) Écrire : manage_account_yml clé valeur
5) Supprimer : manage_account_yml clé " " (suppression récursive)
6) Installer : launch_service service
7) Désinstaller : suppression_appli service
8) Mettre à jour (image seule) : update_container service
9) Appliquer l’auth (label-only) : apply_auth_label service
10) Quitter : deactivate

Principe premium

Toujours auditer avant de modifier : un get_from_account_yml rapide évite d’écraser une valeur sensible.

Règle absolue : ne pas être root

Pour toute opération, assurez-vous de ne pas être root.

Pourquoi ?

Exécuter ces commandes en root peut : - casser les permissions, - créer des fichiers appartenant à root, - provoquer des comportements inattendus (venv/Docker/scripts), - compliquer les corrections (chown à répétition).

Charger l’environnement (venv)

Exécutez :

cd /opt/seedbox-compose
source profile.sh

Après cela, vous devriez voir (venv) devant l’invite de commande.

Validation

Si le prompt affiche (venv), l’environnement est chargé.

Si (venv) n’apparaît pas

  • Vérifiez le chemin : /opt/seedbox-compose
  • Relancez source profile.sh
  • Évitez de lancer le script en root (permissions cassées)

Comprendre account.yml (structure et clés)

Les clés sont séparées par des points.

Exemple YAML :

user:
  domain: mydomain.net

La clé sera :

  • user.domain
    et sa valeur :
  • mydomain.net

Pourquoi cette notation ?

Elle permet de manipuler le YAML facilement depuis la CLI, sans éditer le fichier à la main.

Afficher tout le contenu de account.yml

Pour afficher dans le shell tout le contenu du fichier :

get_from_account_yml
Bon usage

Avant une modification, faites toujours un dump complet (ou un dump du bloc parent) pour éviter les surprises.

Manipuler account.yml

Écrire une clé (create/overwrite)

Crée la clé si elle n’existe pas, ou l’écrase si elle existe :

manage_account_yml cle valeur

Exemple :

manage_account_yml user.domain mondomaine.com

Écrasement

Si la clé existe, la valeur précédente est remplacée (pas de merge).
Faites un get_from_account_yml avant si vous n’êtes pas sûr.

Pattern safe (lecture → écriture → relecture) 
get_from_account_yml user.domain
manage_account_yml user.domain mondomaine.com
get_from_account_yml user.domain

Effacer une clé (et ses sous-clés)

Efface la clé et toutes les sous-clés associées :

manage_account_yml cle " "

Exemple :

manage_account_yml user.domain " "

Suppression récursive

En supprimant une clé “parent”, vous supprimez aussi toute son arborescence.
Exemple : supprimer user peut supprimer domain/mail/pass/etc.

Avant suppression

Affichez d’abord l’arbre : 

get_from_account_yml user

Obtenir la valeur d’une clé

get_from_account_yml cle

Exemple :

get_from_account_yml user.domain

Retour attendu :

mondomaine.com

Si la valeur n’est pas trouvée :

notfound

Obtenir une clé et toutes ses sous-clés

get_from_account_yml user

Exemple de retour :

domain: mondomaine.com group: null groupid: 1001 htpwd: seed:xxxxxxxxxxxxxx mail: moi@mondomaine.com name: seed pass: xxxxxxxxxxxxxx userid: 1001

Usage

Pratique pour auditer rapidement un bloc (ex. user, traefik, apps, etc.).

Installer / lancer une application sans passer par le menu

launch_service nomduservice
Exemples 
launch_service plex
launch_service radarr
launch_service sonarr

Résultat attendu

Le service est déployé/démarré conformément à la recette (yml + account).

Désinstaller une application sans passer par le menu

suppression_appli nomduservice
Exemples 
suppression_appli plex
suppression_appli radarr
suppression_appli sonarr

Impact

Selon le mode de suppression et l’implémentation, des éléments peuvent être retirés : - container, - fichiers .yml, - entrées account.yml, - et parfois données persistantes (selon options).

Avant suppression

Si vous avez un doute : privilégiez la réinitialisation (quand disponible) plutôt qu’une suppression destructrice.

Mettre à jour une application (image seule) sans passer par le menu

update_container nomduservice

Environnement chargé

Comme toutes les fonctions de cette page, elle s’utilise après source profile.sh (section Charger l’environnement (venv)), exactement comme launch_service.

  • tire la dernière image (docker pull) ;
  • recrée le container à l’identique (config, volumes/binds, réseau, ports… conservés) ;
  • sans exécuter le playbook ni les tâches de configuration.
Exemples 
update_container plex
update_container sonarr

Équivalent ssdv2ctl

ssdv2ctl app update nomduservice

Résultat attendu

Le service tourne avec l’image à jour, configuration et données conservées.

Appliquer l’authentification d’une application (label-only)

L’authentification est stockée dans account.yml sous sub.<app>.auth. La fonction ci-dessous applique le type courant sans rejouer le playbook :

apply_auth_label nomduservice

Environnement chargé

À utiliser après source profile.sh (venv + fonctions), comme update_container et launch_service.

  • lit sub.<app>.auth ;
  • modifie uniquement le label traefik.http.routers.<app>-rtr.middlewares ;
  • recrée le container (les routers secondaires et le reste de la config sont conservés).

Changer la valeur d’abord (si besoin)

manage_account_yml sub.nomduservice.auth oauth2-proxy
apply_auth_label nomduservice

Équivalent ssdv2ctl

ssdv2ctl auth apply nomduservice oauth2-proxy

Un restart ne suffit pas

Changer l’auth modifie un label Docker : il faut recréer le container (ce que fait apply_auth_label).

Quitter l’environnement de manipulation

Pour sortir du venv :

deactivate

Validation

Le préfixe (venv) disparaît : vous êtes sorti de l’environnement.

Diagramme de flux (opérations manuelles)

flowchart TD A["Être non-root"] --> B["Charger venv\nsource profile.sh"] B --> C{"Besoin ?"} C -->|Lire account.yml| D["get_from_account_yml\n(avec ou sans clé)"] C -->|Écrire/supprimer clé| E["manage_account_yml\nclé valeur | clé \" \""] C -->|Installer/Lancer app| F["launch_service nomduservice"] C -->|Mettre à jour (image seule)| I["update_container nomduservice"] C -->|Appliquer l'auth (label-only)| J["apply_auth_label nomduservice"] C -->|Supprimer app| G["suppression_appli nomduservice"] D --> H["deactivate"] E --> H F --> H I --> H J --> H G --> H

Diagramme de séquence (édition account.yml)

sequenceDiagram autonumber actor U as Utilisateur participant V as venv (profile.sh) participant A as account.yml participant C as CLI (manage/get) U->>V: source profile.sh V-->>U: Prompt affiche (venv) U->>C: get_from_account_yml user.domain C->>A: Lecture clé user.domain A-->>C: Valeur (ou notfound) C-->>U: Affiche résultat U->>C: manage_account_yml user.domain mondomaine.com C->>A: Écrit/écrase user.domain A-->>C: OK C-->>U: Confirmation implicite U->>V: deactivate V-->>U: Sortie du venv