Pular para o conteúdo principal
Versão: 0.4 · atual

Referência do instalador

ReferênciaRevisado em 11 de outubro de 2026
Aplica-se a:Excubius 0.4Funções: Instalador (administrador do Linux)
PlanosFree · Core · Pro · EnterpriseImplantaçãoAuto-hospedado

O instalador, install.sh, instala, atualiza, reinstala e desinstala o Excubius em um servidor. Ele é executado como root a partir do pacote do instalador descompactado. Esta referência lista suas opções, suas verificações prévias, as perguntas que ele faz e o que ele deixa no servidor. Para as etapas de uma instalação, consulte Instalar o Excubius.

sudo ./install.sh [options]

Opções​

OpçãoEfeito
(nenhuma)Instala. Em um servidor onde o Excubius já está instalado, oferece Upgrade (o padrão: mantém os dados e as configurações e faz somente as perguntas novas desta versão), Reinstall, Purge ou Cancel
--check-onlyExecuta somente as verificações prévias. Não altera nada
--images FILEInstala a partir de um arquivo de imagens, sem acesso ao registro. Um arquivo em images/, ao lado do script, como no pacote offline, é usado automaticamente
--answers FILENão interativo: linhas key=value, incluindo os segredos. Consulte Arquivo de respostas
--reconfigureEm uma atualização, faz todas as perguntas novamente. As respostas de TLS dadas nesse momento são aplicadas à plataforma em execução
--reinstallRemove o software instalado mantendo o banco de dados e, depois, instala fazendo todas as perguntas
--purgeExclui tudo, incluindo o banco de dados, e depois faz uma instalação nova
--uninstallRemove o software. Primeiro grava um dump final do banco de dados em <dir>/backups/ e depois remove as unidades de usuário, os contêineres, as imagens, <dir>/releases, <dir>/current, /etc/excubius e a configuração de portas rootless. Mantém os volumes do banco de dados e dos certificados, <dir>/backups, <dir>/.env e a conta de serviço, para que uma instalação posterior encontre os dados
--uninstall --purgeTambém exclui todos os volumes, o diretório de instalação inteiro com os backups, a conta de serviço que o instalador criou com o armazenamento de contêineres e os serviços de firewall que a instalação adicionou. Pede que você digite purge
--no-backupNenhum dump final do banco de dados em --uninstall ou --reinstall
--yes, -yAceita todos os valores padrão existentes; as respostas obrigatórias ainda precisam vir de --answers ou do teclado. Significa Upgrade em um servidor já instalado e confirma uma limpeza total (purge)
--dry-runMostra o que seria feito e não altera nada. Uma instalação ainda grava seus arquivos de configuração para revisão; ao lado de um .env existente, como .env.dry-run
--skip-checksContinua mesmo quando as verificações prévias falham, em sistemas sem suporte, por sua conta e risco
--help, -hMostra as opções

Estas combinações são recusadas: --uninstall com --reinstall ou --reconfigure; --purge com --reinstall; --check-only com --uninstall, --purge ou --reinstall; --reconfigure com --purge ou --reinstall.

Somente o diretório de instalação registrado é removido, nunca um caminho do sistema ou um diretório pessoal.

Verificações prévias​

VerificaçãoRequisitoQuando não é atendido
Sistema operacionalRocky Linux ou outro sistema da família RHELFalha
Versão principal9 ou 10Avisa
Arquiteturax86-64Falha
Sistema de inicializaçãosystemdFalha
Gerenciador de pacotesdnfFalha
Memória4 GiBAvisa
CPUs2 vCPUAvisa
Disco20 GiB livres em /home, onde a conta de serviço mantém as imagens e o banco de dadosAvisa
Portas80 e 443 livres, em uma instalação novaFalha
SELinuxInformado—
Registrosghcr.io e docker.io acessíveis por HTTPS, ou um arquivo de imagens legívelFalha
RelógioSincronizadoAvisa; o chrony é habilitado

Perguntas​

Pressione Enter para aceitar o valor entre colchetes. Em uma atualização, são feitas somente as perguntas introduzidas depois da versão que gravou suas respostas; Desde indica qual versão introduziu cada uma.

ChavePerguntaPadrãoFeita quandoDesde
install_dirDiretório de instalação/opt/excubiusSempre; um caminho absoluto0.2.0
service_userConta de serviço que executa a plataformaexcubiusSempre; criada se não existir, executa os contêineres em modo rootless0.2.0
public_urlURL pública que os usuários vão abrirhttps://monitoring.example.comSempre; o host dela é o nome principal do servidor0.2.0
server_aliasesOutros nomes para este servidornenhumSempre; separados por espaços, Enter para nenhum0.3.0
tls_modeComo o HTTPS é fornecidoletsencryptSempre: letsencrypt, letsencrypt-dns, selfsigned, custom, gateway ou later0.2.0
tls_cert_namesNomes a incluir no certificadoallHá aliases e o modo gera um certificado0.3.0
tls_emailE-mail da conta do Let's Encrypt—letsencrypt ou letsencrypt-dns0.2.0
tls_dns_providerProvedor de DNS da zona dos nomes—letsencrypt-dns; um ID dnsapi do acme.sh, como dns_cf, dns_dreamhost ou dns_azure0.3.0
tls_dns_credentialsCredenciais da API de DNS—letsencrypt-dns; inseridas uma a uma, sem eco0.3.0
tls_cert_fileArquivo da cadeia de certificados—custom; PEM, com o certificado do servidor primeiro0.3.0
tls_key_fileArquivo da chave privada—custom; PEM, sem frase secreta, correspondente ao certificado0.3.0
default_presetPredefinição baseenterpriseSempre: enterprise, databases ou core0.2.0
registry_user, registry_tokenUsuário do registro e token somente leitura para as imagens—Sem um arquivo de imagens0.2.0
slack_bot_tokenToken de bot do Slack—Sempre; opcional0.2.0
slack_default_channelCanal do Slack para alertas#alertsSempre0.2.0
entra_tenant_idID do locatário do Entra ID para a entrada—Sempre; opcional0.2.0
entra_client_id, entra_client_secretID do aplicativo e segredo do cliente do Entra ID—Um ID de locatário foi informado0.2.0

Os modos de TLS:

ModoUse quando
letsencryptTodos os nomes estão no DNS público apontando para o servidor e a porta 80 está acessível pela Internet
letsencrypt-dnsVocê tem credenciais de API para a zona DNS dos nomes. O servidor não precisa estar acessível pela Internet
selfsignedEm qualquer lugar. Os navegadores exibem avisos até que os usuários confiem no certificado
customSua organização emite o certificado
gatewayO TLS termina em um balanceador de carga ou proxy reverso à frente
laterHTTP simples por enquanto

Com um modo do Let's Encrypt, o instalador verifica os nomes no DNS público e, por HTTP, se eles apontam para este servidor. Quando não apontam, ele explica as alternativas e nunca para por causa disso. As respostas de TLS apenas inicializam as configurações da plataforma; depois, elas são gerenciadas em Settings › Server.

Valores gerados​

O instalador gera estes valores uma única vez e nunca os substitui: a senha do banco de dados (POSTGRES_PASSWORD), o segredo de assinatura das sessões (JWT_SECRET), a chave que criptografa os segredos armazenados (EXCUBIUS_DATA_KEY) e o token do coletor (EXCUBIUS_COLLECTOR_TOKEN). Consulte Variáveis de ambiente.

Arquivo de respostas​

Para uma instalação autônoma, passe --answers FILE com uma linha key=value por pergunta. Os segredos são incluídos nesse arquivo; proteja-o e exclua-o depois. As credenciais de DNS ficam em uma única linha, separadas por ;. Uma resposta ausente recebe o valor padrão; uma resposta obrigatória ausente ou inválida interrompe o instalador com o nome da chave, para que você complete o arquivo e o execute novamente.

Um trecho:

install_dir=/opt/excubius
service_user=excubius
public_url=https://monitoring.areito.example
server_aliases=
tls_mode=letsencrypt-dns
tls_email=ops@areito.example
tls_dns_provider=dns_cf
tls_dns_credentials=CF_Token=<token>
default_preset=enterprise
registry_user=<registry user>
registry_token=<read-only token>
slack_bot_token=<bot token>
slack_default_channel=#areito-alerts
sudo ./install.sh --answers ./answers.conf --yes

Atualizações e respostas com versão​

O instalador registra suas respostas que não são segredos em <dir>/install.answers, com a versão do instalador que as gravou e se aquela execução foi concluída. Em uma atualização, ele faz somente as perguntas introduzidas desde essa versão. Uma execução que não foi concluída é tratada como uma instalação nova: todas as perguntas são feitas novamente, com as respostas anteriores como valores padrão. Os segredos nunca são gravados em install.answers.

No servidor​

CaminhoO que é
<dir>/.envConfiguração e segredos; modo 0600, pertencente à conta de serviço
<dir>/install.answersSuas respostas que não são segredos, a versão que as gravou e se aquela execução foi concluída
<dir>/currentA versão instalada, um link para <dir>/releases/
<dir>/backupsDumps diários do banco de dados, os 14 últimos mantidos, além do dump final de uma desinstalação
~<service account>/.config/systemd/user/excubius.service e o timer de backup
/var/log/excubius-install.logO log do instalador, sem segredos

Como a conta de serviço:

sudo -iu excubius
export XDG_RUNTIME_DIR=/run/user/$(id -u) # once per shell, for systemctl --user
systemctl --user status excubius # the platform
<dir>/current/scripts/compose.sh ps # the containers
<dir>/current/scripts/compose.sh logs -f backend # the API's log
<dir>/current/scripts/backup-db.sh # a database backup now
<dir>/current/scripts/enable-tls.sh --status # TLS without the console
<dir>/current/scripts/rollback.sh # back to the previous release