Guía Técnica: Instalación de Frappe ERPNext en Debian 12, Ubuntu 24.04 y Fedora

📋 Introducción

La instalación manual de Frappe Framework y ERPNext ofrece control total sobre tu infraestructura, ideal para entornos de producción que requieren personalización, auditoría de seguridad o integración con sistemas locales. En esta guía, cubriremos la instalación paso a paso en tres distribuciones Linux populares, utilizando las mejores prácticas actuales para 2026.

✅ ¿Por qué elegir instalación manual vs Docker?

Ventaja	Descripción
🔧 Control granular	Acceso directo a configuración de Nginx, Supervisor y MariaDB
🐛 Depuración simplificada	Logs accesibles sin capas de contenedores
📦 Personalización	Modificación de dependencias sin reconstruir imágenes
💰 Optimización de recursos	Sin overhead de virtualización adicional

📌 Requisitos mínimos del servidor: 4 GB RAM, 2 vCPU, 50 GB almacenamiento, conexión SSH con usuario sudo.

🔄 Tabla de Compatibilidad de Versiones (Frappe v16)

Dependencia	Versión Requerida	Notas
Python	3.14	Gestionado con `uv`
Node.js	24 LTS	Instalado vía nvm o NodeSource
MariaDB	11.8+	Configuración utf8mb4 obligatoria
Redis	6+	Para caché y colas de trabajo
Yarn	1.22+	Gestión de assets frontend
wkhtmltopdf	0.12.6 (patched qt)	Generación de PDFs

🐧 Fase 1: Preparación del Sistema Operativo

🔹 Debian 12 / Ubuntu 24.04 LTS

# 1. Actualizar paquetes del sistema
sudo apt update && sudo apt upgrade -y

# 2. Instalar dependencias base
sudo apt install -y git redis-server mariadb-server mariadb-client \
pkg-config libmariadb-dev gcc build-essential libssl-dev cron \
nginx supervisor python3-dev python3-setuptools python3-pip \
xvfb libfontconfig nano wget curl

# 3. Instalar wkhtmltopdf (requiere libssl1.1 en Ubuntu 24.04)
wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo dpkg -i wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo apt --fix-broken install -y

# Verificar instalación
wkhtmltopdf --version  # Debe mostrar: 0.12.6 (with patched qt)

🔹 Fedora 40/41

# 1. Actualizar sistema
sudo dnf update -y

# 2. Instalar dependencias base
sudo dnf install -y git redis mariadb-server mariadb \
pkgconf-pkg-config gcc gcc-c++ openssl-devel cronie \
nginx supervisor python3-devel python3-pip \
xorg-x11-server-Xvfb fontconfig nano wget curl

# 3. Habilitar e iniciar servicios
sudo systemctl enable --now redis mariadb

# 4. Instalar wkhtmltopdf desde RPM Fusion o compilar desde fuente
sudo dnf install -y wkhtmltopdf
# Nota: Verificar que sea versión 0.12.6 con Qt parcheado

🗄️ Fase 2: Configuración de MariaDB

# 1. Crear archivo de configuración específico para Frappe
sudo tee /etc/mysql/mariadb.conf.d/99-frappe.cnf > /dev/null <<'EOF'
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4
EOF

# 2. Reiniciar MariaDB para aplicar cambios
sudo systemctl restart mariadb

# 3. Ejecutar script de seguridad
sudo mariadb-secure-installation

Respuestas recomendadas durante la configuración:
- ¿Establecer contraseña root? → Sí (guardar en gestor de contraseñas)
- ¿Eliminar usuarios anónimos? → Sí
- ¿Desactivar login remoto de root? → Sí (a menos que necesites acceso BI externo)
- ¿Eliminar base de datos de test? → Sí
- ¿Recargar tablas de privilegios? → Sí

👤 Fase 3: Creación de Usuario Dedicado

# Crear usuario 'frappe' con permisos limitados
sudo useradd -m -s /bin/bash frappe
sudo usermod -aG sudo frappe  # Debian/Ubuntu
# sudo usermod -aG wheel frappe  # Fedora

# Establecer contraseña segura
sudo passwd frappe

# Crear directorio de trabajo y asignar permisos
sudo mkdir -p /opt/frappe
sudo chown -R frappe:frappe /opt/frappe
sudo chmod 750 /opt/frappe

# Agregar www-data al grupo frappe para acceso de Nginx
sudo usermod -aG frappe www-data

# Cambiar al usuario frappe para continuar
sudo su - frappe

🔐 Mejor práctica: Nunca ejecutar servicios de aplicación como root. El usuario frappe tendrá permisos mínimos necesarios.

🐍 Fase 4: Entorno Python con uv (Recomendado Oficialmente)

Frappe v16 recomienda usar uv, un gestor de paquetes Python ultra-rápido escrito en Rust.

# 1. Instalar uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc  # O ~/.zshrc según tu shell

# 2. Instalar Python 3.14 como versión predeterminada
uv python install 3.14 --default

# 3. Verificar instalación
uv --version        # Debe mostrar versión reciente
python3.14 --version  # Debe mostrar Python 3.14.x

Alternativa: Entorno virtual tradicional (si prefieres venv)

# Solo si no usas uv:
python3.14 -m venv /opt/frappe/venv
source /opt/frappe/venv/bin/activate
pip install --upgrade pip setuptools wheel

⚙️ Fase 5: Instalación de Node.js y Bench CLI

Instalación de Node.js 24 LTS
Opción A: Via NodeSource (Recomendado para producción)

# Debian/Ubuntu
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

# Fedora
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo dnf install -y nodejs

# Instalar Yarn globalmente
sudo npm install -g yarn

Opción B: Via nvm (Flexibilidad para desarrollo)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24
nvm use 24
npm install -g yarn

Instalación de Frappe Bench

Frappe Bench es la herramienta oficial de línea de comandos (CLI) diseñada para administrar aplicaciones basadas en el framework Frappe, siendo ERPNext la más conocida.

# Instalar bench CLI usando uv (método oficial para v16)
uv tool install frappe-bench --python python3.14

# Verificar instalación
bench --version  # Debe mostrar versión >= 5.x

🏗️ Fase 6: Inicialización del Bench y Creación de Sitio

# Navegar al directorio de trabajo
cd /opt/frappe

# 1. Inicializar nuevo bench con Frappe v16
bench init frappe-bench \
  --frappe-branch version-16 \
  --python python3.14

# 2. Entrar al directorio del bench
cd frappe-bench

# 3. Descargar ERPNext (y otras apps si las necesitas)
bench get-app --branch version-16 erpnext
# Apps adicionales opcionales (e-commerce):
# bench get-app  payments
# bench get-app  webshop

# 4. Crear nuevo sitio
bench new-site miproyecto.local \
  --admin-password 'TuContraseñaSegura123!' \
  --db-root-password 'ContraseñaRootMariaDB' \
  --mariadb-user-host-login-scope=%

# 5. Instalar ERPNext en el sitio
bench --site miproyecto.local install-app erpnext

# 6. Habilitar el scheduler para trabajos programados
bench --site miproyecto.local enable-scheduler

🌐 Fase 7: Configuración de Producción (Nginx + Supervisor)

# 1. Habilitar multi-tenancy por DNS (necesario para dominios personalizados)
bench config dns_multitenant on

# 2. Generar configuraciones de Nginx y Supervisor
bench setup nginx
bench setup supervisor

# 3. Instalar Ansible (requerido para setup production en v16)
sudo apt install -y ansible  # Debian/Ubuntu
# sudo dnf install -y ansible  # Fedora

# 4. Configurar entorno de producción
sudo env "PATH=$PATH" bench setup production frappe

# 5. Vincular archivos de configuración al sistema
sudo ln -sf /opt/frappe/frappe-bench/config/nginx.conf /etc/nginx/conf.d/frappe.conf
sudo ln -sf /opt/frappe/frappe-bench/config/supervisor.conf /etc/supervisor/conf.d/frappe.conf

# 6. Recargar servicios
sudo supervisorctl reread
sudo supervisorctl update
sudo systemctl restart nginx
sudo supervisorctl restart all

# 7. Verificar estado de servicios
sudo supervisorctl status

Salida esperada: Todos los procesos deben mostrar RUNNING.

🔒 Fase 8: SSL con Let's Encrypt (Opcional pero Recomendado)

# Instalar Certbot
sudo snap install core && sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

# Configurar SSL para tu dominio
# Primero, asegúrate de que tu dominio apunta a la IP del servidor
sudo bench setup lets-encrypt miproyecto.tudominio.com

# Reiniciar Nginx para aplicar cambios
sudo systemctl reload nginx

🧪 Verificación Final y Primer Acceso

# Verificar apps instaladas
bench --site miproyecto.local list-apps

# Verificar versión del sistema
bench version --format table

Acceder a tu instancia:
- Desarrollo: http://miproyecto.local:8000 (requiere edición de /etc/hosts)
- Producción: https://miproyecto.tudominio.com

Credenciales por defecto:
- Usuario: Administrator
- Contraseña: La establecida en bench new-site

📚 Recursos Adicionales

💡 Nota para clientes potenciales: Esta guía técnica demuestra nuestra experiencia práctica con tecnologías de código abierto. Si buscas implementar ERPNext en tu organización con cumplimiento FEL en Guatemala, contáctanos para una consultoría personalizada.