Alojar Vaultwarden num VPS gerido: as suas palavras-passe no seu servidor

O que faz o Vaultwarden

O Vaultwarden é um servidor de gestão de palavras-passe escrito em Rust, concebido para o autoalojamento. O seu wiki destina-o a particulares, famílias e organizações de dimensão humana. O cofre web vem incluído nas suas imagens Docker.

Implementa uma API compatível com os clientes oficiais do Bitwarden, no navegador, no computador e no telemóvel. O README esclarece que o projeto não está associado ao Bitwarden nem à Bitwarden, Inc., e pede que qualquer problema lhe seja comunicado diretamente, seja qual for o cliente utilizado, e não aos canais de assistência oficiais.

• O cofre: cofre pessoal, anexos, ícones dos sites, chave de API pessoal, e Send para transmitir um texto ou um ficheiro.
• As organizações: coleções, partilha de palavras-passe, funções, grupos, registos de eventos e políticas.
• A autenticação de dois fatores: aplicação de autenticação, e-mail, FIDO2 WebAuthn, YubiKey e Duo.
• Os recursos de recuperação: acesso de emergência e recuperação de conta, esta última exigindo que o e-mail esteja configurado.
• A administração: uma página /admin para as definições, as contas e o diagnóstico.

O wiki enumera também o que falta em relação ao servidor oficial, como o início de sessão por chave de acesso, as funções personalizadas e algumas políticas empresariais. Esclarece que as funcionalidades sobretudo úteis às grandes organizações não são uma prioridade do projeto: leia essa lista se delas precisar.

O que permite a licença AGPL-3.0

O Vaultwarden é publicado sob a GNU Affero General Public License, versão 3. O texto afirma uma permissão ilimitada de fazer correr o programa não modificado. Pode, portanto, utilizar a imagem publicada pelo projeto para a sua empresa e a sua equipa, sem licença para comprar.

O artigo 13 acrescenta uma condição própria da AGPL: se modificar o programa, a sua versão tem de oferecer a todos os que a utilizam à distância, pela rede, o meio de obter gratuitamente o seu código-fonte.

A instalação com o Docker Compose

O README recomenda as imagens de contentor. Num servidor com o Docker instalado, crie uma pasta e coloque nela este compose.yaml, tirado do README e do wiki:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "true"
    volumes:
      - ./vw-data/:/data/
    ports:
      - 127.0.0.1:8000:80

docker compose up -d

• Uma porta publicada em 127.0.0.1: como no README, o Vaultwarden só é acessível através do proxy inverso, instalado no mesmo servidor.
• DOMAIN: o endereço de base da sua instância, em https. O wiki avisa que, sem isso, há funcionalidades que deixam de funcionar, entre as quais os anexos e as ligações de convite.
• Uma pasta vw-data num disco local: guarda todos os dados. O wiki assinala os problemas do SQLite num volume CIFS ou Samba, que não gere o bloqueio de ficheiros.
• A etiqueta latest acompanha a última versão publicada, e o wiki recomenda-a para a maioria das utilizações. Uma etiqueta como 1.37.5 fixa uma versão, e latest-alpine dá o mesmo numa base Alpine.

O seu nome de domínio aponta para o servidor com registos A e AAAA, e os visitantes chegam pelas portas 80 e 443. Enquanto o proxy inverso não estiver instalado, o cofre web fica inutilizável: passe diretamente à secção seguinte.

O projeto não quantifica nem a memória nem o processador; apresenta-se apenas como uma solução para os casos em que o serviço oficial, exigente em recursos, não convém. O tamanho depende do número de contas e do volume dos anexos. Num VPS gerido, descreva-nos a sua utilização e recomendamos-lhe o tamanho adequado.

HTTPS e WebSocket: o proxy inverso

O cofre web assenta na API Web Crypto, que os navegadores reservam aos contextos seguros: o README indica que só funciona depois de o HTTPS ser ativado, e o wiki considera o HTTPS «pretty much required», quase obrigatório. O projeto recomenda um proxy inverso à frente do Vaultwarden e desaconselha o TLS integrado na sua framework Rocket.

Escolha um certificado reconhecido, como os do Let's Encrypt, que o wiki recomenda: com um certificado autoassinado, algumas plataformas recusam a ligação. O certificado tem de incluir a cadeia completa, sem o que os dispositivos Android não se ligam.

As notificações WebSocket, ativas por predefinição, avisam o navegador, a aplicação de secretária e a extensão de que uma entrada mudou. Passam pela porta HTTP principal, e o proxy tem de transmitir os cabeçalhos Upgrade e Connection. As aplicações móveis utilizam as notificações nativas do respetivo sistema, que se configuram à parte.

Com o Caddy

O wiki aconselha a olhar primeiro para o Caddy se não tiver preferência: ativa o HTTPS por si próprio, obtém o certificado Let's Encrypt e suporta o WebSocket. A definição do wiki transmite também ao Vaultwarden o endereço real do visitante, para os seus registos:

vault.example.com {
  reverse_proxy 127.0.0.1:8000 {
    header_up X-Real-IP {remote_host}
  }
}

Com o Nginx e o Certbot

Este bloco retoma o exemplo Nginx do wiki, reduzido à porta 80 para deixar o Certbot instalar o HTTPS:

upstream vaultwarden-default {
  zone vaultwarden-default 64k;
  server 127.0.0.1:8000;
  keepalive 2;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      "";
}

server {
    listen 80;
    listen [::]:80;
    server_name vault.example.com;

    client_max_body_size 525M;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    location / {
      proxy_pass http://vaultwarden-default;
    }
}

O Certbot instala depois o certificado e encarrega-se de o renovar:

sudo certbot --nginx

Verificar o WebSocket

Abra as ferramentas de programação do navegador, separador de rede, filtro WS, e volte a ligar-se ao cofre: uma resposta 101 em /notifications/hub confirma a ligação. Outro teste do wiki: abra o cofre em dois navegadores, mude o nome de uma entrada num deles, e a alteração aparece logo no outro.

Fechar as inscrições

Por predefinição, qualquer pessoa que chegue à sua instância pode criar nela uma conta. É útil para a sua primeira conta, e o wiki recomenda fechar a seguir, para impedir um atacante de criar uma.

1. Abra o seu endereço HTTPS e crie a sua conta; depois, ligue as suas aplicações a esse endereço.
2. Passe SIGNUPS_ALLOWED a "false" no compose.yaml.
3. Reinicie com docker compose up -d: uma variável de ambiente está ligada ao contentor, que tem de ser recriado para a ter em conta.

SIGNUPS_ALLOWED: "false"

• Os convites continuam abertos depois do encerramento: os proprietários e os administradores de uma organização podem convidar novas pessoas. INVITATIONS_ALLOWED a "false" retira essa possibilidade, e o wiki deixa a escolha consoante a confiança que deposita nos seus utilizadores.
• Uma lista de domínios: SIGNUPS_DOMAINS_WHITELIST limita a inscrição a certos domínios de e-mail, e SIGNUPS_VERIFY a true impõe então a verificação do endereço. Quando esta lista está definida, SIGNUPS_ALLOWED é ignorada.
• A página de administração permite convidar qualquer pessoa, sejam quais forem estas restrições.

Assim que guardar a configuração a partir da página de administração, nasce um ficheiro config.json na pasta de dados, que prevalece sobre as variáveis de ambiente. As definições em causa passam então a mudar-se a partir dessa página: modificar o compose.yaml deixa de bastar.

A página de administração e o seu token

A página /admin serve para configurar o Vaultwarden, ver e eliminar as contas e as organizações, retirar a autenticação de dois fatores a um utilizador, convidar e ler o diagnóstico. Sem ADMIN_TOKEN, fica desativada: se não precisar dela, deixe-a assim.

O wiki recomenda vivamente ativar o HTTPS antes desta página. O token faz de palavra-passe, e pode ser guardado em forma de hash, em argon2id, em vez de em claro na configuração. O Vaultwarden fornece o comando: pede a palavra-passe duas vezes e devolve uma cadeia PHC.

docker run --rm -it vaultwarden/server /vaultwarden hash

Coloque essa cadeia num ficheiro .env, ao lado do compose.yaml, entre apóstrofos, e depois chame-a a partir do serviço:

VAULTWARDEN_ADMIN_TOKEN='$argon2id$...'

ADMIN_TOKEN: ${VAULTWARDEN_ADMIN_TOKEN}

Verifique o resultado, reinicie e depois inicie sessão em /admin com a sua palavra-passe, e não com a cadeia PHC:

docker compose config
docker compose up -d

• A sessão dura 20 minutos por predefinição, ajustáveis por ADMIN_SESSION_LIFETIME. Uma sessão aberta continua válida depois de uma mudança de token. Para as cortar todas, elimine rsa_key.pem da pasta de dados e reinicie, o que desliga também os utilizadores e anula os convites em curso.
• Um acesso reduzido: os exemplos de proxy do wiki mostram como abrir /admin apenas a certos endereços, ou acrescentar-lhe uma autenticação HTTP.
• DISABLE_ADMIN_TOKEN retira todo o controlo: está previsto para uma camada de autenticação separada colocada à frente, e o wiki reserva-o a quem sabe o que está a fazer.

O que protege o cofre

A primeira proteção é a palavra-passe mestra. Os dados do cofre são cifrados com chaves pessoais ou de organização: quem obtiver uma cópia da base de dados ou forçar uma sessão ainda tem de quebrar essa palavra-passe para os ler. A sua solidez conta, portanto, antes de mais. Uma sessão de administração permite, por si só, eliminar uma conta ou retirar uma autenticação de dois fatores, sem dar acesso aos dados do cofre.

Prepare o esquecimento da palavra-passe mestra antes de ele acontecer: ative o acesso de emergência da sua conta e, numa organização, a recuperação de conta, que exige o e-mail configurado.

Mais três definições, tiradas do guia de reforço da segurança

• Uma conta não root: a imagem corre como root por predefinição, e o wiki considera preferível dar-lhe o mínimo de direitos. Acrescente user: 1000:1000 ao serviço, com uma pasta vw-data pertencente a esse utilizador.
• Os registos do proxy: a ligação WebSocket passa um token no endereço, em access_token. Se o seu proxy guarda os registos ou os envia para um serviço externo, o wiki recomenda ocultar aí esse valor.
• O mínimo de montagens: monte a pasta de dados e mais nada, nem a sua pasta pessoal, nem /var/run/docker.sock.

SQLite, MariaDB ou PostgreSQL

A mesma imagem suporta as três bases de dados. O wiki descreve o SQLite como a mais utilizada e a mais testada, e recomenda-a para a maioria das utilizações, salvo necessidade precisa de outra.

DATABASE_URL: "postgresql://user_name:user_password@db_host:5432/vaultwarden"

Crie uma base de dados vazia e o respetivo utilizador: no arranque, o Vaultwarden instala nela o seu próprio esquema. Uma palavra-passe com caracteres especiais escreve-se em codificação percentual neste endereço.

Faça esta escolha antes de encher o cofre. O wiki descreve uma passagem do SQLite para o PostgreSQL com o pgloader, esclarecendo que esse caminho não é suportado pelo projeto, que se faz por sua conta e risco e que começa por uma cópia de segurança.

Os e-mails: a configuração SMTP

O Vaultwarden arranca sem e-mail, mas várias funcionalidades dependem dele: os convites, a verificação dos endereços, o envio das dicas de palavra-passe, a autenticação de dois fatores por e-mail e a recuperação de conta.

Num VPS Simafri, o envio passa por uma retransmissão SMTP autenticada, na porta 587: o endereço de uma conta de correio que já tenha, ou o Simafri Suite. A palavra-passe coloca-se no ficheiro .env, como o token de administração:

SMTP_HOST: "smtp.example.com"
SMTP_FROM: "vault@example.com"
SMTP_PORT: "587"
SMTP_SECURITY: "starttls"
SMTP_USERNAME: "vault@example.com"
SMTP_PASSWORD: ${VAULTWARDEN_SMTP_PASSWORD}

• As ligações de convite constroem-se a partir de DOMAIN e continuam válidas durante 5 dias.
• Microsoft: o wiki indica que o Hotmail, o Outlook e o Office 365 exigem agora OAuth2, que o Vaultwarden ainda não suporta. O erro a reconhecer é No compatible authentication mechanism was found.
• Gmail: preveja uma palavra-passe de aplicação, segundo o wiki.
• O teste: a página de administração envia um e-mail de teste. Se mudar aí uma definição SMTP, guarde primeiro, porque o teste utiliza as definições guardadas, e essa gravação cria o config.json.

Se nada partir, o wiki propõe testar a ligação à retransmissão a partir do servidor. O comando devolve 0 quando a retransmissão responde:

timeout 5 bash -c 'cat < /dev/null > /dev/tcp/smtp.example.com/587'; echo $?

As cópias de segurança

O README lembra que o projeto não pode ser responsabilizado por uma perda de dados e recomenda vivamente cópias de segurança regulares. O wiki aconselha-as automáticas, com pelo menos uma cópia noutro lugar. Eis o que contém a pasta de dados com o SQLite:

A base de dados, com o serviço a funcionar

Desde a versão 1.32.1, o Vaultwarden sabe fazer ele próprio a cópia da sua base SQLite, sem parar o serviço:

docker exec -it vaultwarden /vaultwarden backup

O comando escreve um ficheiro db_AAAAMMDD_HHMMSS.sqlite3 ao lado da base de dados, em vw-data. A imagem não contém nem sqlite3 nem cron: o wiki aconselha agendar a tarefa no servidor, pelo menos uma vez por dia. Retire então o -it, porque uma tarefa agendada não tem terminal, e faça a triagem desses ficheiros, que se acumulam.

A pasta inteira, com o serviço parado

Quando a base de dados não está a ser utilizada, basta uma simples cópia de todos os seus ficheiros. É o método com o serviço parado que o wiki dá como exemplo para o Docker, e leva também os anexos:

docker compose down
tar -czf vaultwarden-$(date +%F).tar.gz vw-data
docker compose up -d

O wiki considera útil uma camada de cifragem, sobretudo quando a cópia inclui o token de administração e os acessos SMTP, e cita o rclone, o restic e o rustic para enviar as cópias para longe. Com o MariaDB ou o PostgreSQL, acrescente uma exportação da base de dados à pasta vw-data.

O wiki pede para não se contentar com os instantâneos de disco, mais delicados de restaurar. Guarde, por isso, estas cópias próprias da aplicação: colocadas no disco do servidor, entram também nas suas cópias de segurança noturnas.

Restaurar

1. Pare o Vaultwarden.
2. Substitua cada ficheiro ou pasta de vw-data pela respetiva versão copiada.
3. Se a base de dados vem de /vaultwarden backup, dê-lhe o nome db.sqlite3 e elimine primeiro qualquer ficheiro db.sqlite3-wal existente: um diário que não corresponda pode corromper a base de dados. Se vem de uma cópia direta, restaure em conjunto db.sqlite3 e o seu db.sqlite3-wal.
4. Reinicie e verifique depois que consegue abrir o cofre.

O wiki aconselha repetir este exercício de vez em quando, mantendo uma cópia dos dados no lugar: é assim que verifica que uma cópia de segurança funciona.

As atualizações

O wiki dá dois comandos, a partir da pasta do compose.yaml. A pasta de dados mantém-se no lugar:

docker compose pull
docker compose up -d

Estas atualizações contam mais do que noutros casos. As aplicações móveis e as extensões de navegador atualizam-se sozinhas, e o wiki avisa que uma diferença de versão em relação ao servidor pode provocar falhas repentinas. O cofre web, incluído na imagem, fica sempre alinhado com o seu servidor.

O projeto não tem calendário de versões: acompanhe as suas notas de versão e faça uma cópia de segurança logo antes de cada atualização. Algumas trazem correções de segurança, como a 1.37.5, de 1 de novembro de 2026, cujas notas recomendam atualizar o mais depressa possível. Estas notas avisam também que, desde a 1.37.5, um valor de configuração inválido impede o Vaultwarden de arrancar: reveja o seu ficheiro de ambiente antes de atualizar. A página de diagnóstico de /admin indica se existe uma versão mais recente.

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Vaultwarden continua a ser o seu software, com as suas definições e os seus dados.

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.