csansoon/hostel-rooms

Adicionar e gerenciar quartos

As máquinas estão no documento de configuração no servidor. Você deve ser um administrador (hostel-users). Cada alteração é aplicada imediatamente.

hostel config providers        # NOME, TIPO, MÁQUINAS
hostel config rooms            # MÁQUINA, TIPO, SO, PLATAFORMAS, RÓTULOS, QUARTOS
hostel config edit             # altera o TOML no $EDITOR

Uma máquina é nomeada <provider>/<machine>, ou apenas <machine> quando o nome é único. Os nomes seguem ^[a-z][a-z0-9-]*$. Os requisitos de plataforma (Xcode, Android SDK, KVM, desktop) estão em hostel-platforms.

Uma máquina atrás de NAT (ela se conecta ao servidor)

Use isso para a maioria das suas próprias máquinas: um Mac mini em casa, um PC com Windows, um Linux. A máquina mantém uma conexão de saída com o servidor. Ela não precisa de SSH de entrada da internet.

1. No seu computador, crie um código de máquina (24 horas, funciona uma vez):

   hostel config rooms add mac-mini --platform ios --label xcode-26.5 --label desktop
   hostel config rooms add win-pc --label desktop
   

   --platform e --label podem se repetir. --provider seleciona o provedor estático (padrão home; o servidor o adiciona se estiver faltando). No aplicativo: Front desk › Adicionar um quarto.

2. Execute o comando impresso na nova máquina como administrador: sudo no macOS e Linux, um PowerShell de administrador no Windows. O comando baixa hostel do seu servidor e executa hostel machine join <code>.

hostel machine join cria o usuário hostel (sem direitos de administrador), instala a chave do servidor para ele, adiciona a máquina à configuração (connect = true, SO identificado da máquina) e instala o serviço que executa hostel machine connect:

SO	Serviço	Log
Linux	unidade systemd hostel-machine-connect.service (usuário hostel-connect)	journalctl -u hostel-machine-connect
macOS	LaunchDaemon so.hostel.machine-connect	/var/log/hostel-machine-connect.log
Windows	tarefa agendada Hostel machine connect (LOCAL SERVICE)	C:\ProgramData\hostel\machine-connect.log

O token está em /etc/hostel ou C:\ProgramData\hostel; o usuário do quarto não pode lê-lo. Se uma etapa falhar, corrija-a e execute o mesmo comando novamente: ele continua. --no-service pula o serviço e imprime o comando hostel machine connect para você executar manualmente (--server <url> --token-file <file> [--server-key k] [--ssh 127.0.0.1:22]).

3. Faça as etapas que join imprime e que apenas uma pessoa pode fazer:

   • macOS: Ajustes do Sistema › Geral › Compartilhamento › Login Remoto ativado, para hostel; Xcode para iOS; para desktop, login automático de hostel e sem senha após o protetor de tela.
   • Windows: OpenSSH Server em execução e iniciando automaticamente (Get-Service sshd); para desktop, a tarefa "Hostel desktop".
   • Linux: o servidor SSH executa na porta 22 e permite login por chave para hostel.

4. Verifique: hostel status mostra o quarto em até um minuto.

Uma máquina estática que o servidor alcança via SSH

Use isso quando o servidor puder abrir TCP para a máquina (mesma LAN ou VPN). Na máquina, crie um usuário padrão hostel com a chave SSH do servidor. A chave é a saída de hostel admin pubkey (no computador de um administrador), e hostel server init também a imprimiu ("chave pública do servidor"). No Linux:

sudo useradd -m -s /bin/bash hostel
sudo install -d -m 700 -o hostel -g hostel ~hostel/.ssh
echo 'ssh-ed25519 AAAA... hostel-server' | sudo tee ~hostel/.ssh/authorized_keys
sudo chown hostel:hostel ~hostel/.ssh/authorized_keys && sudo chmod 600 ~hostel/.ssh/authorized_keys

Permita login por chave SSH para esse usuário. Mantenha o encaminhamento TCP ativado no sshd (o padrão do OpenSSH; túneis precisam dele). Em seguida, adicione-a com hostel config edit:

[providers.home]
kind = "static"

[providers.home.machines.mac-mini]
address = "[email protected]"    # usuário@host[:porta]; usuário padrão hostel, porta 22
os = "macos"                         # obrigatório: linux, macos ou windows
platforms = ["ios", "android"]       # plataformas de dispositivo; a plataforma do SO é automática
labels = ["xcode-26.5", "desktop"]
tools = { java = "21" }              # ferramentas mise no nível da máquina
env = { HOSTEL_IOS_RUNTIME = "26.5" }
# slots = [{ name = "a" }, { name = "b" }]   # dois leases por vez (padrão: um slot "a")

• slots: cada slot n recebe as portas 7500 + 10n a 7509 + 10n para túneis. Um slot pode definir ports, env e seu próprio user do SO.
• env e tools no provedor se aplicam a todas as suas máquinas; as chaves da máquina substituem chaves com o mesmo nome.
• O servidor fixa a chave do host SSH da máquina na primeira conexão.
• Windows manualmente: docs/static-room-setup.md, seção "Windows" (o usuário e as regras de acesso de authorized_keys que o OpenSSH exige).
• Para um endereço público: permita SSH de entrada apenas do servidor, ou use connect = true (o fluxo de join) e feche o SSH de entrada.

Altere uma chave sem o editor (platforms e labels são listas separadas por vírgula):

hostel config rooms set mac-mini labels=xcode-26.5,desktop
hostel config rooms set mac-mini platforms=ios

Namespace (máquinas em nuvem sob demanda)

Namespace (namespace.so) cria quartos quando um lease precisa deles: um devbox para macOS (ou Linux), uma instance para Linux. Instale ambas as CLIs como o usuário do servidor e coloque ~/.local/bin no PATH do serviço:

curl -fsSL https://get.namespace.so/cloud/install.sh | sh        # nsc
curl -fsSL get.namespace.so/devbox/install.sh | bash             # devbox
sudo mkdir -p /etc/systemd/system/hostel.service.d
printf '[Service]\nEnvironment=PATH=%s/.local/bin:/usr/local/bin:/usr/bin:/bin\n' "$HOME" \
  | sudo tee /etc/systemd/system/hostel.service.d/path.conf
sudo systemctl daemon-reload && sudo systemctl restart hostel

Do seu computador (imprime uma URL; abra-a e selecione o workspace):

hostel config providers login namespace        # --cli devbox ou --cli nsc para uma CLI
hostel config providers add ns --kind namespace

Em seguida, adicione modelos de máquina com hostel config edit:

[providers.ns]
kind = "namespace"
max_rooms = 3                        # todas as máquinas deste provedor juntas
# limits = [{ machines = ["mac"], max_rooms = 1 }]

[providers.ns.machines.mac]
spec = { product = "devbox", platform = "macos", size = "m", image = "tahoe-slim" }
platforms = ["ios"]
labels = ["xcode-26.5", "desktop"]
env = { DEVELOPER_DIR = "/Applications/Xcode_26.5.app/Contents/Developer", HOSTEL_IOS_RUNTIME = "26.5" }
max_rooms = 1
max_lifetime = "3h"                  # obrigatório para um devbox: a duração máxima do plano

[providers.ns.machines.linux]
spec = { product = "instance", machine_type = "linux/amd64:8x16" }   # opcional: image (padrão ubuntu:24.04)
platforms = ["android"]
labels = ["kvm"]
tools = { java = "21" }
max_rooms = 2

Custos e limites (verifique o plano atual no Namespace):

• O Hostel atua apenas em quartos com o prefixo de nome hostel-<server_id>-.
• Um devbox é efêmero: é excluído após cerca de 15 minutos ocioso e ao atingir seu max_lifetime. Uma instance tem um prazo fixo que o servidor estende.
• Um devbox macOS custa muito mais por minuto do que um Linux.
• Os limites do plano se aplicam a todos os leases juntos (eles compartilham um login). No plano Developer: um devbox por usuário, máximo de 3 h, sem Windows. Um erro de "limite atingido" marca a máquina como cheia por limit_retry (2 minutos).
• Apenas tipos de instance linux são suportados. Android no Namespace usa Linux.
• Um login dura dias. Quando termina, as chamadas ao provedor falham: faça login novamente.

O provedor externo (seu próprio comando)

kind = "external" executa seu comando para cada operação (capabilities, provision, resume, stop, extend, destroy, list, access) com JSON na stdin e stdout. docs/design.md, seção 7, "Contrato do provedor externo", tem o contrato completo. O repositório test/fakeprovider (contêineres Docker) é uma ferramenta de teste, não um provedor suportado.

[providers.docker]
kind = "external"
command = ["/usr/local/bin/my-provider"]
command_env = { DOCKER_HOST = "unix:///var/run/docker.sock" }
timeouts = { provision = "5m", default = "1m" }

[providers.docker.machines.small]
os = "linux"                         # obrigatório
spec = { image = "debian:13" }       # passado para seu comando como está
max_rooms = 2

Limites e quartos aquecidos (máquinas sob demanda)

Chave	Onde	Padrão
max_rooms	provedor (todas as suas máquinas) / máquina	nenhum / 1
limits	provedor: [{ machines = [...], max_rooms = N }]	[]
max_lease	provedor, máquina	2h
max_lifetime	provedor, máquina	nenhum
warm_running	provedor, máquina: manter um quarto livre em execução por este tempo	5m
warm_stopped	provedor, máquina: manter um quarto parado por este tempo	24h

Drenar, reparar, remover, destruir

hostel config rooms drain mac-mini        # sem novos leases; leases atuais continuam
hostel config rooms undrain mac-mini
hostel config rooms repair mac-mini       # verificar novamente um quarto quebrado
hostel config rooms repair mac-mini --accept-host-key
hostel config rooms destroy ns/mac        # um quarto sob demanda sem lease (dê o nome do quarto se houver vários)
hostel config rooms remove mac-mini       # remover a máquina; seus tokens de quarto são revogados
hostel config providers remove ns         # apenas sem quartos sob demanda

• Uma máquina com um lease ativo não pode ser removida: drene-a e aguarde.
• Uma máquina sob demanda não pode ser removida enquanto tiver quartos: destrua-os primeiro.
• hostel admin room drain|undrain|repair|destroy <nome ou ID do quarto> faz o mesmo por quarto.

Máquinas offline

A cada intervals.presence (30 s) o servidor verifica cada quarto estático ocioso. Um quarto que não responde fica Offline e não recebe leases. Quando ele responde novamente, o servidor o prepara novamente automaticamente. Nenhum comando é necessário. hostel status imprime offline (visto pela última vez ...). Veja hostel-troubleshoot.