ERPNext es un ERP de código abierto construido sobre el framework Frappe que reúne contabilidad, inventario, compras, ventas, fabricación y recursos humanos en una sola aplicación web. En este tutorial instalarás ERPNext 15 en Ubuntu 24.04 con la herramienta oficial Frappe Bench, MariaDB y Redis, lo pondrás en modo producción con Nginx y Supervisor y lo publicarás con HTTPS en tu dominio.

Requisitos previos

Para seguir esta guía necesitas:

  • Un servidor con Ubuntu 24.04 LTS recién instalado, por ejemplo un VPS de CubePath, con al menos 4 GB de RAM (8 GB recomendados), 2 vCPU y 40 GB de disco.
  • Acceso con un usuario con privilegios sudo.
  • Un dominio con un registro DNS de tipo A que apunte a la IP del servidor. En esta guía se usa your_domain como marcador: sustitúyelo por tu dominio real en todos los comandos.
  • Los puertos 22, 80 y 443 abiertos.

ERPNext 15 necesita Python 3.10 o superior, Node.js 18 o superior, MariaDB 10.6 o superior y Redis. Ubuntu 24.04 incluye Python 3.12, Node.js 18 y MariaDB 10.11, así que todo se instala desde los repositorios de la distribución.

Paso 1: Crear el usuario frappe

Frappe Bench no debe ejecutarse como root. Crea un usuario dedicado llamado frappe y dale permisos de sudo, que necesitará al configurar el modo producción:

sudo adduser frappe
sudo usermod -aG sudo frappe

Ubuntu 24.04 crea los directorios personales con permisos 750, lo que impide que Nginx lea los archivos estáticos de ERPNext. Da permiso de paso (no de lectura del listado) al resto de usuarios:

sudo chmod o+x /home/frappe

Comprueba los permisos:

ls -ld /home/frappe

drwxr-x--x 2 frappe frappe 4096 Sep 25 10:00 /home/frappe

Paso 2: Instalar las dependencias del sistema

Actualiza el sistema e instala Python, Git, MariaDB, Redis, Node.js, Nginx, Supervisor y wkhtmltopdf, que ERPNext usa para generar los PDF de facturas y otros documentos:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl cron python3-dev python3-venv python3-pip pipx \
  mariadb-server mariadb-client redis-server nodejs npm \
  nginx supervisor xvfb libfontconfig1 wkhtmltopdf

Frappe usa Yarn para compilar los recursos del frontend. Instálalo de forma global con npm:

sudo npm install -g yarn

Verifica las versiones instaladas:

python3 --version
node --version
yarn --version
mariadb --version

Python 3.12.3
v18.19.1
1.22.22
mariadb  Ver 15.1 Distrib 10.11.8-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper

Paso 3: Configurar MariaDB

ERPNext requiere que MariaDB use el juego de caracteres utf8mb4. Crea un archivo de configuración propio para no editar los archivos del paquete:

sudo nano /etc/mysql/mariadb.conf.d/99-frappe.cnf

Añade este contenido:

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

Reinicia MariaDB para aplicar los cambios:

sudo systemctl restart mariadb

A continuación ejecuta el asistente de seguridad. Cuando pregunte por cambiar la contraseña de root, responde que sí y define una contraseña robusta (Bench te la pedirá al crear el sitio). Responde también que sí a eliminar usuarios anónimos, deshabilitar el acceso remoto de root y eliminar la base de datos de pruebas:

sudo mariadb-secure-installation

Comprueba que el juego de caracteres es el correcto:

sudo mariadb -e "SHOW VARIABLES LIKE 'character_set_server';"

+----------------------+---------+
| Variable_name        | Value   |
+----------------------+---------+
| character_set_server | utf8mb4 |
+----------------------+---------+

Paso 4: Instalar Frappe Bench

A partir de aquí trabaja como el usuario frappe:

sudo -iu frappe

Ubuntu 24.04 no permite instalar paquetes de Python con pip fuera de un entorno virtual. Usa pipx, que instala frappe-bench en su propio entorno y deja el comando bench en ~/.local/bin:

pipx install frappe-bench
pipx ensurepath

Cierra la sesión y vuelve a entrar para que el nuevo PATH tenga efecto:

exit
sudo -iu frappe

Comprueba que bench está disponible:

bench --version

5.25.1

El número de versión puede variar; basta con que el comando responda.

Paso 5: Inicializar el directorio de Bench

bench init descarga Frappe en la rama version-15, crea un entorno virtual de Python e instala las dependencias de JavaScript. Tarda varios minutos:

cd ~
bench init --frappe-branch version-15 frappe-bench

Al terminar verás un mensaje similar a este:

SUCCESS: Bench frappe-bench initialized

Entra en el directorio creado. Todos los comandos bench siguientes deben ejecutarse desde aquí:

cd ~/frappe-bench

Paso 6: Crear el sitio e instalar ERPNext

Un "sitio" en Frappe es una instancia con su propia base de datos. Usa tu dominio como nombre del sitio, así Nginx podrá enrutar las peticiones por nombre de host:

bench new-site your_domain

Bench te pedirá la contraseña de root de MariaDB que definiste en el paso 3 y una contraseña para el usuario Administrator de ERPNext. Guárdala: la usarás para entrar por primera vez.

Descarga la aplicación ERPNext en la misma rama que Frappe e instálala en el sitio:

bench get-app --branch version-15 erpnext
bench --site your_domain install-app erpnext

Activa el planificador de tareas, que ejecuta procesos en segundo plano como correos, informes programados y copias de seguridad:

bench --site your_domain enable-scheduler
bench --site your_domain set-maintenance-mode off

Comprueba las aplicaciones instaladas en el sitio:

bench --site your_domain list-apps

frappe 15.x.x version-15
erpnext 15.x.x version-15

Paso 7: Configurar el modo producción

En desarrollo, bench start lanza todos los procesos en primer plano. En producción, Supervisor mantiene vivos los procesos de Frappe (servidor web, workers, Redis y socket.io) y Nginx sirve los archivos estáticos y hace de proxy inverso.

Activa el enrutado por nombre de dominio, para que Nginx responda a your_domain en el puerto 80:

bench config dns_multitenant on

bench setup production genera la configuración de Supervisor y Nginx y recarga ambos servicios. Debe ejecutarse con sudo, pero como bench está en ~/.local/bin, pasa el PATH del usuario:

sudo env "PATH=$PATH" bench setup production frappe

Cuando termine, comprueba que todos los procesos están en ejecución:

sudo supervisorctl status

frappe-bench-redis:frappe-bench-redis-cache                 RUNNING   pid 4101, uptime 0:00:35
frappe-bench-redis:frappe-bench-redis-queue                 RUNNING   pid 4102, uptime 0:00:35
frappe-bench-web:frappe-bench-frappe-web                    RUNNING   pid 4103, uptime 0:00:35
frappe-bench-web:frappe-bench-node-socketio                 RUNNING   pid 4104, uptime 0:00:35
frappe-bench-workers:frappe-bench-frappe-schedule           RUNNING   pid 4105, uptime 0:00:35
frappe-bench-workers:frappe-bench-frappe-long-worker-0      RUNNING   pid 4106, uptime 0:00:35
frappe-bench-workers:frappe-bench-frappe-short-worker-0     RUNNING   pid 4107, uptime 0:00:35

Verifica la configuración de Nginx:

sudo nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Paso 8: Abrir el cortafuegos y activar HTTPS

Permite SSH y el tráfico web en UFW y actívalo:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
Nginx Full                 ALLOW       Anywhere

Instala Certbot con su plugin de Nginx y solicita un certificado de Let's Encrypt. Certbot modifica la configuración que generó Bench para añadir el bloque HTTPS y la redirección desde HTTP:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your_domain

Comprueba que la renovación automática funciona:

sudo certbot renew --dry-run

Congratulations, all simulated renewals succeeded:
  /etc/letsencrypt/live/your_domain/fullchain.pem (success)

Paso 9: Completar el asistente de configuración

Abre https://your_domain en el navegador e inicia sesión con el usuario Administrator y la contraseña que definiste en el paso 6. ERPNext mostrará el asistente inicial, donde eliges idioma, país, zona horaria, moneda, los datos de tu empresa y el plan contable.

Cuando termines llegarás al escritorio de ERPNext con los módulos de Contabilidad, Compras, Ventas, Inventario y el resto disponibles en la barra lateral. Crea usuarios nominales para tu equipo desde Usuarios y reserva Administrator para tareas de administración.

Paso 10: Programar copias de seguridad

Bench incluye un comando que exporta la base de datos y, con --with-files, los archivos adjuntos públicos y privados. Pruébalo manualmente como usuario frappe:

cd ~/frappe-bench
bench --site your_domain backup --with-files

Backup Summary for your_domain at 2026-09-25 10:30:12.345678
Config  : ./your_domain/private/backups/20260925_103012-your_domain-site_config_backup.json 312.0B
Database: ./your_domain/private/backups/20260925_103012-your_domain-database.sql.gz         1.2MiB
Public  : ./your_domain/private/backups/20260925_103012-your_domain-files.tar               10.0KiB
Private : ./your_domain/private/backups/20260925_103012-your_domain-private-files.tar       10.0KiB
Backup for Site your_domain has been successfully completed with files

Para ejecutarlo cada noche, edita el crontab del usuario frappe:

crontab -e

Añade esta línea, que lanza la copia a las 03:00:

0 3 * * * cd /home/frappe/frappe-bench && /home/frappe/.local/bin/bench --site your_domain backup --with-files >> /home/frappe/frappe-bench/logs/backup.log 2>&1

Las copias se guardan en ~/frappe-bench/sites/your_domain/private/backups/, en el mismo servidor. Cópialas periódicamente a otro sistema (por ejemplo con rsync o rclone hacia un almacenamiento de objetos) para poder recuperarte si pierdes el servidor. Para restaurar una copia en un sitio existente se usa bench --site your_domain restore con la ruta del archivo .sql.gz.

Solución de problemas

La página carga sin estilos o los archivos de /assets devuelven 403. Nginx no puede atravesar /home/frappe. Repite sudo chmod o+x /home/frappe y recarga Nginx con sudo systemctl reload nginx.

sudo: bench: command not found al configurar producción. sudo no hereda el PATH del usuario. Usa sudo env "PATH=$PATH" bench ... como en el paso 7.

Error de acceso a MariaDB al crear el sitio. Asegúrate de haber definido una contraseña para root en mariadb-secure-installation y de estar introduciendo esa contraseña, no la del usuario de sistema.

Errores 502 Bad Gateway. Algún proceso de Supervisor está parado. Revisa sudo supervisorctl status y los registros en ~/frappe-bench/logs/, por ejemplo web.error.log y worker.error.log. Reinicia todo con sudo supervisorctl restart all.

Conclusión

Ya tienes ERPNext 15 funcionando en producción sobre Ubuntu 24.04, con Supervisor gestionando los procesos, Nginx con HTTPS delante y copias de seguridad diarias. Como siguientes pasos, configura una cuenta de correo saliente en Cuenta de correo electrónico para que ERPNext envíe facturas y notificaciones, envía las copias fuera del servidor y aplica las actualizaciones menores de la rama 15 con bench update tras hacer una copia de seguridad.