csansoon/hostel-server-setup

Hostel 서버 설정하기

서버는 큐, 사용자, 구성 및 SSH 게이트웨이를 유지 관리합니다. 팀당 하나의 서버를 실행합니다. 에이전트와 사람들은 자신의 컴퓨터에서 연결합니다 (hostel-install).

1. 머신 및 TLS 모드 선택

• systemd가 설치된 리눅스 머신(amd64 또는 arm64; 2 CPU와 4 GB면 충분함), 또는 항상 켜져 있는 홈 머신. 저장소는 systemd 서비스만 문서화합니다. 다른 OS에서는 자체 서비스 관리자와 함께 hostel server run을 실행하세요.
• 클라이언트가 접근할 수 있는 HTTPS 주소 하나. 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 공개 키와 첫 번째 관리자 초대를 출력합니다:

첫 번째 관리자로 컴퓨터를 연결하세요. 컴퓨터에서 다음을 실행하세요:

  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입니다. 구성이 유효하지 않으면 서버가 시작되지 않고 로그에 이유가 표시됩니다.

네임스페이스 룸의 경우 devbox 및 nsc CLI가 서비스의 PATH에 있어야 합니다(hostel-rooms, "네임스페이스" 섹션).

6. 데이터베이스의 구성

그 외 모든 것(프로바이더, 머신, 플랫폼 및 설정)은 데이터베이스의 구성 문서입니다. 관리자가 연결된 컴퓨터에서 변경합니다. 유효한 변경은 재시작 없이 즉시 적용됩니다.

hostel config                    # 문서 표시 (멤버는 비밀을 ***로 표시)
hostel config edit               # $VISUAL / $EDITOR에서 변경
hostel config apply file.toml    # 파일로 대체 (또는 -는 stdin)
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의 온디맨드 룸은 다음 조정 시 파괴됩니다.
• 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.