Cómo instalar ERPNext en un VPS con Docker
Despliega ERPNext en un VPS con Docker: los 11 contenedores, TLS, correo saliente, versiones fijadas y una restauración de copias de seguridad probada.
Qué implica ponerlo en producción
Alojar ERPNext en un VPS es una tarea de operaciones, no una instalación de un solo comando. La pila oficial de Docker Compose consta de once contenedores y contiene el libro mayor y los registros de clientes. Esto eleva el nivel de exigencia para todo lo que sigue: una copia de seguridad no es una copia de seguridad hasta que se ha restaurado, y una etiqueta de imagen sin fijar es una migración de esquema a punto de producirse.
A lo largo del texto aparecen varios nombres. ERPNext es la aplicación empresarial. Frappe es el framework de Python en el que se basa. Bench es la herramienta de línea de comandos que administra los sitios y ya está instalada dentro de los contenedores. Un site es un inquilino: una base de datos de MariaDB y un directorio de archivos subidos. Casi todos los comandos de esta guía se ejecutan bench dentro del contenedor backend contra un sitio con nombre.
Esta guía usa el repositorio frappe_docker, que es el despliegue que mantiene el proyecto. Todos los comandos siguientes se comprobaron con ese repositorio en agosto de 2026. Si Docker Compose es nuevo para usted, ejecutar Docker Compose en un VPS cubre los conceptos que da por supuestos esta guía.
¿Cuántos recursos de VPS necesita ERPNext?
Los datos de este 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 la evaluación, empiece con 2 vCPU y 4 GB de RAM. Ese es el nivel de evaluación. Son puntos de partida, no mediciones obtenidas de esta guía, y el volumen real de sus documentos determina la cifra adecuada. La última fila no es un mínimo publicado. Proporciona más margen de memoria, pero no garantiza que la memoria nunca se agote.
Sea realista con los planes pequeños. Un VPS de 1 GB o 2 GB deja poco margen para diez contenedores de ejecución prolongada, el buffer pool de MariaDB y un worker de Python que genere un informe. Bajo presión de memoria, el kernel puede detener un contenedor mediante el out of memory killer, y docker inspect muestra entonces "OOMKilled": true con el código de salida 137. Si se detiene un worker a mitad de un trabajo, un documento enviado puede quedar con el trabajo en segundo plano incompleto.
Para una empresa que usa ERPNext a diario, empiece a planificar con 8 GB de RAM, 4 vCPU y 100 GB de SSD. Después, pruebe su carga de trabajo. La RAM se agota primero. El disco crece más rápido de lo esperado porque cada archivo adjunto y cada copia de seguridad local se almacenan en el mismo volumen que la base de datos.
Los once contenedores y la función de cada uno
Ejecute docker compose ps una vez que la pila esté activa y diez contenedores estén en ejecución. Uno más, configurator, realiza su tarea una sola vez y finaliza; de ahí proviene el total de once.
backendejecuta la aplicación Frappe bajo gunicorn. Aquí es donde residebench.frontendes nginx. Sirve los recursos estáticos y transfiere todo lo demás al backend.queue-shortyqueue-longson trabajadores de RQ (Redis Queue). Ejecutan tareas en segundo plano como el envío de correos, importaciones y generación de informes.schedulerdispara las tareas basadas en tiempo, incluyendo informes programados y documentos de repetición automática.websocketes el proceso socket.io que gestiona las actualizaciones en tiempo real en el navegador.dbes MariaDB.redis-cacheyredis-queueson dos instancias separadas de Redis, una para caché y otra para la cola de tareas.proxyes Traefik, añadido mediante la anulación de HTTPS. Gestiona los puertos 80 y 443 y obtiene los certificados.
Conocer esta división es útil, ya que indica qué registro debe consultar. Un correo electrónico bloqueado es un problema del trabajador de la cola, por lo que docker compose logs -f queue-short es el comando correcto. Una página que carga pero nunca actualiza su indicador de notificaciones es un problema de websocket. Leer los registros de backend para cualquiera de estos casos es una pérdida de tiempo.
Instale con los archivos de Compose de producción, no con los de demostración
El repositorio incluye pwd.yml y el README lo indica claramente: "Esta configuración sólo está pensada para evaluaciones de corta duración. No podrá instalar aplicaciones personalizadas en esta configuración". Úselo para probar ERPNext durante una tarde. No lo use para ejecutar el sistema de una 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 y cambie cuatro valores. ERPNEXT_VERSION fija la etiqueta de la imagen. DB_PASSWORD se entrega como 123 en el archivo de ejemplo. SITES_RULE es la regla de enrutamiento de Traefik y LETSENCRYPT_EMAIL proporciona el correo electrónico de la cuenta de ACME. Let's Encrypt dejó de enviar correos de notificación de expiración el 4 de junio de 2025, así que supervise la expiración de los certificados por separado.
ERPNEXT_VERSION=v16.32.1
DB_PASSWORD=<a long random password>
SITES_RULE=Host(`erp.example.com`)
LETSENCRYPT_EMAIL=ops@example.comAhora genere un archivo de Compose y, después, inícielo.
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 no inicia nada. Combina el archivo base con las anulaciones e imprime el resultado con todas las variables ya sustituidas. Después, ejecute el archivo generado. Este paso adicional resulta útil: la pila en ejecución queda definida en un único archivo que puede leer, por lo que no puede cambiar mientras trabaja si alguien edita el archivo env o actualiza el repositorio. cómo se combinan varios archivos de Docker Compose explica detalladamente las reglas de anulación.
La exportación COMPOSE_FILE hace que los comandos siguientes usen el archivo generado. Repítala en cada shell nuevo; en cron, pase -f ~/gitops/erpnext.yaml explícitamente.
Espere a que db se inicie y a que configurator termine, lo que tarda unos segundos, y después cree el sitio.
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.comCompruébelo:
docker compose --project-name erpnext ps
docker compose --project-name erpnext exec backend bench --site erp.example.com list-appslist-apps debería mostrar frappe y erpnext con sus versiones. Un ps correcto muestra diez servicios en estado running y ninguno en restarting.
Aquí suelen producirse dos problemas. --mariadb-user-host-login-scope=% asigna al usuario de base de datos del sitio nuevo un alcance de host comodín, de modo que puede seguir iniciando sesión cuando Docker asigna al contenedor de la aplicación una dirección diferente. Sin esta opción, Frappe limita el usuario al host que realiza la conexión en ese momento. El contenedor de la aplicación llega a MariaDB a través de la red de Docker, por lo que se conecta como un host remoto, y un usuario de base de datos limitado a localhost no puede iniciar sesión desde allí. Esta opción cambia el usuario de base de datos del sitio, no la cuenta root. El alcance % permite conexiones desde cualquier host que pueda alcanzar MariaDB, así que mantenga la base de datos en la red privada de Docker.
El segundo problema es el nombre del sitio. De forma predeterminada, el frontend elige qué sitio servir a partir de la cabecera HTTP Host, por lo que un sitio creado como erpnext no es accesible en erp.example.com aunque ambos existan. Asigne al sitio el nombre del dominio, como se ha indicado antes, o establezca FRAPPE_SITE_NAME_HEADER en el archivo env con el nombre del sitio y vuelva a generar el archivo de Compose.
HTTPS y requisitos previos
El override compose.https.yaml ejecuta Traefik en el puerto 443, redirige el puerto 80 hacia él y solicita certificados a Let's Encrypt. TLS (seguridad de la capa de transporte) evita que una factura y una cookie de sesión circulen por la red en texto plano.
Deben cumplirse dos condiciones; de lo contrario, nunca se emitirá ningún certificado. El registro DNS A de erp.example.com ya debe apuntar al VPS. Los puertos 80 y 443 deben ser accesibles desde Internet, porque Let's Encrypt demuestra que usted controla el nombre mediante un desafío HTTP-01 en el puerto 80. Compruebe también el firewall de red del proveedor y el firewall del servidor. Son controles independientes, y el firewall del panel es el que se suele olvidar.
Los certificados se guardan en el volumen cert-data, en /letsencrypt/acme.json. Si el navegador muestra un certificado predeterminado en lugar del suyo, busque el nombre del servicio proxy en docker compose --project-name erpnext ps y revise sus registros para encontrar el error de ACME (entorno de gestión automática de certificados). ¿Ejecuta otras aplicaciones web en el mismo servidor? una instancia de Traefik delante de varias aplicaciones de Docker Compose explica cómo compartir el proxy en lugar de competir por el puerto 443. La segunda aplicación de un servidor como este suele estar orientada a clientes, y una mesa de soporte Chatwoot autohospedada se ejecuta detrás del mismo proxy. Así, las personas que gestionan las facturas también pueden responder al correo y al chat de los clientes desde un único lugar.
Correo saliente, o las facturas nunca salen del servidor
Este es el paso que la mayoría de las guías de ERPNext omiten y el que determina si el sistema resulta útil. Sin correo saliente operativo, ninguna factura llega al cliente, ningún restablecimiento de contraseña se entrega y ningún informe programado se envía. La pila no incluye un servidor de correo.
No intente enviar correo directamente desde el VPS por el puerto 25. Proveedores como AWS bloquean el puerto saliente 25 de forma predeterminada, y una IP de envío nueva, con poco o ningún historial, aumenta el riesgo de rechazo o de que los mensajes terminen en spam. Ninguno de estos resultados es inevitable. Use un relay autenticado en el puerto 587 y compruebe primero las reglas de salida de su proveedor: DigitalOcean bloquea los puertos 25, 465 y 587 en los Droplets de forma predeterminada.
La ruta compatible es la pantalla Email Account de la interfaz de ERPNext, que almacena la contraseña cifrada. También puede escribir las claves en la configuración del sitio:
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 almacena 587 como un número en lugar de la cadena "587". Vuelva a leer el archivo y confirme que esos dos valores no tienen comillas:
docker compose --project-name erpnext exec backend \
cat sites/erp.example.com/site_config.jsonPara almacenar la contraseña cifrada, configure juntos el servidor saliente, el nombre de usuario y la contraseña en la pantalla Email Account. El campo de contraseña de esa pantalla no establece la clave de configuración del sitio independiente mail_password.
A continuación, envíe un mensaje real. Cree una Sales Invoice, envíela por correo a una dirección que controle y supervise la cola mientras lo hace:
docker compose --project-name erpnext logs -f queue-shortEl correo saliente es un trabajo en segundo plano, por lo que un mensaje que nunca llega suele aparecer como un trabajo fallido en ese registro, no como un error en el navegador. Publique también registros SPF (sender policy framework) y DKIM (domainkeys identified mail) para el dominio de envío y añada después una política DMARC. Sin autenticación, una factura técnicamente correcta corre el riesgo de ser rechazada o de terminar en spam. Si prefiere controlar toda la ruta, un servidor de correo Mailcow autohospedado le proporciona un relay bajo su control, en un servidor separado del ERP.
Copias de seguridad que realmente se restauran
Un volcado de base de datos por sí solo no constituye una copia de seguridad de ERPNext. Los archivos adjuntos y los archivos privados residen en el directorio sites, no en MariaDB. Si solo restaura la base de datos, cada orden de compra subida aparecerá como un enlace roto.
docker compose --project-name erpnext exec backend \
bench --site erp.example.com backup --with-filesEsto escribe cuatro archivos en sites/erp.example.com/private/backups dentro del volumen sites:
- un volcado
-database.sql.gz - un archivo
-files.tarde archivos públicos - un archivo
-private-files.tarde archivos privados - una copia
-site_config_backup.jsonde la configuración del sitio
El cuarto archivo es el que la gente suele descartar, y es el que causa problemas. Contiene encryption_key, la clave que Frappe utiliza para cifrar las contraseñas almacenadas: credenciales de cuentas de correo, claves de pasarelas de pago y todos los secretos de integración. Si restaura una base de datos sin la clave correspondiente, el sitio cargará normalmente, pero el envío de correos fallará con el siguiente error:
frappe.exceptions.ValidationError: Encryption key is invalid! Please check site_config.jsonMantenga siempre los cuatro archivos juntos.
Luego, sáquelos del servidor. Una copia de seguridad dentro del volumen no sobrevive si el servidor falla, y además bench la elimina: por defecto, borra las copias de seguridad con más de 23 horas de antigüedad de ese directorio. Ese valor predeterminado era de 24 horas antes de Frappe 16.20.0 y 15.114.0, y la clave keep_backups_for_hours en la configuración del sitio permite sobrescribirlo.
docker compose --project-name erpnext cp \
backend:/home/frappe/frappe-bench/sites/erp.example.com/private/backups \
~/erpnext-backupsEjecute esto desde cron y luego envíe el directorio a un lugar que usted no administre. copias de seguridad cifradas con restic a almacenamiento externo es la herramienta adecuada, ya que cifra los datos antes de subirlos y restic check verifica que el repositorio siga siendo legible. Una copia de seguridad de ERP es una copia de todo su libro contable, por lo que debe estar cifrada en reposo en un hardware distinto al actual.
Pruebe la restauración antes de necesitarla
Una copia de seguridad no probada es sólo una suposición. Restáurela en un segundo sitio del mismo servidor, nunca en el sitio en producción.
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 la clave de cifrado de la configuración respaldada al sitio restaurado; de lo contrario, sus integraciones seguirán sin funcionar:
docker compose --project-name erpnext exec backend \
bench --site restore-test.example.com set-config encryption_key '<value from site_config_backup.json>'Compruebe ahora la restauración como lo haría un contable. Abra el informe de cuentas por cobrar y compare el saldo de cierre con el del sitio en producción. Abra una factura de compra reciente y descargue su archivo adjunto. Que un sitio muestre la página de inicio de sesión no demuestra nada.
Elimine el sitio de prueba cuando termine:
docker compose --project-name erpnext exec backend \
bench drop-site restore-test.example.comPor qué el bloqueo de versiones es más importante en ERPNext
En un sitio estático, una etiqueta de imagen sin versión fija implica un reinicio inesperado. En ERPNext implica una migración del esquema. bench migrate reescribe las tablas de la base de datos y puede reescribir los datos de los documentos. No tiene deshacer. Revertir significa restaurar una copia de seguridad, no ejecutar un docker compose down.
Por tanto, fije la etiqueta. ERPNEXT_VERSION=v16.32.1 era la versión fijada en el pwd.yml del propio repositorio en agosto de 2026. El 2026-11-16, tanto pwd.yml como example.env fijaban v16.55.0. No use ninguna de esas versiones sin comprobarla antes. Las versiones actuales aparecen en la página de versiones de frappe/erpnext, y las etiquetas de imagen disponibles están en Docker Hub. Lea las notas de la versión a la que va a actualizar antes de iniciar el proceso.
La actualización comienza con una copia de seguridad y el modo de mantenimiento.
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 en ~/gitops/erpnext.env y, después, genere la configuración, descargue las imágenes y ejecute la migración.
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 offEl modo de mantenimiento es importante porque migrate modifica el esquema mientras se ejecuta. Si un usuario envía un documento contra una tabla parcialmente migrada, tendrá que reparar los registros manualmente.
Actualice una versión principal cada vez y haga una copia de seguridad entre cada paso. Consulte las instrucciones de migración de cada versión principal antes de continuar.
El repositorio también incluye overrides/compose.migrator.yaml. Añade un contenedor que ejecuta bench --site all migrate al iniciar cuando existen sitios y MIGRATE_SITES está habilitado, como ocurre de forma predeterminada. Es práctico. También significa que un docker compose up con una etiqueta modificada puede migrar la base de datos de producción sin supervisión. En un sistema empresarial, ejecute migrate como una decisión explícita tomada ese mismo día.
Refuerzo de la seguridad de un servidor que almacena registros de clientes
Cambie la contraseña de Administrator en el primer inicio de sesión. El archivo Compose de evaluación incluye admin como contraseña, y ese hábito se traslada a producción.
Cambie DB_PASSWORD para que no use el valor de 123 en example.env. Ese valor termina en el ~/gitops/erpnext.yaml generado en texto sin cifrar, así que chmod 600 el archivo y manténgalo fuera de cualquier repositorio de git. Para una opción más segura, overrides/compose.mariadb-secrets.yaml lee la contraseña de un archivo de secreto de Docker en lugar de una variable de entorno. gestión de archivos de entorno y secretos en Docker Compose explica las ventajas y desventajas.
Publique sólo lo necesario. Con la sobreescritura HTTPS, los únicos puertos expuestos son 80 y 443. No añada una asignación de ports al servicio db para facilitar la conexión de un cliente de base de datos: eso expone MariaDB a Internet. Use docker compose --project-name erpnext exec backend bench mariadb en su lugar. En el host, permita 22, 80 y 443, deniegue el resto y compruebe también el firewall de red independiente del proveedor.
Active la autenticación de dos factores en System Settings para todas las cuentas que tengan el rol System Manager. Ese rol puede cambiar System Settings, así que trátelo como una cuenta de administrador y no como una simple comodidad. Si ejecuta varias aplicaciones autoalojadas, Authentik como proveedor de inicio de sesión único autoalojado es mejor que añadir otra contraseña para cada aplicación.
Aplique los parches del host y reinicie para instalar las actualizaciones del kernel. Antes de confiar en que el stack volverá a iniciarse, compruebe que el archivo generado incluya una política restart para cada servicio, porque un stack sin ella permanece detenido después de ese reinicio. hacer que un stack de Docker Compose vuelva a iniciarse después de un reinicio explica la parte de systemd.
Cuando ERPNext deja de ser cómodo en un solo VPS
Un VPS puede alojar una empresa pequeña durante mucho tiempo. Estas son señales de que ya no es suficiente:
- Los trabajos en segundo plano se acumulan, por lo que los correos y las importaciones llegan con minutos u horas de retraso.
docker inspectinforma de contenedores con"OOMKilled": trueo con el código de salida 137.- Los informes que tardaban dos segundos tardan treinta, y MariaDB es el proceso que consume la CPU.
- Las copias de seguridad tardan tanto que una ejecución se solapa con la siguiente ejecución programada.
Empiece por asignar a MariaDB recursos que no comparta con otros servicios, porque la base de datos y los workers de Python compiten por la misma memoria, y el buffer pool es el componente que necesita más memoria. Un servidor de aplicaciones más grande ayuda menos de lo esperado. ejecutar la base de datos en Docker o en el host explica esta decisión, y configurar límites de memoria en Docker Compose evita que un contenedor deje sin recursos a los demás mientras realiza el cambio.
Después, añada workers de cola en lugar de aumentar la capacidad web. El trabajo lento de ERPNext se ejecuta en segundo plano: la generación de informes y las importaciones masivas. Más workers necesitan margen de CPU y memoria; añadir contenedores a un VPS que ya está saturado no aumenta la capacidad.
FAQ
¿Cuánta RAM necesita ERPNext en un VPS?
Para una evaluación, empiece con 4 GB y 2 vCPU. Para una empresa que lo usa a diario, planifique 8 GB y 4 vCPU con 100 GB de SSD. Bajo presión de memoria, el kernel puede detener contenedores mediante el mecanismo out of memory killer, que docker inspect informa como "OOMKilled": true con el código de salida 137. Son valores iniciales, no mediciones, así que supervise el uso de memoria propio durante el primer mes.
¿Puedo ejecutar pwd.yml en producción?
No. El README del proyecto lo describe como destinado únicamente a evaluaciones de corta duración y señala que no permite instalar aplicaciones personalizadas. Use compose.yaml con las sobrescrituras de MariaDB, Redis y HTTPS, genérelas en un solo archivo con docker compose config y ejecute ese archivo.
¿Por qué mi sitio de ERPNext no está disponible justo después de crearlo?
De forma predeterminada, el frontend elige el sitio que debe servir a partir de la cabecera HTTP Host, por lo que el nombre del sitio debe coincidir con el dominio del navegador. Un sitio creado como erpnext no se sirve en erp.example.com. Cree el sitio usando el dominio como nombre o establezca FRAPPE_SITE_NAME_HEADER en el archivo de entorno con el nombre del sitio, vuelva a generar el archivo compose y reinicie el stack.
¿Qué debe incluir una copia de seguridad de ERPNext?
Cuatro archivos, conservados juntos: el volcado de -database.sql.gz, los archivos -files.tar y -private-files.tar y la copia de configuración -site_config_backup.json. bench --site erp.example.com backup --with-files genera los cuatro. La copia de configuración contiene encryption_key, por lo que una restauración sin ella deja sin posibilidad de descifrado las contraseñas de integraciones almacenadas, lo que se manifiesta como Encryption key is invalid! Please check site_config.json.
¿Cómo actualizo ERPNext sin dañar mis datos?
Haga una copia de seguridad con --with-files, active el modo de mantenimiento, cambie ERPNEXT_VERSION en el archivo de entorno, vuelva a generar el archivo compose, descargue las imágenes, inicie el stack y ejecute bench --site erp.example.com migrate; después, desactive el modo de mantenimiento. Avance una versión principal cada vez y lea primero las notas de la versión, porque migrate reescribe el esquema y los datos de los documentos sin posibilidad de deshacer los cambios. Para revertir la actualización, restaure la copia de seguridad creada al principio.