🌐 This page is not yet translated to English. Showing Portuguese (BR) reference. Help translate this page on GitHub.

Instalador one-liner (Linux / macOS)

Forma rápida de subir o RoqueOS Server numa máquina Linux ou macOS. Funciona em fresh install e em update, o script é idempotente.

Pré-requisitos

Linux Ubuntu 22.04+ ou Debian 12+ (Mint, Pop!_OS, derivados também funcionam) OU macOS 13+
Docker instalado (docker --version retorna ≥ 24.x)
Porta 27021 liberada no firewall (sudo ufw allow 27021/tcp no Ubuntu)
4 GB RAM mínimo (recomendado 8 GB), 20 GB de disco livre

Não precisa instalar nada manualmente além do Docker, o script cuida do resto.

Comando padrão

bash

curl -fsSL https://roqueos.com.br/install.sh | bash

Em ~2 min você tem roqueos-server rodando em http://localhost:27021.

A próxima coisa que você vê depois do install.sh terminar é o passo de criar a primeira API Key admin no painel web em http://<seu-ip>:27021/admin. Salve apiKey + apiSecret em local seguro, é mostrado uma única vez.

Flags úteis

bash

# Instalar + habilitar RoqueClaw (agente IA, +2 GB imagem)
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --with-roqueclaw

# Instalar + habilitar Cloud Gaming (Android na nuvem, +1.5 GB imagem)
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --with-android-gaming

# Instalar + habilitar Windows Apps (roda .exe via Wine, +1.5 GB imagem)
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --with-windows-apps

# Instalar + habilitar RoqueOffice (edita .docx/.xlsx/.pptx, OnlyOffice, +2 GB)
# ⚠️ precisa de um SUBDOMÍNIO público próprio pro editor, ver a seção abaixo
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- \
  --with-office --office-url https://office.seudominio.com

# Atualizar uma instância existente (preserva config + secrets + volumes)
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update -y

# Atualizar + liberar espaço (prune imagens dangling depois do pull)
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update -y --force-image-prune

# Subir em porta diferente (ex.: 8080 já em uso pelo seu app)
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --port 8080

# Diretório de dados custom
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --data-path /mnt/raid/roqueos

# Mapear pastas/drives pro app Arquivos sem prompt (repetível), formato PATH=NOME
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- \
  --map-drive /mnt/media=midia --map-drive /srv/docs=documentos

# Não-interativo (CI, scripts), auto-confirma prompts
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --with-roqueclaw -y

Flag completa (curl ... | bash -s -- --help):

Flag	Descrição
`--with-roqueclaw`	Instala agente IA OpenClaw (~2 GB imagem extra)
`--with-android-gaming`	Instala Cloud Gaming (Android emulado + ws-scrcpy, ~1.5 GB)
`--with-windows-apps`	Instala Windows Apps (roda `.exe` via Wine + noVNC, ~1.5 GB)
`--with-office`	Instala RoqueOffice (OnlyOffice, edita `.docx/.xlsx/.pptx`, ~2 GB)
`--with-app-maker-public`	Liga a rota pública do Criar App (publicar apps na internet), OFF por padrão
`--office-url URL`	URL HTTPS pública do editor (ex.: `https://office.seudominio.com`), ver abaixo
`--port PORT`	Porta do servidor (default: 27021)
`--data-path PATH`	Diretório de dados persistente (default: `/data/roqueos`)
`--map-drive PATH=NAME`	Mapeia pasta/drive pro app Arquivos sem prompt (repetível)
`--update`	Força recreate do container mesmo se digest está igual (use após config tweaks)
`--force-image-prune`	Após update, `docker image prune -f` libera disco
`-y`, `--yes`, `--skip-prompts`	Auto-confirma prompts (não-interativo)
`--help`	Mostra ajuda completa

RoqueOffice, precisa de um subdomínio público próprio

O RoqueOffice é o único recurso que precisa de uma URL HTTPS pública própria. Os demais (RoqueClaw, Cloud Gaming, Windows Apps) são acessados através do seu servidor RoqueOS (noVNC proxiado), então basta a URL principal do servidor. O OnlyOffice é diferente: o navegador do usuário carrega o editor direto de --office-url, e o OnlyOffice gera as URLs internas (cache do documento) no raiz daquele host: por isso um proxy em sub-path não funciona; ele tem que viver no raiz de um subdomínio (ex.: office.seudominio.com).

Você indica esse subdomínio com --office-url. O que o instalador faz a partir daí depende da sua infra:

Sua infra	O que o instalador faz	O que você faz
Cloudflare Tunnel (configurado em Server Admin)	Cria automaticamente o registro DNS (CNAME proxied → `<tunnel>.cfargotunnel.com`) e a regra de ingress do tunnel para `office.<domínio>`	Só passar `--with-office --office-url https://office.<domínio>`
Outro reverse proxy (nginx/Caddy/Traefik)	Sobe o container OnlyOffice na porta `9090`	Apontar `office.<domínio>` (HTTPS) → `http://localhost:9090`
Mesma máquina / LAN	Usa `http://localhost:9090` (default, sem `--office-url`)	Nada, funciona local

💡 Ordem recomendada com Cloudflare: configure o Cloudflare Tunnel primeiro (Server Admin → Cloudflare), depois rode --with-office --office-url https://office.<domínio>. Assim o instalador acha as credenciais e cria DNS + rota sozinho.

O passo do install termina com um resumo do RoqueOffice dizendo exatamente em que pé está: Ready (publicado), Action needed (falta a URL pública) ou Almost there (URL dada, mas a parte do Cloudflare não fechou, com o comando manual). Um --office-url é persistido e sobrevive a --update (um --update simples não desliga o office).

Busca na web dos agentes (Tavily)

Para o app Agentes poder pesquisar na internet (a ferramenta roqueos_web_search), o servidor precisa de uma chave da Tavily (tem free tier). Passe a chave na variável de ambiente TAVILY_API_KEY ao rodar o install:

bash

TAVILY_API_KEY=tvly-SUA_CHAVE bash <(curl -fsSL https://roqueos.com.br/install.sh) --update -y

A chave é persistida (no .roqueos-secrets.env, junto com os outros secrets) e sobrevive a --update, então você só precisa passar uma vez; updates futuros mantêm a busca ligada. Sem a chave, a ferramenta aparece nos agentes mas avisa que não está configurada (não quebra nada).

O que o `--update` preserva

Esta é a invariante mais importante do script: o update NUNCA perde config. Pode rodar quantas vezes quiser, sem medo.

Preservados (sobrevivem a --update --force-recreate):

✅ JWT_SECRET, ENCRYPTION_KEY, GUACAMOLE_CRYPT_KEY (em /data/roqueos/.roqueos-secrets.env)
✅ Config do RoqueOffice (OFFICE_JWT_SECRET + OFFICE_DOCSERVER_URL no mesmo arquivo de secrets), um --update simples mantém o office ligado
✅ TAVILY_API_KEY (busca na web dos agentes), no mesmo arquivo de secrets; um --update simples mantém a busca ligada
✅ Banco SQLite (volume Docker roqueos-db)
✅ Arquivos dos usuários (/data/roqueos/users/)
✅ Cache de transcoding (volume roqueos-transcode-cache)
✅ Config de Cloudflare Tunnel (tunnel token, rotas)
✅ API Keys cadastradas
✅ Network Storage configurados (SMB/NFS)
✅ Containers instalados via App Store
✅ Features opt-in ligadas (Windows Apps, RoqueShield, Cloud Gaming, RoqueOffice, rota pública do Criar App), ficam no server-config.json do volume, então um --update mantém tudo o que já estava on

Rota pública do Criar App (`--with-app-maker-public`)

Nasce desligada de propósito: ligar deixa o HTML que um usuário gerou no Criar App alcançável por uma URL a partir do domínio do servidor. Passe --with-app-maker-public (num install ou --update) para ligar. A publicação reusa o módulo de static-sites, então herda os modos de acesso (aberto, senha, contatos) e o portão. Depois de ligar, o toggle "Publicar na internet" aparece no Criar App e cada app publicado ganha um endereço público com SEO próprio (title, description, og:image).

Único cenário onde update PODE perder dados: se você apagar manualmente o volume roqueos-db ou o diretório /data/roqueos/. O script nunca faz isso sozinho.

Auto-rollback em falha

Se o update falhar (smoke check em /health não responde 200 dentro de 60s), o script automaticamente:

Detecta falha via smoke_check_post_update
Restaura a imagem tagada como :previous (gerada antes do docker pull)
Recria o container com a versão anterior
Sai com erro descritivo no stderr

Você nunca fica num estado degradado por bug de version nova.

Rollback manual

bash

# Lista versões disponíveis
docker images roqueribeiro1988/roqueos-server

# Volta pra versão específica
docker stop roqueos-server && docker rm roqueos-server
docker run -d --name roqueos-server --restart unless-stopped -p 27021:27021 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /data/roqueos/users:/data/roqueos/users \
  -v /data/roqueos/shared:/data/roqueos/shared \
  -v roqueos-db:/app/data \
  -v roqueos-transcode-cache:/app/transcode-cache \
  --env-file /data/roqueos/.roqueos-secrets.env \
  -e NODE_ENV=production \
  roqueribeiro1988/roqueos-server:v1.0.13   # ← versão desejada

Cloud provisioning (4 flags internas)

Estas flags NÃO são pra você usar manualmente, são consumidas pelo cloud-init que provisiona VMs do RoqueOS Cloud. Documentadas aqui por completude:

Flag	Função
`--customer-id ID`	UID do cliente cloud
`--tier NAME`	`starter` / `pro` / `power`
`--provisioning-token TOKEN`	Token hex one-time (64 chars, expira 30 min)
`--provisioning-callback URL`	Cloud Function endpoint que registra o admin key

Quando as 4 estão presentes, install.sh chama POST /admin/setup localmente, pega {apiKey, apiSecret} e POSTa pro callback. Ver provisioning flow.

Troubleshooting

Sintoma	Diagnóstico
`docker: command not found`	Instalar Docker primeiro: `curl -fsSL https://get.docker.com \| sh`
`port 27021 already in use`	Outro processo na porta. `sudo lsof -i :27021` pra descobrir; usar `--port 8080`
`permission denied` no `/var/run/docker.sock`	Adicionar user no grupo docker: `sudo usermod -aG docker $USER` (re-login depois)
`/health` 502 após boot	Container ainda subindo. Aguarde 30s e teste de novo. Se persiste: `docker logs roqueos-server`
Update falha com "image pull rate limit"	Docker Hub anônimo limita pulls. Login: `docker login` ou aguardar 6h

Logs em tempo real:

bash

docker logs -f roqueos-server

Status detalhado:

bash

curl -sS http://localhost:27021/health | python -m json.tool

Próximos passos

Acessar http://<seu-ip>:27021/admin no navegador
Criar primeira API Key admin
Login em https://roqueos.com.br/app
Settings → Server → "Adicionar servidor" → colar URL + apiKey + apiSecret
Ver wizard de bootstrap pra detalhes do passo a passo

Referências

Atalhos PowerShell pra Windows: versão Windows do mesmo script
Volumes e backup: o que persiste entre updates
App Store de containers: instalar Plex/Nextcloud/etc com 1 clique
RoqueClaw setup: habilitar o agente IA depois

Instalador one-liner (Linux / macOS) ​

Pré-requisitos ​

Comando padrão ​

Flags úteis ​

RoqueOffice, precisa de um subdomínio público próprio ​

Busca na web dos agentes (Tavily) ​

O que o --update preserva ​

Rota pública do Criar App (--with-app-maker-public) ​

Auto-rollback em falha ​

Rollback manual ​

Cloud provisioning (4 flags internas) ​

Troubleshooting ​

Próximos passos ​

Referências ​

Instalador one-liner (Linux / macOS)

Pré-requisitos

Comando padrão

Flags úteis

RoqueOffice, precisa de um subdomínio público próprio

Busca na web dos agentes (Tavily)

O que o `--update` preserva

Rota pública do Criar App (`--with-app-maker-public`)

Auto-rollback em falha

Rollback manual

Cloud provisioning (4 flags internas)

Troubleshooting

Próximos passos

Referências