Hospedar Vaultwarden em um VPS gerenciado: suas senhas em seu servidor

O que o Vaultwarden faz

O Vaultwarden é um servidor de gerenciamento de senhas escrito em Rust, concebido para a auto-hospedagem. O wiki dele o destina a pessoas físicas, famílias e organizações de porte humano. O cofre web vem incluído nas imagens Docker.

Ele implementa uma API compatível com os clientes oficiais do Bitwarden, no navegador, no computador e no celular. O README esclarece que o projeto não é associado ao Bitwarden nem à Bitwarden, Inc., e pede que qualquer problema, seja qual for o cliente usado, seja relatado diretamente a ele, e não aos canais de suporte oficiais.

• O cofre: cofre pessoal, anexos, ícones dos sites, chave de API pessoal e o Send, para transmitir um texto ou um arquivo.
• As organizações: coleções, compartilhamento de senhas, funções, grupos, registros de eventos e políticas.
• A autenticação em duas etapas: aplicativo autenticador, e-mail, FIDO2 WebAuthn, YubiKey e Duo.
• Os recursos de socorro: 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 configurações, as contas e o diagnóstico.

O wiki também lista o que falta em relação ao servidor oficial, como o login por chave de acesso, as funções personalizadas e algumas políticas empresariais. Ele esclarece que os recursos voltados sobretudo a grandes organizações não são uma prioridade do projeto: leia essa lista se precisar deles.

O que a licença AGPL-3.0 permite

O Vaultwarden é publicado sob a GNU Affero General Public License, versão 3. O texto afirma uma permissão irrestrita de rodar o programa não modificado. Você pode, portanto, usar a imagem publicada pelo projeto para sua empresa e sua equipe, sem licença a comprar.

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

A instalação com Docker Compose

O README recomenda as imagens de contêiner. Em um servidor com o Docker instalado, crie uma pasta e coloque nela este compose.yaml, extraído 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ó é acessado pelo proxy reverso, instalado no mesmo servidor.
• DOMAIN: o endereço de base de sua instância, em https. O wiki avisa que recursos deixam de funcionar sem isso, entre eles os anexos e os links de convite.
• Uma pasta vw-data em um disco local: ela guarda todos os dados. O wiki aponta os problemas do SQLite em um volume CIFS ou Samba, que não gerencia o bloqueio de arquivos.
• A tag latest acompanha a última versão publicada, e o wiki a recomenda para a maioria dos usos. Uma tag como 1.37.5 fixa uma versão, e latest-alpine dá o mesmo em uma base Alpine.

Seu nome de domínio aponta para o servidor com registros A e AAAA, e os visitantes chegam pelas portas 80 e 443. Enquanto o proxy reverso não estiver no lugar, o cofre web fica inutilizável: passe direto à seção seguinte.

O projeto não informa números de memória nem de processador; ele se apresenta apenas como uma solução para os casos em que o serviço oficial, exigente em recursos, não serve. O tamanho depende do número de contas e do volume dos anexos. Em um VPS gerenciado, descreva-nos o uso e recomendamos o tamanho adequado.

HTTPS e WebSocket: o proxy reverso

O cofre web se apoia na API Web Crypto, que os navegadores reservam a contextos seguros: o README indica que ele só funciona com o HTTPS ativado, e o wiki considera o HTTPS “pretty much required”, praticamente obrigatório. O projeto recomenda um proxy reverso na frente do Vaultwarden e desaconselha o TLS integrado ao framework dele, o Rocket.

Use um certificado reconhecido, como os do Let's Encrypt, que o wiki recomenda: com um certificado autoassinado, algumas plataformas recusam a conexão. O certificado deve trazer a cadeia completa, sem o que os dispositivos Android não se conectam.

As notificações WebSocket, ativas por padrão, avisam o navegador, o aplicativo de desktop e a extensão de que uma entrada mudou. Elas passam pela porta HTTP principal, e o proxy precisa repassar os cabeçalhos Upgrade e Connection. Os aplicativos de celular usam as notificações nativas do sistema, que são configuradas à parte.

Com o Caddy

O wiki aconselha olhar primeiro o Caddy, se você não tem preferência: ele ativa o HTTPS sozinho, obtém o certificado Let's Encrypt e dá suporte ao WebSocket. A configuração do wiki também repassa ao Vaultwarden o endereço real do visitante, para os logs dele:

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 de 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;
    }
}

Em seguida, o Certbot instala o certificado e cuida de renová-lo:

sudo certbot --nginx

Verificar o WebSocket

Abra as ferramentas de desenvolvimento do navegador, aba de rede, filtro WS, e reconecte-se ao cofre: uma resposta 101 em /notifications/hub confirma a conexão. Outro teste do wiki: abra o cofre em dois navegadores, renomeie uma entrada em um deles, e a mudança aparece logo no outro.

Fechar os cadastros

Por padrão, qualquer pessoa que alcance sua instância pode criar uma conta nela. Isso é útil para sua primeira conta, e o wiki recomenda fechar em seguida, para impedir que um invasor crie uma.

1. Abra seu endereço HTTPS e crie sua conta; depois, conecte seus aplicativos a esse endereço.
2. Mude SIGNUPS_ALLOWED para "false" no compose.yaml.
3. Reinicie com docker compose up -d: uma variável de ambiente fica vinculada ao contêiner, que precisa ser recriado para levá-la em conta.

SIGNUPS_ALLOWED: "false"

• Os convites continuam abertos após o fechamento: os proprietários e os administradores de uma organização podem convidar novas pessoas. INVITATIONS_ALLOWED em "false" retira essa possibilidade, e o wiki deixa essa escolha conforme a confiança que você tem em seus usuários.
• Uma lista de domínios: SIGNUPS_DOMAINS_WHITELIST limita o cadastro a certos domínios de e-mail, e SIGNUPS_VERIFY em true passa a exigir a verificação do endereço. Quando essa lista está definida, SIGNUPS_ALLOWED é ignorada.
• A página de administração permite convidar qualquer pessoa, quaisquer que sejam essas restrições.

Assim que você salva a configuração pela página de administração, um arquivo config.json nasce na pasta de dados e prevalece sobre as variáveis de ambiente. As configurações em questão passam então a ser alteradas por essa página: modificar o compose.yaml deixa de bastar.

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

A página /admin serve para configurar o Vaultwarden, ver e excluir as contas e as organizações, remover a autenticação em duas etapas de um usuário, convidar e ler o diagnóstico. Sem ADMIN_TOKEN, ela fica desativada: se você não precisa dela, deixe-a assim.

O wiki recomenda fortemente ativar o HTTPS antes dessa página. O token funciona como senha e pode ser guardado em forma de hash, em argon2id, em vez de em texto puro na configuração. O Vaultwarden fornece o comando: ele pede a senha duas vezes e devolve uma cadeia PHC.

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

Coloque essa cadeia em um arquivo .env, ao lado do compose.yaml, entre aspas simples, e depois chame-a a partir do serviço:

VAULTWARDEN_ADMIN_TOKEN='$argon2id$...'

ADMIN_TOKEN: ${VAULTWARDEN_ADMIN_TOKEN}

Confira o resultado, reinicie e conecte-se em /admin com sua senha, e não com a cadeia PHC:

docker compose config
docker compose up -d

• A sessão dura 20 minutos por padrão, ajustáveis por ADMIN_SESSION_LIFETIME. Uma sessão aberta continua válida após uma troca de token. Para encerrar todas, exclua rsa_key.pem da pasta de dados e reinicie, o que também desconecta os usuários e cancela os convites em andamento.
• Um acesso reduzido: os exemplos de proxy do wiki mostram como abrir /admin apenas a certos endereços ou acrescentar a ele uma autenticação HTTP.
• DISABLE_ADMIN_TOKEN retira todo controle: ele é previsto para uma camada de autenticação separada colocada na frente, e o wiki o reserva a quem sabe o que está fazendo.

O que protege o cofre

A primeira proteção é a senha mestra. Os dados do cofre são criptografados com chaves pessoais ou de organização: quem obtém uma cópia do banco ou força uma sessão ainda precisa quebrar essa senha para lê-los. A solidez dela conta, portanto, antes de tudo. Uma sessão de administração, por si só, permite excluir uma conta ou remover uma autenticação em duas etapas, sem dar acesso aos dados do cofre.

Prepare-se para o esquecimento da senha mestra antes que ele aconteça: ative o acesso de emergência de sua conta e, em uma organização, a recuperação de conta, que exige o e-mail configurado.

Mais três configurações, extraídas do guia de reforço de segurança

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

SQLite, MariaDB ou PostgreSQL

A mesma imagem suporta os três bancos. O wiki descreve o SQLite como o mais usado e o mais testado, e o recomenda para a maioria dos usos, salvo necessidade precisa de outro.

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

Crie um banco vazio e o usuário dele: na inicialização, o próprio Vaultwarden instala nele o esquema. Uma senha com caracteres especiais é escrita em codificação por cento nesse endereço.

Faça essa 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 é feito por sua conta e risco e que começa por um backup.

Os e-mails: a configuração SMTP

O Vaultwarden inicia sem e-mail, mas vários recursos dependem dele: os convites, a verificação dos endereços, o envio das dicas de senha, a autenticação em duas etapas por e-mail e a recuperação de conta.

Em um VPS Simafri, o envio passa por um relay SMTP autenticado, na porta 587: o endereço de uma conta de e-mail que você já tem, ou o Simafri Suite. A senha vai no arquivo .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}

• Os links de convite são montados a partir de DOMAIN e continuam válidos por 5 dias.
• Microsoft: o wiki indica que Hotmail, Outlook e Office 365 passaram a exigir OAuth2, que o Vaultwarden ainda não suporta. O erro a reconhecer é No compatible authentication mechanism was found.
• Gmail: prepare uma senha de aplicativo, segundo o wiki.
• O teste: a página de administração envia um e-mail de teste. Se você mudar nela uma configuração SMTP, salve primeiro, pois o teste usa as configurações salvas, e esse salvamento cria o config.json.

Se nada sair, o wiki propõe testar a conexão com o relay a partir do servidor. O comando devolve 0 quando o relay responde:

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

Os backups

O README lembra que o projeto não pode ser responsabilizado por uma perda de dados e recomenda fortemente backups regulares. O wiki os aconselha automáticos, com pelo menos uma cópia em outro lugar. Veja o que a pasta de dados contém com o SQLite:

O banco, com o serviço em funcionamento

Desde a versão 1.32.1, o Vaultwarden sabe fazer backup do próprio banco SQLite, sem parar o serviço:

docker exec -it vaultwarden /vaultwarden backup

O comando grava um arquivo db_AAAAMMDD_HHMMSS.sqlite3 ao lado do banco, 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, pois uma tarefa agendada não tem terminal, e faça a triagem desses arquivos, que se acumulam.

A pasta inteira, com o serviço parado

Quando o banco não está em uso, basta uma simples cópia de todos os arquivos dele. É o método com o serviço parado que o wiki dá como exemplo para o Docker, e ele leva junto 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 criptografia, sobretudo quando o backup leva o token de administração e os acessos SMTP, e cita rclone, restic e rustic para enviar as cópias para longe. Com MariaDB ou PostgreSQL, acrescente uma exportação do banco à pasta vw-data.

O wiki pede para não confiar apenas em snapshots de disco, mais delicados de restaurar. Guarde, portanto, estas cópias próprias da aplicação: colocadas no disco do servidor, elas também entram nos backups noturnos dele.

Restaurar

1. Pare o Vaultwarden.
2. Substitua cada arquivo ou pasta de vw-data pela versão salva.
3. Se o banco vem de /vaultwarden backup, nomeie-o db.sqlite3 e exclua antes qualquer arquivo db.sqlite3-wal existente: um journal que não corresponde pode corromper o banco. Se ele vem de uma cópia direta, restaure juntos o db.sqlite3 e o db.sqlite3-wal dele.
4. Reinicie e verifique se consegue abrir o cofre.

O wiki aconselha repetir esse exercício de tempos em tempos, mantendo uma cópia dos dados no lugar: é assim que você verifica se um backup funciona.

As atualizações

O wiki dá dois comandos, a partir da pasta do compose.yaml. A pasta de dados continua no lugar:

docker compose pull
docker compose up -d

Essas atualizações contam mais do que em outros casos. Os aplicativos de celular e as extensões de navegador se atualizam sozinhos, e o wiki avisa que uma diferença de versão em relação ao servidor pode causar falhas repentinas. O cofre web, incluído na imagem, fica sempre alinhado ao servidor dele.

O projeto não tem calendário de versões: acompanhe as notas de versão e faça um backup 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 quanto antes. Essas notas também avisam que, desde a 1.37.5, um valor de configuração inválido impede o Vaultwarden de iniciar: revise seu arquivo 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ê em um VPS gerenciado

A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Vaultwarden continua sendo seu software, com as configurações e os dados dele.

Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.