csansoon/hostel-server-setup

Hostel サーバーのセットアップ

サーバーはキュー、ユーザー、設定、SSH ゲートウェイを管理します。チームごとに1台のサーバーを実行します。エージェントとユーザーは各自のコンピュータ（hostel-install）から接続します。

1. マシンと TLS モードの選択

• systemd 搭載の Linux マシン（amd64 または arm64、2 CPU・4 GB で十分）、または常時稼働するホームマシン。リポジトリでは systemd サービスのみを文書化しています。他の OS では、hostel server run を独自のサービス管理ツールで実行してください。
• クライアントが到達可能な HTTPS アドレス1つ。API とゲートウェイはそのアドレスを共有します。ゲートウェイは /v1/gateway 上の WebSocket 内で SSH を受け入れます。

TLS モード	使用するケース	クライアントの確認方法
self-signed（デフォルト）	ドメインなし、プロキシなし：IP アドレス、LAN 名、VPN 名。サーバーは独自の証明書で HTTPS を提供します。	招待コードから取得したピン留めされた鍵。
off	サーバーの前に TLS 対応プロキシがある場合（Caddy、クラウドロードバランサー）。	通常の方法でプロキシの証明書を確認。

2. インストール

サーバーマシンの管理者として以下を実行します：

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 にはすべてのルーム用のバイナリ（hostel-<os>-<arch>、mise-<os>-<arch>）が格納されます。/opt/hostel/platforms にはプラットフォームスクリプトが格納されます（古いサーバーのみがインポート、バイナリにはデフォルトのプラットフォームが含まれます）。

3. 初期化

サービスを実行するユーザー（root 以外）で hostel server init を実行します。ターミナル上で、フラグで指定されていない場合はサーバー名、アドレス、ユーザー名を対話的に尋ねられます。フラグ：

フラグ	意味
--server-id	サーバー名、[a-z0-9]{1,20}（デフォルト：ホスト名から生成）。サーバーが作成するルーム名の一部として使用されます。
--listen	API アドレス（デフォルト 127.0.0.1:7410）。
--tls	self-signed（デフォルト）または off。
--url	クライアントが使用するアドレス。複数の場合は繰り返し指定。招待コードに含まれます。
--user	初回管理者の名前。
--helper-dir	ルーム用のバイナリディレクトリ：install.sh --server /opt/hostel 実行後は /opt/hostel/helpers（デフォルト：data_dir/helpers）。
--config	書き込む設定ファイル（デフォルト ~/.config/hostel/server.toml）。

自己署名証明書、独自ポート（ファイアウォールで TCP 7410 を開放）：

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

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

--tls off かつ https:// アドレスの場合、init は gateway_public = "wss://hostel.example.com/v1/gateway" も書き込みます。ゲストや参加済みマシンはプロキシ経由で SSH ゲートウェイに到達できます。プロキシは /v1/gateway（WebSocket）をサーバーに転送する必要があります。

init は server.toml、hostel.schema.json、データディレクトリ（~/.local/share/hostel：データベース、server_ed25519、gateway_host_ed25519、TLS 証明書）、およびサーバーの SSH 公開鍵と初回管理者招待を出力します：

Connect your computer as the first admin. Run this on your computer:

  hostel connect hostel1-...

自分のコンピュータでそのコマンドを24時間以内に実行してください（hostel-install）。

4. server.toml の編集

server.toml には、サーバーがデータベースを開く前に必要なキーのみが含まれます：server_id、listen、gateway_listen、gateway_public、tls、public_urls、data_dir、helper_dir、platforms_dir。init は helper_dir（--helper-dir 使用時）と、プロキシ背後では gateway_public を書き込みます。確認：

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

helper_dir がない場合、サーバーはルームにヘルパーを提供できず、hostel machine join もバイナリをダウンロードできません。プロキシ背後で gateway_public がない場合、すべてのゲスト SSH セッションと参加済みマシンが失敗します。

Caddy の例（Caddy は追加設定なしで WebSocket アップグレードを透過）：

hostel.example.com {
	reverse_proxy 127.0.0.1:8000
}

tls = "self-signed" の場合、デフォルトの gateway_public は同じアドレスの /v1/gateway になります。設定しないでください。ファイルを確認（各問題と有効な値を出力）：

hostel admin config check

server.toml の変更にはサーバーの再起動が必要です。

5. systemd サービス

/etc/systemd/system/hostel.service（alice を 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 <file> で別の server.toml を選択します。ログは stderr に JSON 形式で出力されます。設定が無効な場合、サーバーは起動せず、ログに理由が表示されます。

Namespace ルームの場合、devbox と nsc CLI がサービスの PATH に含まれている必要があります（hostel-rooms、セクション「Namespace」）。

6. データベース内の設定

その他すべて（プロバイダー、マシン、プラットフォーム、設定）は、データベース内の設定文書として管理されます。管理者は接続済みの任意のコンピュータから変更できます。有効な変更は即座に適用され、再起動は不要です。

hostel config                    # 文書を表示（メンバーはシークレットが *** と表示）
hostel config edit               # $VISUAL / $EDITOR で変更
hostel config apply file.toml    # ファイルで置き換え（- で標準入力）
hostel config history            # ユーザーと時刻付きのリビジョン履歴
hostel config settings           # デフォルト以外の設定を表示
hostel config settings set idle_timeout=20m

設定：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）。

別のリビジョンが先に到着した場合（再度編集）、または変更が無効な場合（エラーはキーパスを指定）、サーバーは変更を拒否します。マシンとプロバイダー：hostel-rooms。プラットフォーム：hostel-platforms。ユーザー：hostel-users。

7. サーバーマシン上での招待

管理者としてログインできない場合、サーバーマシン上で直接招待を作成します（API は使用しません）：

hostel server invite                     # 管理者招待
hostel server invite --role member --name "Bob Example"

8. バックアップ

状態はデータディレクトリ（~/.local/share/hostel）にあります。鍵は一度バックアップします（server_ed25519、gateway_host_ed25519、tls_cert.pem、tls_key.pem）。データベースはファイルコピーではなく SQLite でバックアップします：

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

• データベースを紛失：ユーザーは再接続が必要。この server_id のオンデマンドルームは次の reconcile で破棄されます。
• server_ed25519 を紛失：新しい公開鍵（hostel admin pubkey）を各静的マシンに設定します。
• TLS 鍵を紛失（自己署名）：各クライアントは新しい招待コードで再接続が必要。

9. アップデート

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

サーバーは次のリース前に各ルームに新しいヘルパーを送信します。

次のステップ

• ルームを追加：hostel-rooms
• ユーザーを招待：hostel-users