csansoon/hostel-server-setup

Configurer un serveur Hostel

Le serveur gère la file d'attente, les utilisateurs, la configuration et la passerelle SSH. Exécutez un serveur par équipe. Les agents et les personnes s'y connectent depuis leurs propres ordinateurs (hostel-install).

1. Choisir la machine et le mode TLS

• Une machine Linux avec systemd (amd64 ou arm64 ; 2 CPU et 4 Go suffisent), ou une machine personnelle qui reste allumée. Le dépôt ne documente que le service systemd ; sur un autre OS, exécutez hostel server run avec votre propre gestionnaire de services.
• Une adresse HTTPS que les clients peuvent atteindre. L'API et la passerelle la partagent : la passerelle accepte SSH à l'intérieur d'un WebSocket sur /v1/gateway.

Mode TLS	Utilisez-le quand	Vérification client
self-signed (par défaut)	Pas de domaine ni de proxy : une adresse IP, un nom LAN, un nom VPN. Le serveur sert HTTPS avec son propre certificat.	La clé épinglée du code d'invitation.
off	Un proxy avec TLS est devant le serveur (Caddy, un équilibreur de charge cloud).	Le certificat du proxy, de manière normale.

2. Installation

En tant qu'administrateur sur la machine serveur :

curl -fsSL -o install.sh https://raw.githubusercontent.com/csansoon/hostel/main/install.sh
sudo sh install.sh --dir /usr/local/bin --server /opt/hostel

/opt/hostel/helpers reçoit les binaires pour tous les espaces (hostel-<os>-<arch>, mise-<os>-<arch>). /opt/hostel/platforms reçoit les scripts de plateforme (seul un ancien serveur les importe ; le binaire contient les plateformes par défaut).

3. Initialisation

Exécutez hostel server init en tant qu'utilisateur qui exécute le service (pas root). Dans un terminal, il demande le nom du serveur, les adresses et votre nom lorsque les indicateurs ne les donnent pas. Indicateurs :

Indicateur	Signification
--server-id	Le nom du serveur, [a-z0-9]{1,20} (par défaut : depuis le nom d'hôte). Il fait partie des noms des espaces que le serveur crée.
--listen	L'adresse API (par défaut 127.0.0.1:7410).
--tls	self-signed (par défaut) ou off.
--url	Une adresse que les clients utilisent. Répétez-la pour plusieurs. Les codes d'invitation les contiennent.
--user	Votre nom, pour le premier administrateur.
--helper-dir	Les binaires pour les espaces : /opt/hostel/helpers après install.sh --server /opt/hostel (par défaut : data_dir/helpers).
--config	Le fichier à écrire (par défaut ~/.config/hostel/server.toml).

Auto-signé, sur son propre port (ouvrir TCP 7410 dans le pare-feu) :

hostel server init --server-id demo --listen 0.0.0.0:7410 \
  --url https://hostel.example.com:7410 --user "Alice Example" \
  --helper-dir /opt/hostel/helpers

Derrière un proxy avec TLS :

hostel server init --server-id demo --tls off --listen 127.0.0.1:8000 \
  --url https://hostel.example.com --user "Alice Example" \
  --helper-dir /opt/hostel/helpers

Avec --tls off et une adresse https://, init écrit également gateway_public = "wss://hostel.example.com/v1/gateway" : les invités et les machines jointes atteignent la passerelle SSH via le proxy. Le proxy doit transférer /v1/gateway (un WebSocket) vers le serveur.

init écrit server.toml, hostel.schema.json, le répertoire de données (~/.local/share/hostel : la base de données, server_ed25519, gateway_host_ed25519, et le certificat TLS), et imprime la clé publique SSH du serveur et la première invitation d'administrateur :

Connectez votre ordinateur en tant que premier administrateur. Exécutez ceci sur votre ordinateur :

  hostel connect hostel1-...

Exécutez cette commande sur votre propre ordinateur dans les 24 heures (hostel-install).

4. Éditer server.toml

server.toml ne contient que les clés dont le serveur a besoin avant d'ouvrir sa base de données : server_id, listen, gateway_listen, gateway_public, tls, public_urls, data_dir, helper_dir, platforms_dir. init écrit helper_dir (avec --helper-dir) et, derrière un proxy, gateway_public. Vérifiez-les :

grep -E 'helper_dir|gateway_public' ~/.config/hostel/server.toml
hostel admin config check

Sans helper_dir, le serveur ne peut pas donner leur aide aux espaces, et hostel machine join ne peut pas télécharger le binaire. Sans gateway_public derrière un proxy, chaque session SSH invité et chaque machine jointe échouent.

Un exemple Caddy (Caddy transmet les mises à niveau WebSocket sans configuration supplémentaire) :

hostel.example.com {
	reverse_proxy 127.0.0.1:8000
}

Avec tls = "self-signed", le gateway_public par défaut est /v1/gateway sur la même adresse ; ne le définissez pas. Vérifiez le fichier (il imprime chaque problème et les valeurs effectives) :

hostel admin config check

Une modification de server.toml nécessite un redémarrage du serveur.

5. Le service systemd

/etc/systemd/system/hostel.service (remplacez alice par l'utilisateur qui a exécuté init) :

[Unit]
Description=Hostel server
After=network-online.target
Wants=network-online.target

[Service]
User=alice
ExecStart=/usr/local/bin/hostel server run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now hostel
journalctl -u hostel -f

hostel server run --config <fichier> sélectionne un autre server.toml. Le journal est JSON sur stderr. Si la configuration est invalide, le serveur ne démarre pas et le journal indique pourquoi.

Pour les espaces Namespace, les CLI devbox et nsc doivent être sur le PATH du service (hostel-rooms, section "Namespace").

6. La configuration dans la base de données

Tout le reste (fournisseurs, machines, plateformes et les paramètres) est le document de configuration dans la base de données. Un administrateur le modifie depuis n'importe quel ordinateur connecté. Une modification valide s'applique immédiatement, sans redémarrage.

hostel config                    # afficher le document (les membres voient les secrets comme ***)
hostel config edit               # le modifier dans $VISUAL / $EDITOR
hostel config apply file.toml    # le remplacer par un fichier (ou - pour stdin)
hostel config history            # les révisions, avec utilisateur et heure
hostel config settings           # les paramètres qui ne sont pas par défaut
hostel config settings set idle_timeout=20m

Paramètres : idle_timeout (10m), poll_timeout (5m), limit_retry (2m), port_process_offline (10m), intervals.scheduler (10s), intervals.reconcile (5m), intervals.tunnel_check (30s), intervals.presence (30s), mise.idiomatic_tools (["node", "python"]), mise.github_token, mise.agent_device (true).

Le serveur refuse une modification si une autre révision est arrivée en premier (modifiez à nouveau) ou si elle est invalide (l'erreur nomme le chemin de la clé). Machines et fournisseurs : hostel-rooms. Plateformes : hostel-platforms. Utilisateurs : hostel-users.

7. Invitations sur la machine serveur

Si personne ne peut se connecter en tant qu'administrateur, créez une invitation sur la machine serveur elle-même (elle n'utilise pas l'API) :

hostel server invite                     # un administrateur
hostel server invite --role member --name "Bob Example"

8. Sauvegardes

L'état se trouve dans le répertoire de données (~/.local/share/hostel). Sauvegardez les clés une fois (server_ed25519, gateway_host_ed25519, tls_cert.pem, tls_key.pem). Sauvegardez la base de données avec SQLite, pas avec une copie de fichier :

sqlite3 ~/.local/share/hostel/hostel.db ".backup /var/backups/hostel.db"

• Base de données perdue : les utilisateurs doivent se reconnecter ; les espaces à la demande avec cet server_id sont détruits à la prochaine réconciliation.
• server_ed25519 perdu : placez la nouvelle clé publique (hostel admin pubkey) sur chaque machine statique.
• Clé TLS perdue (auto-signé) : chaque client doit se reconnecter avec un nouveau code d'invitation.

9. Mise à jour

curl -fsSL -o install.sh https://raw.githubusercontent.com/csansoon/hostel/main/install.sh
sudo sh install.sh --dir /usr/local/bin --server /opt/hostel
sudo systemctl restart hostel

Le serveur envoie le nouvel assistant à chaque espace avant son prochain bail.

Suite

• Ajouter des espaces : hostel-rooms.
• Inviter des personnes : hostel-users.