Como hospedar o ERPNext em uma VPS com Docker
Veja como dimensionar a VPS, operar os 11 containers do ERPNext, configurar TLS e email, fixar versões e testar uma restauração de backup.
O que está a assumir ao executar
Alojear o ERPNext numa VPS é uma tarefa de operação, não uma instalação com um único comando. A stack oficial do Docker Compose tem onze contentores e armazena o seu livro-razão geral e os registos dos clientes. Isto eleva o nível exigido para tudo o que se segue: uma cópia de segurança só é uma cópia de segurança depois de ser restaurada, e uma tag de imagem não fixada é uma migração de esquema à espera de acontecer.
Alguns nomes aparecem ao longo do texto. O ERPNext é a aplicação empresarial. O Frappe é o framework Python subjacente. O Bench é a ferramenta de linha de comandos que gere os sites e já está instalada dentro dos contentores. Um site é um tenant: uma base de dados MariaDB e um diretório de ficheiros carregados. Quase todos os comandos deste guia são executados bench dentro do contentor backend, num site identificado pelo nome.
Este guia usa o repositório frappe_docker, que é a implementação mantida pelo projeto. Todos os comandos abaixo foram verificados nesse repositório em agosto de 2026. Se ainda não conhece bem o Docker Compose, executar o Docker Compose numa VPS aborda os conceitos que este guia pressupõe.
De quanta capacidade precisa um VPS para o ERPNext?
Os dados por trás deste gráfico
[
{
"label": "Evaluation",
"vcpu": 2,
"ram_gb": 4,
"disk_gb": 40
},
{
"label": "Small production",
"vcpu": 4,
"ram_gb": 8,
"disk_gb": 100
},
{
"label": "Room to grow",
"vcpu": 4,
"ram_gb": 16,
"disk_gb": 160
}
]Para uma avaliação, comece com 2 vCPU e 4 GB de RAM. Esse é o nível de avaliação. Estes valores são pontos de partida, não medições deste guia, e o volume dos seus próprios documentos determina o número real. A última linha nem sequer é um mínimo publicado. Dá-lhe mais margem de memória, mas não garante que a memória nunca se esgote.
Seja realista quanto aos planos pequenos. Um VPS com 1 GB ou 2 GB deixa pouca margem para dez contentores de longa execução, o buffer pool do MariaDB e um worker Python a gerar um relatório. Sob pressão de memória, o kernel out of memory killer pode parar um contentor e, em docker inspect, verá então "OOMKilled": true com o código de saída 137. Um worker terminado a meio do trabalho deixa um documento submetido com o processamento em segundo plano incompleto.
Para uma empresa que usa o ERPNext diariamente, comece a planear com 8 GB de RAM, 4 vCPU e 100 GB de SSD. Depois, teste a sua carga de trabalho. A RAM esgota-se primeiro. O disco cresce mais depressa do que muitas pessoas esperam, porque cada anexo e cada backup local é guardado no mesmo volume que a base de dados.
Os onze contentores e a função de cada um
Execute docker compose ps depois de a stack estar ativa e de dez contentores estarem em execução. O contentor configurator executa o seu trabalho uma vez e termina. É daí que vem o total de onze.
backendexecuta a aplicação Frappe com gunicorn. É aqui quebenchreside.frontendé o nginx. Serve os recursos estáticos e encaminha tudo o resto para o backend.queue-shortequeue-longsão workers RQ (Redis Queue). Executam tarefas em segundo plano, como o envio de email, as importações e a criação de relatórios.schedulerexecuta as tarefas baseadas em tempo, incluindo os relatórios agendados e os documentos de repetição automática.websocketé o processo socket.io responsável pelas atualizações em tempo real no browser.dbé o MariaDB.redis-cacheeredis-queuesão duas instâncias Redis separadas: uma para a cache e outra para a fila de tarefas.proxyé o Traefik, adicionado pelo override de HTTPS. Gere as portas 80 e 443 e obtém os certificados.
Vale a pena compreender esta divisão, porque ela indica qual log deve consultar. Um email bloqueado é um problema do worker da fila, por isso docker compose logs -f queue-short é o comando correto. Uma página que carrega, mas nunca atualiza o indicador de notificações, tem um problema de websocket. Consultar os logs de backend para qualquer um destes problemas faz perder tempo.
Instale com os ficheiros de compose de produção, não com os de demonstração
O repositório inclui pwd.yml, e o README é claro: "This setup is intended for short-lived evaluation only. You will not be able to install custom apps to this setup." Use-o para avaliar o ERPNext durante uma tarde. Não o utilize para operar uma empresa.
sudo apt update && sudo apt install -y git
curl -fsSL https://get.docker.com | bash
git clone https://github.com/frappe/frappe_docker
cd frappe_docker
mkdir -p ~/gitops
cp example.env ~/gitops/erpnext.envAbra ~/gitops/erpnext.env e altere quatro valores. ERPNEXT_VERSION fixa a tag da imagem. DB_PASSWORD é fornecido como 123 no ficheiro de exemplo. SITES_RULE é a regra de encaminhamento do Traefik, e LETSENCRYPT_EMAIL fornece o email da conta ACME. O Let's Encrypt terminou os emails de notificação de expiração em June 4, 2025, por isso monitorize a expiração dos certificados separadamente.
ERPNEXT_VERSION=v16.32.1
DB_PASSWORD=<a long random password>
SITES_RULE=Host(`erp.example.com`)
LETSENCRYPT_EMAIL=ops@example.comAgora gere um ficheiro de compose e inicie-o.
docker compose --project-name erpnext \
--env-file ~/gitops/erpnext.env \
-f compose.yaml \
-f overrides/compose.mariadb.yaml \
-f overrides/compose.redis.yaml \
-f overrides/compose.https.yaml \
config > ~/gitops/erpnext.yaml
docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d
export COMPOSE_FILE="$HOME/gitops/erpnext.yaml"config não inicia nada. Faz a junção do ficheiro base com as substituições e apresenta o resultado com todas as variáveis já substituídas. Depois, execute esse ficheiro gerado. O passo adicional é útil: a stack em execução fica num único ficheiro que pode consultar, por isso não pode ser alterada enquanto a utiliza se alguém editar o ficheiro env ou fizer pull do repositório. como vários ficheiros Docker Compose são combinados explica as regras de substituição em detalhe.
A exportação COMPOSE_FILE faz com que os comandos abaixo utilizem o ficheiro gerado. Repita-a em cada shell novo; no cron, passe -f ~/gitops/erpnext.yaml explicitamente.
Aguarde até db iniciar e configurator terminar, o que demora alguns segundos, e depois crie o site.
docker compose --project-name erpnext exec backend \
bench new-site --mariadb-user-host-login-scope=% \
--db-root-password '<your DB_PASSWORD>' \
--install-app erpnext \
--admin-password '<a strong admin password>' \
erp.example.comVerifique:
docker compose --project-name erpnext ps
docker compose --project-name erpnext exec backend bench --site erp.example.com list-appslist-apps deve apresentar frappe e erpnext com as respetivas versões. Um ps saudável apresenta dez serviços no estado running e nenhum no estado restarting.
Há dois problemas frequentes neste ponto. --mariadb-user-host-login-scope=% atribui ao utilizador da base de dados do novo site um âmbito de host wildcard, para que continue a conseguir iniciar sessão quando o Docker atribuir ao contentor da aplicação um endereço diferente. Sem esta opção, o Frappe limita o utilizador ao host que faz a ligação naquele momento. O contentor da aplicação acede ao MariaDB através da rede Docker, por isso chega como um host remoto, e um utilizador da base de dados limitado a localhost não consegue iniciar sessão a partir daí. Esta opção altera o utilizador da base de dados do site, não a conta root. O âmbito % permite ligações a partir de qualquer host que consiga alcançar o MariaDB, por isso mantenha a base de dados na rede Docker privada.
O segundo problema é o nome do site. Por predefinição, o frontend escolhe o site a servir a partir do cabeçalho HTTP Host, por isso um site criado como erpnext não fica acessível em erp.example.com, mesmo que ambos existam. Dê ao site o nome do domínio, como acima, ou defina FRAPPE_SITE_NAME_HEADER no ficheiro env com o nome do site e gere novamente o ficheiro de compose.
HTTPS e o que tem de estar configurado antes de funcionar
O override compose.https.yaml executa o Traefik na porta 443, redireciona a porta 80 para essa porta e solicita certificados ao Let's Encrypt. O TLS (transport layer security) impede que uma fatura e um cookie de sessão circulem pela rede em texto simples.
Duas condições têm de ser verdadeiras. Caso contrário, nenhum certificado será emitido. O registo DNS A de erp.example.com já tem de apontar para a VPS. As portas 80 e 443 têm de estar acessíveis a partir da Internet, porque o Let's Encrypt confirma que controla o nome através de um desafio HTTP-01 na porta 80. Verifique também a firewall de rede do seu fornecedor e a firewall do servidor. São controlos separados, e a firewall do painel é frequentemente esquecida.
Os certificados ficam no volume cert-data, em /letsencrypt/acme.json. Se o navegador mostrar um certificado predefinido em vez do seu, identifique o nome do serviço proxy em docker compose --project-name erpnext ps e consulte os respetivos logs para encontrar o erro do ACME (automatic certificate management environment). Está a executar outras aplicações web no mesmo servidor? uma instância do Traefik à frente de várias aplicações Docker Compose mostra como partilhar o proxy em vez de tentar usar a porta 443 em vários serviços. A segunda aplicação num servidor deste tipo é frequentemente destinada a clientes, e uma central de suporte Chatwoot alojada localmente fica atrás do mesmo proxy. Assim, as pessoas que tratam das faturas também respondem ao email e ao chat dos clientes num único local.
E-mail de saída, ou as faturas nunca saem do servidor
Este é o passo que a maioria dos guias do ERPNext ignora e é o que determina se o sistema é útil. Sem e-mail de saída a funcionar, nenhuma fatura chega ao cliente, nenhum pedido de redefinição de palavra-passe é recebido e nenhum relatório agendado é entregue. A stack não inclui um servidor de e-mail.
Não tente enviar e-mail diretamente do VPS pela porta 25. Provedores como a AWS bloqueiam a porta 25 de saída por predefinição, e um IP de envio novo, com pouco ou nenhum histórico, aumenta o risco de rejeição ou de as mensagens serem classificadas como spam. Nenhum destes resultados é inevitável. Use um relay autenticado na porta 587 e verifique primeiro as regras de saída do seu provedor: a DigitalOcean bloqueia as portas 25, 465 e 587 nos Droplets por predefinição.
O método suportado é o ecrã Email Account na interface do ERPNext, que armazena a palavra-passe de forma encriptada. Também pode escrever as chaves na configuração do site:
docker compose --project-name erpnext exec backend \
bench --site erp.example.com set-config mail_server smtp.example.com
docker compose --project-name erpnext exec backend \
bench --site erp.example.com set-config mail_port 587 --parse
docker compose --project-name erpnext exec backend \
bench --site erp.example.com set-config use_tls 1 --parse
docker compose --project-name erpnext exec backend \
bench --site erp.example.com set-config mail_login 'erp@example.com'
docker compose --project-name erpnext exec backend \
bench --site erp.example.com set-config auto_email_id 'erp@example.com'--parse armazena 587 como um número, e não como a string "587". Leia novamente o ficheiro e confirme que esses dois valores não têm aspas:
docker compose --project-name erpnext exec backend \
cat sites/erp.example.com/site_config.jsonPara armazenar a palavra-passe de forma encriptada, configure o servidor de saída, o login e a palavra-passe em conjunto no ecrã Email Account. O campo de palavra-passe desse ecrã não define a chave de configuração do site mail_password separada.
Envie depois uma mensagem real. Crie uma Sales Invoice, envie-a por e-mail para um endereço que controle e monitorize a fila enquanto isso:
docker compose --project-name erpnext logs -f queue-shortO e-mail de saída é um trabalho em segundo plano. Por isso, uma mensagem que nunca chega normalmente aparece como um trabalho com falha nesse log, e não como um erro no browser. Publique também registos SPF (sender policy framework) e DKIM (domainkeys identified mail) para o domínio de envio e adicione uma política DMARC. Sem autenticação, uma fatura tecnicamente correta corre o risco de ser rejeitada ou classificada como spam. Se preferir controlar todo o percurso, um servidor de e-mail Mailcow autoalojado fornece um relay sob o seu controlo, num servidor separado do ERP.
Backups que são realmente restaurados
Um dump da base de dados, por si só, não é um backup do ERPNext. Os anexos e os ficheiros privados ficam no diretório sites, não no MariaDB. Restaure apenas a base de dados e todas as ordens de compra carregadas voltarão como links quebrados.
docker compose --project-name erpnext exec backend \
bench --site erp.example.com backup --with-filesIsto grava quatro ficheiros em sites/erp.example.com/private/backups dentro do volume sites:
- um dump
-database.sql.gz - um arquivo
-files.tardos ficheiros públicos - um arquivo
-private-files.tardos ficheiros privados - uma cópia
-site_config_backup.jsonda configuração do site
O quarto ficheiro é aquele que muitas pessoas eliminam. É também o que causa mais problemas. Contém encryption_key, a chave que o Frappe usa para encriptar as palavras-passe armazenadas: credenciais de contas de email, chaves de gateways de pagamento e todos os segredos das integrações. Restaure uma base de dados sem a chave correspondente e o site carregará normalmente, mas o envio de email falhará com:
frappe.exceptions.ValidationError: Encryption key is invalid! Please check site_config.jsonMantenha sempre os quatro ficheiros juntos.
Depois, retire-os do servidor. Um backup dentro do volume não sobrevive à perda do servidor. Além disso, o bench remove-o periodicamente: por predefinição, elimina desse diretório os backups com mais de 23 horas. Essa predefinição era de 24 horas antes do Frappe 16.20.0 e 15.114.0. A chave keep_backups_for_hours na configuração do site substitui esse valor.
docker compose --project-name erpnext cp \
backend:/home/frappe/frappe-bench/sites/erp.example.com/private/backups \
~/erpnext-backupsExecute esse comando a partir do cron e, em seguida, envie o diretório para um local que não administre. backups encriptados do restic num armazenamento externo é a ferramenta adequada, porque encripta os dados antes do envio e restic check confirma que o repositório continua legível. Um backup de ERP é uma cópia de todo o seu livro contabilístico. Por isso, deve permanecer encriptado em repouso, num hardware que não seja este.
Teste a restauração antes de precisar dela
Um backup não testado é apenas uma suposição. Teste-o num segundo site no mesmo servidor, nunca no site em produção.
docker compose --project-name erpnext exec backend \
bench new-site --mariadb-user-host-login-scope=% \
--db-root-password '<your DB_PASSWORD>' \
--admin-password '<a strong admin password>' \
restore-test.example.com
docker compose --project-name erpnext exec backend \
bench --site restore-test.example.com --force restore \
sites/erp.example.com/private/backups/<stamp>-erp_example_com-database.sql.gz \
--with-public-files sites/erp.example.com/private/backups/<stamp>-erp_example_com-files.tar \
--with-private-files sites/erp.example.com/private/backups/<stamp>-erp_example_com-private-files.tar \
--db-root-password '<your DB_PASSWORD>'Copie a chave de encriptação da configuração protegida por backup para o site restaurado. Caso contrário, as integrações continuarão indisponíveis:
docker compose --project-name erpnext exec backend \
bench --site restore-test.example.com set-config encryption_key '<value from site_config_backup.json>'Agora verifique a restauração como faria um contabilista. Abra o relatório de contas a receber e compare o saldo final com o site em produção. Abra uma fatura de compra recente e transfira o respetivo anexo. Um site que apresenta a página de login não prova nada.
Remova o site de teste quando terminar:
docker compose --project-name erpnext exec backend \
bench drop-site restore-test.example.comPor que fixar versões é mais importante no ERPNext
Num site estático, uma tag de imagem sem versão fixa significa um reinício inesperado. No ERPNext, significa uma migração de esquema. bench migrate reescreve tabelas da base de dados e pode reescrever dados de documentos. Não existe desfazer. Reverter significa restaurar uma cópia de segurança, não fazer um docker compose down.
Por isso, fixe a tag. ERPNEXT_VERSION=v16.32.1 era a versão fixada no próprio pwd.yml do repositório em agosto de 2026. Em 2026-11-16, tanto pwd.yml como example.env fixavam v16.55.0. Não reutilize nenhum dos dois números sem o confirmar. As versões atuais estão listadas na página de versões do frappe/erpnext, e as tags de imagem existentes estão no Docker Hub. Leia as notas da versão para a qual vai atualizar antes de iniciar a atualização.
A atualização começa com uma cópia de segurança e o modo de manutenção.
docker compose --project-name erpnext exec backend \
bench --site erp.example.com backup --with-files
docker compose --project-name erpnext exec backend \
bench --site erp.example.com set-maintenance-mode onEdite ERPNEXT_VERSION em ~/gitops/erpnext.env. Em seguida, gere a configuração, faça pull da imagem e execute a migração.
docker compose --project-name erpnext \
--env-file ~/gitops/erpnext.env \
-f compose.yaml \
-f overrides/compose.mariadb.yaml \
-f overrides/compose.redis.yaml \
-f overrides/compose.https.yaml \
config > ~/gitops/erpnext.yaml
docker compose --project-name erpnext -f ~/gitops/erpnext.yaml pull
docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d
docker compose --project-name erpnext exec backend \
bench --site erp.example.com migrate
docker compose --project-name erpnext exec backend \
bench --site erp.example.com set-maintenance-mode offO modo de manutenção é importante porque migrate altera o esquema enquanto é executado. Se um utilizador enviar um documento para uma tabela parcialmente migrada, poderá ser necessário reparar os registos manualmente.
Atualize uma versão principal de cada vez, com uma cópia de segurança entre cada etapa. Consulte as instruções de migração de cada versão principal antes de prosseguir.
O repositório também inclui overrides/compose.migrator.yaml. Este adiciona um contentor que executa bench --site all migrate no arranque quando existem sites e MIGRATE_SITES está ativado, como acontece por predefinição. É conveniente. Também significa que um docker compose up com uma tag alterada migra a sua base de dados de produção sem supervisão. Num sistema empresarial, execute migrate como uma decisão tomada conscientemente nessa manhã.
Reforçar a segurança de um servidor que armazena registos de clientes
Altere a palavra-passe do Administrator no primeiro início de sessão. O ficheiro Compose de avaliação inclui admin como essa palavra-passe, e esse hábito acompanha as pessoas para produção.
Altere DB_PASSWORD para não usar o 123 em example.env. Esse valor fica no ~/gitops/erpnext.yaml renderizado em texto simples, por isso chmod 600 o ficheiro e mantenha-o fora de qualquer repositório git. Para obter mais segurança, overrides/compose.mariadb-secrets.yaml lê a palavra-passe de um ficheiro de secret do Docker, em vez de uma variável de ambiente. gerir ficheiros de ambiente e secrets no Docker Compose explica os compromissos.
Publique apenas o que for necessário. Com o override HTTPS, apenas as portas 80 e 443 ficam expostas. Não adicione um mapeamento ports ao serviço db para facilitar a ligação de um cliente de base de dados: isso coloca o MariaDB na Internet pública. Use docker compose --project-name erpnext exec backend bench mariadb. No host, permita 22, 80 e 443, bloqueie as restantes e verifique também a firewall de rede separada do fornecedor.
Ative a autenticação de dois fatores nas System Settings para todas as contas que tenham a função System Manager. Essa função pode alterar as System Settings, por isso trate-a como uma conta de administrador, e não como uma mera conveniência. Se executar várias aplicações self-hosted, Authentik como fornecedor self-hosted de single sign-on é melhor do que usar mais uma palavra-passe por aplicação.
Aplique patches no host e reinicie-o para instalar atualizações do kernel. Antes de confiar que a stack voltará a arrancar, verifique no ficheiro renderizado se existe uma política restart em cada serviço, porque uma stack sem essa política permanece parada depois do reboot. fazer uma stack Docker Compose arrancar novamente depois de um reboot explica a configuração no systemd.
Quando o ERPNext deixa de ser confortável numa única VPS
Uma VPS pode suportar uma pequena empresa durante bastante tempo. Estes são sinais de que isso já não acontece:
- Os trabalhos em segundo plano acumulam-se, e os emails e as importações chegam com minutos ou horas de atraso.
docker inspectapresenta contentores com"OOMKilled": trueou código de saída 137.- Os relatórios que demoravam dois segundos passam a demorar trinta, e o processo que mantém a CPU ocupada é o MariaDB.
- As cópias de segurança demoram tanto que uma execução se sobrepõe à seguinte execução agendada.
Comece por atribuir ao MariaDB recursos que não sejam partilhados, porque a base de dados e os workers Python competem pela mesma memória, e o buffer pool é o componente que precisa de mais memória. Um servidor de aplicações maior ajuda menos do que se espera. executar a base de dados no Docker ou no host aborda essa decisão, e definir limites de memória no Docker Compose impede que um contentor deixe os outros sem recursos enquanto faz essa alteração.
Depois, adicione workers de fila em vez de aumentar a capacidade web. O trabalho mais lento do ERPNext é executado em segundo plano: geração de relatórios e importações em massa. Mais workers precisam de margem de CPU e memória; adicionar contentores a uma VPS já saturada não aumenta a capacidade.
FAQ
Quanta RAM o ERPNext precisa numa VPS?
Para avaliação, comece com 4 GB e 2 vCPU. Para uma empresa que o utiliza diariamente, planeie 8 GB e 4 vCPU com 100 GB de SSD. Sob pressão de memória, o kernel pode parar contentores através do out of memory killer, o que docker inspect comunica como "OOMKilled": true com o código de saída 137. Estes valores são pontos de partida, não medições. Monitorize o consumo de memória do seu sistema durante o primeiro mês.
Posso executar pwd.yml em produção?
Não. O README do projeto indica que o ficheiro se destina apenas a avaliações de curta duração e salienta que não é possível instalar aplicações personalizadas nele. Use compose.yaml com as substituições para MariaDB, Redis e HTTPS, gere um único ficheiro com docker compose config e execute esse ficheiro.
Porque é que o meu site ERPNext fica inacessível logo depois de o criar?
Por predefinição, o frontend escolhe o site a servir com base no cabeçalho HTTP Host. Por isso, o nome do site tem de corresponder ao domínio introduzido no browser. Um site criado como erpnext não é servido em erp.example.com. Crie o site com o domínio como nome ou defina FRAPPE_SITE_NAME_HEADER no ficheiro env com o nome do site, gere novamente o ficheiro compose e reinicie a stack.
O que tem de estar incluído numa cópia de segurança do ERPNext?
São necessários quatro ficheiros, mantidos em conjunto: o dump -database.sql.gz, os arquivos -files.tar e -private-files.tar e a cópia de configuração -site_config_backup.json. A execução de bench --site erp.example.com backup --with-files produz os quatro ficheiros. A cópia de configuração contém encryption_key. Sem ela, uma restauração deixa as palavras-passe de integrações armazenadas impossíveis de desencriptar, o que aparece como Encryption key is invalid! Please check site_config.json.
Como atualizo o ERPNext sem danificar os meus dados?
Faça uma cópia de segurança com --with-files, ative o modo de manutenção, altere ERPNEXT_VERSION no ficheiro env, gere novamente o ficheiro compose, faça pull, inicie a stack, execute bench --site erp.example.com migrate e desative o modo de manutenção. Avance uma versão principal de cada vez e leia primeiro as notas de versão, porque migrate reescreve o esquema e os dados dos documentos sem possibilidade de desfazer a alteração. Reverter significa restaurar a cópia de segurança criada no início.