Tutoriais de VPS
ERPNext na VPS: Frappe Docker, HTTPS, filas e recuperação
Implante ERPNext com arquivos Frappe Docker compatíveis, overrides MariaDB/Redis, inicialização do site e aplicação, HTTPS e filas monitoradas. Proteja papéis e teste backups completos antes de migrar.

O ERPNext reúne contabilidade, compras, estoque, vendas, manufatura, recursos humanos e projetos sobre Frappe. Controlar dados e implantação exige manter banco, filas, permissões e recuperação. Usaremos Ubuntu 24.04, Docker Compose e os contêineres oficiais frappe_docker.
| Uso | CPU | RAM | Disco | Ponto de partida |
|---|---|---|---|---|
| Laboratório | 2 vCPU | 4 GB | 60 GB SSD | Limitar concorrência sem remover filas necessárias |
| Equipe pequena | 4 vCPU | 8 GB | 120 GB NVMe | Espaço separado para backup e SMTP testado |
| Várias empresas/manufatura | 8 vCPU+ | 16 GB+ | 200 GB NVMe+ | Considerar separar banco, arquivos e filas |
São orçamentos, sem garantia de desempenho. 2 GB costuma servir apenas para avaliação breve. Reserve aproximadamente 30% da RAM e 25% do disco, medindo free -h, df -h e docker stats. Veja dimensionamento.
Configure DNS funcional para erp.example.com. Abra SSH/HTTP/HTTPS necessários e mantenha MariaDB/Redis privados.
sudo apt update
sudo apt install -y ca-certificates curl git openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/erpnext
sudo chown -R "$USER":"$USER" /opt/erpnext
cd /opt/erpnext
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker
Revise o instalador root ou use pacotes suportados; o grupo Docker concede acesso poderoso. Não acompanhe indefinidamente mudanças não revisadas de main:
git fetch --tags
git tag --sort=-version:refname | head -n 10
git rev-parse HEAD
Registre commit testado e tag/digest. Voltar ao código antigo não reverte migração de banco.
O nome antigo .env.example aparece neste padrão:
cp .env.example .env
openssl rand -hex 32
nano .env
chmod 600 .env
Confira a revisão: o modelo oficial atual é example.env. compose.yaml precisa de overrides de banco/Redis/publicação ou serviços externos equivalentes. pwd.yml é uma demonstração descartável com credenciais de teste.
Os valores antigos mostram configurações comuns; SITE_NAME, ADMIN_PASSWORD e MYSQL_ROOT_PASSWORD não são variáveis universalmente consumidas pela base atual:
ERPNEXT_VERSION=v15
DB_PASSWORD=change-a-long-database-password
MYSQL_ROOT_PASSWORD=change-a-long-root-password
ADMIN_PASSWORD=change-a-long-admin-password
SITE_NAME=erp.example.com
HTTP_PUBLISH_PORT=8080
Para MariaDB/Redis/Caddy em uma máquina, copie example.env para .env, fixe ERPNEXT_VERSION exato e suportado, substitua DB_PASSWORD e acrescente:
COMPOSE_FILE=compose.yaml:overrides/compose.mariadb.yaml:overrides/compose.redis.yaml:overrides/compose.noproxy.yaml
HTTP_PUBLISH_PORT=127.0.0.1:8080
Use overrides da mesma revisão. MariaDB usa DB_PASSWORD como senha root: substitua o exemplo 123. Preserve sites, db-data e redis-queue-data, sem publicar banco/Redis.
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 backend
Mantenha configurator, backend, frontend, websocket e scheduler, com redis-cache e redis-queue. Modelos antigos podem listar queue-short, queue-default e queue-long; a base atual tem queue-short e queue-long atendendo também default, sem serviço queue-default separado. Use nomes reais e proteja a configuração expandida com segredos.
Este comando só funciona quando a configuração declara o perfil:
docker compose --profile create-site run --rm create-site
Caso contrário, use bench new-site no backend. Exemplo manual antigo:
docker compose exec backend bench new-site erp.example.com \
--mariadb-root-password "$MYSQL_ROOT_PASSWORD" \
--admin-password "$ADMIN_PASSWORD"
docker compose exec backend bench --site all list-apps
docker compose exec backend bench --site erp.example.com migrate
Forneça segredos reais de forma protegida: .env do Compose não carrega automaticamente variáveis no shell. Use o hostname final como nome do site ou configure FRAPPE_SITE_NAME_HEADER deliberadamente. Criar Frappe não instala ERPNext: acrescente --install-app erpnext ao comando suportado ou execute docker compose exec backend bench --site erp.example.com install-app erpnext. Confira list-apps antes de migrar.
Configure empresa, plano de contas, depósitos e papéis. Reserve Administrator para administração e use contas restritas no dia a dia.
Publique frontend em 127.0.0.1:8080 privado:
sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile
erp.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:8080
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
}
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://erp.example.com
Caddy gerencia certificados com DNS/80/443 acessíveis. reverse_proxy suporta WebSocket. Preserve Host, Upgrade e X-Forwarded-Proto, configurando proxies confiáveis no frontend. Use um gateway e HSTS/includeSubDomains somente com HTTPS funcional.
Configure SMTP, SPF, DKIM e DMARC. Confira PTR do IP SMTP real; normalmente o provedor de relay controla isso. Teste avisos internos antes de envios em massa.
- Separe papéis financeiros, comerciais, estoque e auditoria de leitura.
- Crie usuários/API keys por integração, com permissões e rotação.
- Ative MFA administrativo suportado e limite acesso ou use VPN.
- Monitore
queue-short,queue-default,queue-longe scheduler conforme serviços reais; não invente queue-default no modelo atual.
docker compose logs --tail=200 queue-short
docker compose logs --tail=200 queue-default
docker compose logs --tail=200 scheduler
docker compose exec backend bench --site erp.example.com show-pending-jobs
Adapte nomes antigos antes de consultar logs. Investigue Redis, memória dos workers, timeouts de APIs e falhas repetidas. Não apague Redis às cegas para esvaziar filas.
Preserve sites, anexos públicos/privados, configuração e chaves além do banco:
docker compose exec backend bench --site erp.example.com backup --with-files
docker compose exec backend find sites/erp.example.com/private/backups -maxdepth 1 -type f
Confira se os arquivos foram criados corretamente. Copie para o anfitrião backups, .env, Compose efetivo e commit; criptografe cópias externas e não publique .env:
mkdir -p /opt/erpnext/backups
docker cp "$(docker compose ps -q backend):/home/frappe/frappe-bench/sites/erp.example.com/private/backups" /opt/erpnext/backups/
cp .env /opt/erpnext/backups/
docker compose config > /opt/erpnext/backups/compose-$(date +%F).yaml
git rev-parse HEAD > /opt/erpnext/backups/frappe-docker-commit.txt
Inclua site_config.json/common_site_config.json e chaves de criptografia. Pause escritas para um ponto coerente de banco/arquivos. Pelo menos mensalmente, restaure em máquina temporária isolada e teste banco, anexos, login, filas e e-mail sem envios reais. Veja recuperação.
Registre tags, digests, docker compose config e backups. Substitua o marcador entre ângulos por uma revisão testada:
git fetch --tags
git checkout <tested-tag-or-commit>
docker compose pull
docker compose up -d
docker compose exec backend bench --site all migrate
docker compose logs --tail=200 backend
Respeite migrações e versões intermediárias exigidas. Teste login, listas, impressão, downloads, e-mails e filas. Se a migração falhar, pare mudanças; não conecte código antigo sem validar compatibilidade. Restaure o backup correspondente em isolamento antes de decidir a recuperação.
Comece por docker compose ps e logs frontend/backend/Caddy. Confira 8080 privada, DNS, firewall, configurator concluído e dependências saudáveis.
Confira websocket, Upgrade, HTTPS e erros do navegador. Misturar HTTP/HTTPS pode bloquear conexões.
Use docker stats --no-stream para localizar pressão no banco, backend ou workers. Ajuste concorrência, remova somente imagens/logs descartáveis e amplie capacidade ou separe banco quando necessário. Analise consultas lentas em vez de reiniciar tudo.
Confira credenciais SMTP, DNS, scheduler e filas. Verifique porta real e política de saída: 25 afeta SMTP direto; relays costumam usar 587/465.
- Domínio, HTTPS, WebSocket e renovação verificados.
- Banco, Redis, aplicação, filas e scheduler saudáveis ou concluídos conforme função.
- MFA administrativo e permissões comuns testados.
- SMTP, SPF, DKIM e DMARC verificados.
- Banco, anexos,
sites,.enve versões com backup externo. - Restauração isolada testada, com duração e lacunas registradas.
Executar docker compose up inicia o trabalho. Versões, filas, permissões e recuperação testada tornam o sistema sustentável.
Leituras relacionadas: