Tutoriais de VPS
Appwrite na VPS: Docker, HTTPS, permissões e recuperação
Implante Appwrite com Ubuntu, Docker Compose e Caddy, separando instaladores por versão. Planeje recursos, proteja projetos e funções, evite loops do proxy, configure SMTP e copie banco, arquivos persistentes e chaves antes de atualizar.

O Appwrite reúne autenticação, bancos, arquivos, funções, mensagens e APIs em um backend próprio. Pode atender uma aplicação pessoal ou produto interno, desde que você cuide de acesso, e-mail, armazenamento persistente e atualizações. Uma VPS alugada ainda envolve confiança no provedor e nos administradores.
Os exemplos usam Ubuntu 24.04, Docker Compose e Caddy. Não misture versões: os trechos antigos da série 1.7 abaixo não são uma receita atual. A instalação oficial e a versão mais recente consultadas em 16 de novembro de 2026 indicam 2.7.2 com assistente. Use a configuração completa e o caminho de migração da versão escolhida.
O mínimo documentado atual é 2 núcleos, 4 GB de RAM, 2 GB de swap e Compose v2. Uma máquina de 1 núcleo/2 GB não atende. O orçamento de 2 núcleos/4 GB/40 GB SSD é uma referência inicial, sem garantia para produção.
| Recurso | Referência de laboratório | Referência de produção pequena |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU ou mais |
| RAM | 4 GB | Cerca de 8 GB, com medição |
| Disco | Cerca de 30 GB SSD, conforme imagens e dados | Cerca de 80 GB SSD ou mais |
| Sistema | Ubuntu 22.04/24.04 com Docker suportado | Ubuntu 24.04 LTS |
| Domínio | appwrite.example.com | Domínios próprios de aplicação e e-mail |
Confira free -h, df -h e docker stats se bancos, monitoramento ou IA compartilham a VPS. Reserve espaço para imagens, uploads e runtimes de funções. Veja dimensionamento da VPS.
sudo apt update
sudo apt install -y ca-certificates curl git
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/appwrite
sudo chown -R "$USER":"$USER" /opt/appwrite
cd /opt/appwrite
O script executa código como root; revise a origem ou use a instalação por pacotes suportada pelo Docker. Participar do grupo Docker também concede acesso poderoso ao anfitrião. Não coloque projeto e dados em diretórios temporários.
sudo systemctl enable --now docker
docker version
docker compose version
O exemplo histórico a seguir não garante uma instalação atual. Não execute 1.7.x literalmente como uma tag verificada: um clone superficial pode não conter a referência, e a árvore de código não equivale sempre ao modelo de produção.
cd /opt/appwrite
git clone --depth=1 https://github.com/appwrite/appwrite.git source
cd source
git checkout 1.7.x
cp .env.example .env
Para uma instalação nova de 2.7.2, o instalador oficial oferece um assistente. Mantenha a porta temporária privada na VPS:
cd /opt/appwrite
docker run -it --rm \
--publish 127.0.0.1:20080:20080 \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume "$PWD/appwrite:/usr/src/code/appwrite:rw" \
--entrypoint install appwrite/appwrite:2.7.2
No computador de administração, encaminhe 20080 por SSH e abra http://localhost:20080. O instalador usa o socket Docker e pode criar contêineres; escolha uma publicação confiável. Configure hostname final, HTTPS atrás do proxy e backend. O assistente atual usa PostgreSQL por padrão e oferece MariaDB/MongoDB. Os exemplos antigos tratam de MariaDB, sem orientar troca de backend existente.
Revise o .env gerado. Este exemplo mostra segredos e nomes antigos; use as variáveis realmente suportadas pela versão:
_APP_ENV=production
_APP_OPENSSL_KEY_V1=replace-with-a-long-random-secret
_APP_DOMAIN=appwrite.example.com
_APP_DOMAIN_TARGET=appwrite.example.com
_APP_DB_HOST=mariadb
_APP_DB_USER=appwrite
_APP_DB_PASS=replace-with-a-database-password
_APP_DB_SCHEMA=appwrite
_APP_REDIS_HOST=redis
[email protected]
_APP_SYSTEM_EMAIL_NAME=Appwrite
openssl rand -hex 32 gera material aleatório, mas cada opção pode exigir formato específico. Preserve a chave de criptografia, use credenciais únicas e não publique segredos no Git. Não exponha banco, Redis, workers nem APIs internas.
Execute Compose no diretório gerado, não necessariamente no antigo source:
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 appwrite
- Verifique
mariadbquando a instalação usar MariaDB. - Confira se o Appwrite alcança
redisna topologia que utiliza Redis. - Examine
appwritee workers por reinícios recorrentes. - Confira RAM e disco após downloads e inicialização.
Reinícios contínuos não devem ser ignorados como atividade normal. Leia erros e teste uma chamada. O túnel antigo abaixo aponta para a porta 80 remota; adapte o destino ao gateway privado real:
ssh -L 8080:127.0.0.1:80 root@SERVER_IP
Para o gateway 8080 descrito adiante, use ssh -L 8080:127.0.0.1:8080 user@SERVER_IP. Mantenha o console privado até validar HTTPS e controle de acesso.
Configure A/AAAA válidos. Corrija ou remova AAAA se IPv6 não estiver funcionando antes de solicitar certificados.
sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile
Caddy e o gateway Appwrite não podem ocupar simultaneamente a porta 80 do anfitrião. Publique HTTP do gateway como 127.0.0.1:8080:80, mantendo 8080 privada e reservando 80/443 públicos ao Caddy. O exemplo antigo usa upstream 80: troque por 127.0.0.1:8080 antes de aplicá-lo, pois ele pode apontar para o próprio Caddy.
appwrite.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:80
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
}
}
A linha corrigida é reverse_proxy 127.0.0.1:8080. Preserve host/WebSocket e ajuste domínio/HTTPS do Appwrite. Use HSTS, especialmente includeSubDomains, quando os domínios afetados suportarem HTTPS.
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo journalctl -u caddy -n 80 --no-pager
Se já há um gateway, integre nele o serviço vinculado a 127.0.0.1. Veja Caddy e proxy, evitando outro processo nas mesmas portas.
Quando https://appwrite.example.com funcionar com HTTPS verificado:
- Crie administrador, projeto e plataformas Web/Android/iOS/SDK de servidor apropriadas.
- Defina hosts e callbacks explícitos; evite
*amplo onde a opção permitir. - Limite os escopos das chaves e separe desenvolvimento e produção.
- Use autenticação forte, MFA suportado e papéis de equipe definidos.
- Dê credenciais restritas às Functions, sem chaves mestras permanentes.
- Configure SMTP e domínio de envio com SPF, DKIM e DMARC.
- Abra somente administração necessária e HTTP/HTTPS públicos no firewall do provedor; preserve serviços internos privados.
Use rede privada ou túnel para manutenção de 3306/6379. Veja exposição de bancos. Teste permissões com um cliente comum, não apenas com uma chave administrativa que evita verificações normais.
A recuperação exige banco consistente, dados persistentes de uploads/functions e a chave de .env. O exemplo antigo MariaDB/caminhos abaixo não copia automaticamente todos os volumes Docker:
cd /opt/appwrite/source
mkdir -p /opt/appwrite/backup
docker compose exec -T mariadb mysqldump -uappwrite -p"$APPWRITE_DB_PASS" appwrite | gzip > /opt/appwrite/backup/appwrite-$(date +%F).sql.gz
tar -czf /opt/appwrite/backup/appwrite-data-$(date +%F).tgz .env docker-compose.yml volumes/
Identifique backend e montagens reais. APPWRITE_DB_PASS não é carregado automaticamente de variáveis Appwrite com outro nome. Use o cliente de exportação suportado e credenciais protegidas, confira o resultado com pipefail e interrompa escritas durante cópias físicas. Um diretório volumes/ inexistente não contém volumes gerenciados pelo Docker.
Salve cada volume persistente necessário, configuração gerada, chave e versões. Criptografe cópias externas e proteja o acesso. Restaure em uma máquina limpa com a mesma versão; confira login, downloads, consultas e execução de funções. Siga os princípios de restauração. Uma imagem da VPS sem backup consistente e testado não basta.
Os comandos antigos ilustram guardar configuração e recriar contêineres; 1.7.x não é um destino de atualização verificado:
docker compose config > /opt/appwrite/backup/compose-$(date +%F).yaml
git fetch --tags
git checkout 1.7.x
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200
Não siga latest automaticamente. Fixe uma versão suportada, teste migrações e etapas intermediárias exigidas e agende manutenção. Um banco migrado pode não funcionar com a imagem anterior: reverter pode exigir restaurar dados e chaves correspondentes. O arquivo Compose expandido pode conter segredos.
sudo journalctl -u caddy -n 100 --no-pager
docker compose ps
docker compose logs --tail=200 appwrite
ss -lntp | grep -E ':80|:443'
Confira também a porta privada 8080. O Caddy deve alcançar o gateway, sem apontar para si mesmo; o gateway precisa alcançar API e workers saudáveis.
Confira host da API, certificado, WebSocket e callbacks no navegador, depois banco/Redis/workers. Para arquivos grandes, examine limites reais da aplicação, proxy e CDN. O Caddy não impõe um tamanho fixo universal de corpo: confira sua configuração.
docker compose ps
docker stats --no-stream
docker inspect appwrite --format '{{.State.OOMKilled}} {{.State.ExitCode}}'
sudo dmesg -T | grep -i -E 'oom|killed process'
Adapte o nome do contêiner. Examine OOM, filas e montagens antes de limpar; remova somente imagens/logs descartáveis confirmados, preserve volumes, confira swap e amplie recursos quando necessário. Reduzir memória dos workers às cegas pode piorar as filas.
- Domínio, HTTPS, API e WebSocket funcionam na versão escolhida.
- Administrador, plataformas, callbacks e permissões dos clientes foram verificados.
- Banco, Redis e workers não estão públicos.
.env, chaves, banco, uploads e dados de funções têm backup.- Uma instância separada passou por restauração.
- Versões, migrações e reversão com dados estão documentadas.
Comece com um projeto de teste. Um backend sustentável exige que implantação, permissões e recuperação funcionem juntos antes de receber usuários reais.