Wiki

Instalar no Ubuntu / Debian

O pacote .deb: as três perguntas, o diretório de dados, a instalação off-line, o backup e a desinstalação.

Ubuntu 24.04+, Debian 13+ (x86_64). Dois comandos, três perguntas.

Instalar

1. Baixar o pacote

A partir da máquina que hospedará o servidor, em uma sessão comum:

cd /tmp && wget -N https://uversion.io/downloads/server/uversion-server_latest_amd64.deb

A URL _latest_ sempre aponta para a versão publicada mais recente. A flag -N diz ao wget para baixar novamente apenas se o arquivo remoto for mais recente: útil para atualizar sem acumular cópias .deb.1, .deb.2, etc. cd /tmp evita um aviso cosmético do apt ("unsandboxed as root") quando o .deb está no seu diretório home.

2. Iniciar a instalação

Um único comando, no diretório onde você acabou de baixar o pacote:

sudo apt install ./uversion-server_latest_amd64.deb

O instalador faz então três perguntas, na ordem dos três passos a seguir. Elas aparecem em um diálogo azul em tela cheia: você se desloca com Tab e confirma com Enter.

3. Responder: o diretório de dados

Padrão: /var/lib/uversion. É onde aterrissa o conteúdo dos seus arquivos versionados, ou seja, o diretório que cresce, portanto aquele que você quer no seu disco grande. Nem todo caminho é aceito: a seção Escolher um diretório de dados dá as quatro regras, e o instalador recusa nomeando a regra infringida.

A primeira pergunta do instalador do Debian, em um diálogo azul em tela cheia: o caminho do diretório de dados, pré-preenchido com /var/lib/uversion.

4. Responder: colocar o banco de dados também no diretório de dados?

Padrão: não. É a pergunta de maior consequência da instalação, e esse padrão tem um custo que convém conhecer antes de deixá-lo como está.

Essa resposta decide se um único disco basta para reconstruir seu servidor.

Não (padrão): o banco de dados PostgreSQL permanece no diretório do sistema (/var/lib/postgresql), separado dos seus dados. Se a máquina morrer, o disco de dados sobrevivente contém o conteúdo dos arquivos, mas nenhuma revisão, nenhuma conta, nenhum bloqueio e nenhuma permissão. Não é um servidor que se reinicia: é um monte de bytes.
Sim: o instalador cria um banco de dados dedicado dentro do diretório de dados e escreve ali um procedimento de recuperação. Um único disco sobrevivente, mais PostgreSQL e este pacote, bastam então para reconstruir o servidor em outra máquina.

Duas contrapartidas a conhecer antes de responder sim. Esse diretório de banco de dados só pode ser reaberto pela versão maior do PostgreSQL que o criou, de modo que uma reconstrução daqui a vários anos pode exigir instalar explicitamente essa versão. E o disco passa então a carregar também a chave de licença, o segredo JWT e a senha do banco de dados: trate-o como um segredo. Essa resposta muda mais tarde com sudo dpkg-reconfigure uversion-server.

5. Responder: o código de ativação

Obrigatório, a menos que já haja uma licença na máquina ou no disco escolhido no passo 3: nesse caso o instalador avisa você em uma mensagem dedicada e não faz a pergunta, porque um código de ativação é de uso único e o seu já foi consumido pela máquina de onde vem esse disco.

O campo aceita três formas, que é a sua saída se a máquina não tiver Internet: o código curto UV-XXXX-XXXX-XXXX, um caminho absoluto para um arquivo que contenha sua chave de licença completa, ou essa chave completa colada diretamente (uma longa sequência que começa com eyJ). Somente com a primeira forma o instalador contata licence.uversion.io para trocar o código pela chave completa.

6. Anotar o que aparece no final

A instalação termina em uma caixa colorida: usuário admin, senha temporária, endereço do servidor e impressão digital do certificado. Anote-os: o arquivo que contém essa senha é excluído assim que você a altera.

O resumo exibido no fim da instalação: usuário admin, senha temporária e endereço do servidor.

Em seguida, você pode seguir Primeiro login.

Uma instalação interrompida é reiniciada sem risco. Se você fechar a janela, se a rede cair ou se o instalador parar em um erro, basta relançar o mesmo comando apt install. Seu código de ativação não se perde de novo: assim que ele é trocado, a chave obtida é gravada no disco e reutilizada nas tentativas seguintes. E para voltar a qualquer resposta depois, sem reinstalar: sudo dpkg-reconfigure uversion-server. É o comando de recuperação universal desta página.

Escolher um diretório de dados que o instalador aceite

Quatro regras. As três primeiras são verificadas antes de o seu código de ativação ser consumido, então uma recusa não custa nada a você: você corrige e recomeça.

Nem sob /home, nem sob /root. O servidor roda sob uma conta de sistema deliberadamente privada de qualquer acesso aos diretórios pessoais: ele nunca poderia ler nem escrever ali, e não iniciaria.
Nenhum espaço no caminho. O caminho é copiado tal como está para as configurações do serviço, onde um espaço separa dois valores. Um disco externo montado automaticamente sob um nome como /media/jean/My Book cai exatamente nisso.
Um caminho absoluto, ou seja, começando por /.
Cada diretório pai deve deixar passar as contas uversion e postgres. É a armadilha menos evidente, e ela não aparece quando se instala como root: um diretório pai criado à mão e fechado (por exemplo um /perforce em root:root 0750, herdado de um depósito Helix) deixa passar toda a instalação e depois bloqueia o serviço no primeiro acesso. O sintoma é um serviço que se recusa a iniciar com status=200/CHDIR, ou um "Permission denied" na primeira escrita.

Para verificar este último ponto antes de lançar a instalação, exiba as permissões de toda a cadeia de diretórios que leva à sua escolha:

namei -l /srv/uversion        # remplacez par le chemin que vous voulez utiliser

Cada linha deve trazer um x na última coluna de permissões (a dos "outros"). Se faltar algum, o instalador nomeia o diretório culpado e o comando exato a executar, do tipo sudo chmod o+x /le/dossier. Ele nunca modifica por conta própria um diretório que não lhe pertence: abrir um acesso na sua árvore é sua decisão, não a dele.

Para onde vão os arquivos

Dois locais, e apenas um dos dois segue você se você mudar o diretório de dados.

No diretório de dados (o da pergunta 1): o conteúdo dos seus arquivos versionados (sob data/chunks), o certificado TLS e sua impressão digital (sob data/tls), a identidade do servidor (server-id, last-validated-at), a senha inicial de administrador (initial-admin-password, apagada assim que você a altera), o banco de dados PostgreSQL (pgdata) e o kit de recuperação (recovery) se você respondeu sim à pergunta 2.

Em /etc/uversion/, que nunca se move: o arquivo de configuração config.toml, a cópia nua da chave de licença (licence-key) e a senha do banco de dados (db-password).

Todos os comandos desta página usam <data-dir> no lugar de um caminho fixo, porque esse caminho é aquele que você escolheu. Para ler o valor real em uma máquina já instalada:

sudo sed -n 's/^WorkingDirectory=//p' /etc/systemd/system/uversion-server.service.d/10-data-dir.conf

Verificar a instalação

Três verificações independentes, a passar nesta ordem: o serviço roda, ele escuta, e não sinalizou nada.

1. O serviço roda

systemctl status uversion-server

Esperado: active (running). Qualquer outro valor remete à resolução de problemas.

2. O servidor escuta em HTTPS na 8443

ss -tlnp | grep 8443

Uma linha deve aparecer. Se nada sair enquanto o serviço roda, em geral é porque o TLS foi desativado na configuração: o servidor passa então a HTTP simples e a 8443 deixa de escutar por completo.

3. Os logs não mostram erro

sudo journalctl -u uversion-server -n 50

journalctl é o leitor de logs do sistema: é onde o servidor escreve o que faz, e o primeiro lugar para olhar quando algo não inicia.

Reexibir a impressão digital do certificado

Substituindo <data-dir> pelo valor lido acima:

sudo cat <data-dir>/data/tls/fingerprint

Reexibir a senha inicial de administrador

Enquanto não tiver sido alterada, ela ainda está no disco:

sudo cat <data-dir>/initial-admin-password

"No such file or directory" aqui significa que a senha já foi alterada: é o comportamento esperado, o arquivo é excluído nesse momento.

Instalação não interativa e off-line

Duas necessidades diferentes, um mesmo mecanismo: preencher as respostas de antemão antes de lançar o apt, de modo que nenhuma pergunta apareça. O sistema que armazena essas respostas se chama debconf, e é pilotado pela linha de comando.

1. Preencher de antemão as três respostas

Uma linha por pergunta, exatamente as três da instalação interativa:

echo 'uversion-server uversion-server/data-dir string /srv/uversion' | sudo debconf-set-selections
echo 'uversion-server uversion-server/db-on-data-dir boolean true'   | sudo debconf-set-selections
echo 'uversion-server uversion-server/licence-key string UV-XXXX-XXXX-XXXX' | sudo debconf-set-selections

2. Instalar sem diálogo

Como as respostas já estão no lugar, a instalação não pergunta mais nada:

sudo DEBIAN_FRONTEND=noninteractive apt install -y ./uversion-server_latest_amd64.deb

Variante off-line: dar a chave em vez do código

Em uma rede sem acesso à Internet, o código de ativação não pode ser trocado: não há ninguém a contatar. Recupere então sua chave de licença completa a partir da sua área de conta em um posto conectado, coloque-a na máquina e dê o caminho do arquivo em vez do código, no passo 1 acima. É a única saída, e ela está prevista:

echo 'uversion-server uversion-server/licence-key string /root/uversion-licence.key' | sudo debconf-set-selections

O arquivo deve conter a chave sozinha, em uma linha, sem aspas nem outro conteúdo em volta. Um config.toml inteiro apontado por engano é recusado explicitamente. Terceira forma possível, se você preferir não colocar um arquivo: colar a chave completa diretamente no valor, no lugar do caminho.

Fazer backup antes de qualquer operação arriscada

Três coisas a copiar, e elas não são copiadas da mesma maneira: o banco de dados (contas, revisões, bloqueios, permissões), o diretório de dados (o conteúdo dos arquivos) e a configuração, que vive em outro lugar e que é a que se esquece.

1. O banco de dados

Ele é copiado como a conta postgres, nunca como root: o PostgreSQL não tem nenhum "papel" (sua palavra para uma conta de banco de dados) chamado root, então o comando lançado diretamente como root falha com uma mensagem que parece uma pane quando é uma questão de identidade.

Se você respondeu não à pergunta sobre o banco de dados (o padrão), ele vive no cluster do sistema:

sudo -u postgres pg_dump -Fc uversion > /tmp/uversion.dump

Se você respondeu sim, ele vive em um cluster separado, que é preciso nomear explicitamente, senão você faz backup do errado:

pg_lsclusters                                    # repere la ligne "uversion" et sa version
sudo -u postgres pg_dump --cluster <major>/uversion -Fc uversion > /tmp/uversion.dump

2. O diretório de dados

Serviço parado, para uma cópia coerente:

sudo systemctl stop uversion-server
sudo tar czf /tmp/uversion-data.tar.gz -C <data-dir> .
sudo systemctl start uversion-server

3. A configuração

/etc/uversion/ não segue o diretório de dados e não está no banco de dados: ela carrega a chave de licença, o segredo que assina as sessões e a senha do banco de dados. Sem ela, uma restauração em máquina nova recomeça com um segredo novo, então toda a equipe é desconectada de uma vez, e é preciso pedir uma licença de novo.

sudo tar czf /tmp/uversion-etc.tar.gz -C /etc uversion

Desinstalar

Atenção: estes comandos excluem seus repositórios, o histórico, as contas de usuário e as configurações. Faça primeiro o backup da seção anterior se quiser poder voltar atrás.

1. Purgar o pacote

A purga retira o binário, o serviço, as respostas de configuração, /etc/uversion/ e a conta de sistema uversion. Ela preserva de propósito o banco de dados e o diretório de dados: são seus arquivos, um gerenciador de pacotes não os apaga pelas suas costas.

sudo systemctl stop uversion-server 2>/dev/null
sudo apt purge -y uversion-server

Não rode sudo apt autoremove --purge depois desta desinstalação. O PostgreSQL chegou como dependência deste pacote, então o apt vai propor retirá-lo, e a purga dele apaga todos os bancos de dados da máquina, inclusive os que nada têm a ver com o uVersion. O pacote coloca salvaguardas na instalação, mas o comando continua a ser evitado.

2. Seguir a sequência que a purga acabou de exibir

O banco de dados e o diretório de dados ainda estão lá, e os comandos para retirá-los dependem da sua máquina: por isso eles são calculados e impressos na tela em vez de escritos aqui.

Leia o que a purga exibe: o restante depende da sua máquina. O script de desinstalação olha onde seu banco de dados realmente está e então imprime na tela a sequência exata de comandos para o seu caso, caminhos e número de versão incluídos. Siga aquela em vez de uma receita genérica: um comando aproximado destrói ou o banco de dados errado, ou nada.

Duas armadilhas que esta sequência evita, e que explicam por que ela é calculada para você em vez de copiada de um guia:

Um DROP DATABASE sem nomear o cluster mira no servidor de banco de dados errado. Se você respondeu sim à pergunta sobre o banco de dados, o seu vive em um cluster dedicado: o comando padrão se dirige ao cluster do sistema, não encontra nada para excluir, e deixa você acreditar que está feito.
Um rm -rf do diretório de dados sem antes ter retirado o cluster deixa um banco de dados fantasma ainda declarado ao sistema, que falha a cada inicialização da máquina reclamando um diretório que não existe mais. A ordem importa: pg_dropcluster --stop, e depois a exclusão do diretório.

3. Remover o kit de recuperação

A fazer se o disco tiver que deixar seu controle (revenda, devolução de aluguel, descarte): esse diretório contém sua chave de licença, o segredo JWT e a senha do banco de dados, e ele sobrevive à purga por construção.

sudo rm -rf <data-dir>/recovery

4. Garantir que a conta de sistema se foi

Normalmente já é retirada pela purga. O comando não tem efeito se ela desapareceu:

sudo deluser --system uversion 2>/dev/null || true

5. Verificar que nada resta

Quatro verificações, cada uma com o que você deve ler ao lado:

systemctl status uversion-server         # "not-found" ou "inactive"
ls /etc/uversion 2>&1                    # "No such file"
id uversion                              # "no such user"
sudo -u postgres psql -tAc "SELECT 1 FROM pg_database WHERE datname='uversion';"   # (vide)