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

Instalação do RoqueOS Server

Transforme o RoqueOS em uma poderosa plataforma self-hosted de cloud computing. Instale com Docker e libere terminal Linux, navegador remoto, App Store Docker, gerenciador de arquivos e muito mais.

Pré-Requisitos

PRÉ-REQUISITOS

Você precisará de uma máquina rodando Linux (Ubuntu/Debian recomendados) ou macOS/Windows com Docker e Docker Compose instalados.

Não tem Docker? Instale o Docker Engine antes de continuar.

Instalação recomendada (one-liner)

A forma rápida — install.sh (Linux/macOS) e install.ps1 (Windows) cuidam de tudo: pulla as imagens, gera secrets criptográficos, configura volumes, sobe os containers e mostra o painel admin de boas-vindas.

Linux / macOSWindows

bash

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

powershell

irm https://roqueos.com.br/install.ps1 | iex

Em ~2 minutos o servidor está rodando em http://localhost:27021. Detalhes completos das flags (--update, --with-roqueclaw, --with-android-gaming, rollback automático): Instalador Linux/macOS ou Windows.

💡 Próximo passo

Depois do servidor rodando, conecte ele ao seu RoqueOS web via Add Server Wizard. Ou se quiser testar Server Mode antes de instalar nada, use o Servidor Demo público que já vem pré-configurado.

Instalação manual (avançado — fallback)

Avançado

Esta seção existe pra cenários onde o one-liner acima não cobre (ex: rede sem acesso ao GitHub Container Registry, política corporativa que bloqueia curl | bash, ambiente air-gapped). Para 99% dos usuários, use o one-liner acima que automatiza tudo descrito aqui.

A instrução manual aqui pode ficar defasada — o install.sh é a fonte da verdade do fluxo correto.

Para quem prefere gerenciar os containers por conta própria.

1. Gere as chaves de segurança

O servidor requer três chaves criptográficas em produção. Gere-as com Node.js antes de continuar:

bash

node -e "console.log('JWT_SECRET=' + require('crypto').randomBytes(32).toString('hex'))"
node -e "console.log('ENCRYPTION_KEY=' + require('crypto').randomBytes(32).toString('hex'))"
node -e "console.log('GUACAMOLE_CRYPT_KEY=' + require('crypto').randomBytes(16).toString('hex'))"

Ou, se preferir OpenSSL:

bash

echo "JWT_SECRET=$(openssl rand -hex 32)"
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"
echo "GUACAMOLE_CRYPT_KEY=$(openssl rand -hex 16)"

Copie os três valores e substitua os COLE_AQUI no arquivo docker-compose.yml a seguir.

GUARDE SUAS CHAVES

Perder o JWT_SECRET ou ENCRYPTION_KEY em produção exige recriar todas as API Keys e reconectar o frontend. Armazene-os em um gerenciador de senhas ou em um arquivo .env fora do controle de versão.

NOTA TÉCNICA — GUACAMOLE_CRYPT_KEY

O Remote Desktop usa AES-256-CBC, que exige exatamente 32 bytes. O comando randomBytes(16) gera 16 bytes aleatórios representados como 32 caracteres hexadecimais — que em UTF-8 equivalem exatamente a 32 bytes. Use sempre randomBytes(16) para esta chave específica.

2. Baixe as imagens do DockerHub

bash

docker pull roqueribeiro1988/roqueos-server:latest
docker pull roqueribeiro1988/roqueos-server-ubuntu:latest

3. Crie o arquivo `docker-compose.yml`

yaml

version: '3.8'

services:
  roqueos-server:
    image: roqueribeiro1988/roqueos-server:latest
    container_name: roqueos-server
    restart: unless-stopped
    ports:
      - '27021:27021'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - roqueos-users:/data/roqueos/users
      - roqueos-shared:/data/roqueos/shared
      - roqueos-db:/app/data
      - roqueos-transcode-cache:/app/transcode-cache
    cap_add:
      - SYS_ADMIN
    shm_size: 1gb
    environment:
      - TZ=America/Sao_Paulo
      - NODE_ENV=production
      - JWT_SECRET=COLE_AQUI
      - ENCRYPTION_KEY=COLE_AQUI
      - GUACAMOLE_CRYPT_KEY=COLE_AQUI
      - UBUNTU_IMAGE=roqueribeiro1988/roqueos-server-ubuntu:latest
      - GUACD_HOST=guacd
      - GUACD_PORT=4822
    networks:
      - roqueos-network

  guacd:
    image: guacamole/guacd:1.6.0
    container_name: roqueos-guacd
    restart: unless-stopped
    networks:
      - roqueos-network

volumes:
  roqueos-users:
  roqueos-shared:
  roqueos-db:
  roqueos-transcode-cache:

networks:
  roqueos-network:
    driver: bridge

4. Inicie o servidor

bash

docker compose up -d

Streaming de mídia adaptativo (HLS)

A partir da v1.0.5, o servidor detecta automaticamente o hardware disponível e configura o pipeline de streaming de vídeo:

Perfil	CPU / RAM	Qualidades disponíveis	Encoder
low	≤ 2 cores ou ≤ 2 GB RAM	480p	Software (libx264 ultrafast)
mid	4 cores + 4 GB RAM	480p + 720p	Software ou hardware
high	≥ 6 cores + 8 GB RAM	480p + 720p + 1080p	Hardware preferencial

O cache de segmentos HLS fica no volume roqueos-transcode-cache e persiste entre reinicializações. Variáveis opcionais para ajuste fino:

Variável	Padrão	Descrição
`TRANSCODE_CACHE_MAX_GB`	`20`	Tamanho máximo do cache em GB
`TRANSCODE_MAX_CONCURRENT`	`2`	Jobs simultâneos de transcode
`TRANSCODE_PROFILE`	`auto`	Forçar perfil: `low`, `mid`, `high` ou `auto`
`TRANSCODE_HW`	`auto`	Encoder: `auto`, `none`, `nvenc`, `vaapi`, `qsv`

Agente IA — RoqueClaw (v1.0.6+)

O RoqueClaw é um agente de automação visual com IA integrado ao RoqueOS. Para habilitá-lo, adicione ao seu docker-compose.yml na seção environment do serviço roqueos-server:

yaml

- ENABLE_ROQUECLAW=true
- OPENCLAW_IMAGE=roqueribeiro1988/roqueos-openclaw:latest

O servidor baixará a imagem do agente automaticamente na primeira execução.

Acesso Direto (LAN) — expor o IP da rede local

Quando o servidor RoqueOS roda dentro de um container Docker e é acessado via domínio público ou Cloudflare tunnel, o container enxerga apenas suas próprias interfaces de rede internas (172.x.x.x) — e não a interface real do host (ex.: 192.168.1.x). Isso faz com que o card "Acesso Direto (LAN)" desapareça no gerenciador de containers do RoqueOS.

Para expor o IP real da rede local, injete a variável HOST_IP no docker-compose.yml:

yaml

environment:
  - HOST_IP=192.168.1.100 # substitua pelo IP do seu servidor na rede local

Com HOST_IP configurado, o RoqueOS exibirá sempre o endereço correto para acesso direto na rede, independentemente de como o frontend se conecta ao servidor.

Sem acesso para editar o docker-compose.yml?

Se você não puder editar o compose (servidor gerenciado por terceiros, instalação automatizada, etc.), tudo bem: o RoqueOS pede o IP da LAN diretamente na primeira vez que você abrir um app pelo gerenciador de containers. Basta digitar o IP do servidor (ex.: 192.168.1.100) e clicar em Salvar e abrir — fica salvo no seu perfil e sincroniza entre dispositivos.

Como descobrir o IP do seu servidor

Linux/macOS: ip addr ou ifconfig e anote o IP da interface eth0 ou wlan0. Windows: ipconfig e anote o "Endereço IPv4" do adaptador ativo.

Quando não é necessário

Se o frontend se conecta ao servidor diretamente pelo IP local (ex.: http://192.168.1.100:27021), o RoqueOS já detecta o IP automaticamente e HOST_IP não é necessário.

Atualizar para nova versão

Quando uma nova versão for publicada no Docker Hub, você pode atualizar de três formas:

RECOMENDADO

Use Server Admin → Versão → "Atualizar agora" dentro do RoqueOS. O assistente detecta seu método de instalação, mostra o comando exato e acompanha o restart automaticamente.

Docker ComposeScript de instalação (Linux/macOS)Script de instalação (Windows)

bash

docker compose pull && docker compose up -d --force-recreate roqueos-server

bash

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

powershell

& ([scriptblock]::Create((iwr -useb https://roqueos.com.br/install.ps1).Content)) -Update

SEUS DADOS ESTÃO SEGUROS

Os volumes Docker nomeados (roqueos-users, roqueos-shared, roqueos-db, roqueos-transcode-cache) são preservados durante a atualização. Banco de dados, configurações e arquivos não são afetados.

Verificando a Instalação

bash

curl http://localhost:27021/health

Resultado esperado:

json

{ "status": "ok", "timestamp": "2026-03-05T00:00:00.000Z", "version": "2.1.0" }

Painel de Administração

Após a instalação, o Painel de Administração está disponível em:

http://localhost:27021/api

No painel, você pode:

Criar e gerenciar Chaves de API para conectar o frontend
Monitorar containers e serviços em execução
Configurar túneis Cloudflare para acesso seguro externo

Conectando ao Frontend

Abra o RoqueOS em roqueos.com.br ou no app nativo.
Acesse Configurações → Servidor.
Insira a URL do servidor (ex: http://localhost:27021 ou https://seu-tunel.trycloudflare.com).
Cole a Chave de API gerada no painel de administração.
Clique em Conectar.

Próximos Passos

VPS & Cloud — Instale em um servidor remoto para acesso 24/7
Volumes (Discos) — Mapeie suas pastas locais no gerenciador de arquivos
App Store Docker — Instale aplicações Docker com um clique

Instalação do RoqueOS Server ​

Pré-Requisitos ​

Instalação recomendada (one-liner) ​

Instalação manual (avançado — fallback) ​

1. Gere as chaves de segurança ​

2. Baixe as imagens do DockerHub ​

3. Crie o arquivo docker-compose.yml ​

4. Inicie o servidor ​

Streaming de mídia adaptativo (HLS) ​

Agente IA — RoqueClaw (v1.0.6+) ​

Acesso Direto (LAN) — expor o IP da rede local ​

Atualizar para nova versão ​

Verificando a Instalação ​

Painel de Administração ​

Conectando ao Frontend ​

Próximos Passos ​

Instalação do RoqueOS Server

Pré-Requisitos

Instalação recomendada (one-liner)

Instalação manual (avançado — fallback)

1. Gere as chaves de segurança

2. Baixe as imagens do DockerHub

3. Crie o arquivo `docker-compose.yml`

4. Inicie o servidor

Streaming de mídia adaptativo (HLS)

Agente IA — RoqueClaw (v1.0.6+)

Acesso Direto (LAN) — expor o IP da rede local

Atualizar para nova versão

Verificando a Instalação

Painel de Administração

Conectando ao Frontend

Próximos Passos