Instalación de Invoice Ninja en un VPS: Docker, SSL, SMTP, cron y copias de seguridad
TL;DR
Invoice Ninja se puede implementar en un VPS con Docker Compose: la aplicación, MySQL y Redis se ejecutan de forma aislada, Caddy obtiene automáticamente un certificado TLS y cron realiza copias de seguridad de la base de datos y los archivos. A continuación se presenta un esquema práctico para Ubuntu Server 24.04 LTS.
- Usamos Invoice Ninja 5.x, Docker Engine y Docker Compose v2.
- Colocamos la aplicación detrás de Caddy con HTTPS automático.
- Configuramos SMTP para enviar facturas y notificaciones.
- Creamos un usuario del sistema, acceso SSH, UFW y Fail2ban.
- Configuramos un volcado diario de MySQL y copias de seguridad mediante Restic en un almacenamiento compatible con S3.
- Comprobamos los contenedores, HTTPS, SMTP, la cola de tareas y la restauración desde la copia de seguridad.
1. TL;DR
Esta guía explica cómo instalar Invoice Ninja en un VPS propio sin instalar manualmente PHP, Composer ni un servidor web. Docker ejecuta Invoice Ninja, MySQL y Redis; Caddy recibe las solicitudes HTTPS y renueva automáticamente el certificado; y cron ejecuta las copias de seguridad.
- Sistema operativo: Ubuntu Server 24.04 LTS.
- Dominio: por ejemplo,
billing.example.com. - Servidor mínimo funcional: 2 vCPU, 4 GB de RAM y 40 GB de SSD.
- Para una empresa pequeña, es mejor utilizar 4 vCPU, 8 GB de RAM y 80 GB de NVMe.
- Los puertos 80 y 443 los utiliza Caddy; el puerto 22 se utiliza para SSH.
2. Contenido
El material está estructurado como un procedimiento secuencial: desde la elección de recursos y la protección básica del servidor hasta la comprobación del correo, la restauración de la base de datos y el mantenimiento periódico.
- Definición de requisitos y arquitectura.
- Preparación del VPS y del acceso SSH.
- Instalación de Docker Engine y Compose.
- Creación de la configuración de Docker Compose.
- Configuración del dominio, Caddy y TLS.
- Conexión de SMTP y tareas en segundo plano.
- Configuración de las copias de seguridad.
- Diagnóstico de errores y respuestas a preguntas frecuentes.
3. Qué configuramos y por qué
Qué es Invoice Ninja
Invoice Ninja es una aplicación web para emitir facturas, propuestas comerciales, facturas recurrentes, gestionar clientes y aceptar pagos. La versión Self-hosted es adecuada para autónomos, pequeñas agencias y empresas que necesitan controlar sus datos, su dominio y el proceso de envío de documentos.
Con una instalación propia, la aplicación funciona en su servidor. Los datos de los clientes y las facturas se almacenan en su base de datos, mientras que el envío de correos se realiza mediante el proveedor SMTP elegido. Esto difiere del escenario SaaS, en el que la infraestructura, las actualizaciones y las copias de seguridad están controladas por una plataforma externa.
Arquitectura final
Después de completar las instrucciones, se obtendrá el siguiente esquema:
| Componente | Propósito | Acceso público |
|---|---|---|
| Caddy | HTTPS, certificados automáticos y reverse proxy | 80, 443 |
| Invoice Ninja | Interfaz web y API | Solo a través de Caddy |
| MySQL 8 | Almacenamiento de clientes, facturas y configuraciones | Solo la red interna de Docker |
| Redis 7 | Caché y colas de tareas en segundo plano | Solo la red interna de Docker |
| Restic | Copias de seguridad cifradas | Conexiones salientes a S3 |
Qué funcionará después de la instalación
- Acceso a Invoice Ninja en una dirección como
https://billing.example.com. - Creación de clientes, productos, facturas y plantillas.
- Envío de facturas por correo electrónico mediante SMTP.
- Generación de archivos PDF y almacenamiento de cargas de usuario.
- Tareas en segundo plano mediante Redis y un contenedor worker.
- Copias de seguridad diarias y cifradas de la base de datos y los archivos.
Cloud-managed o self-hosted
La opción en la nube es más sencilla para empezar a trabajar: no es necesario actualizar el servidor, controlar el espacio en disco ni comprobar la restauración de las copias de seguridad. A cambio, hay que pagar una suscripción periódica y aceptar limitaciones relacionadas con los datos, las integraciones y la configuración.
El Invoice Ninja self-hosted en un VPS requiere más responsabilidad. Es necesario actualizar las imágenes por cuenta propia, restringir el acceso, controlar SMTP y verificar las copias. A cambio, el coste fijo del alquiler del servidor suele ser predecible y los datos se pueden almacenar en la jurisdicción elegida.
Un VPS es un compromiso práctico para un proyecto o un equipo pequeño. Un servidor dedicado está justificado cuando hay muchos clientes, un gran volumen de PDF, varias aplicaciones empresariales funcionando en paralelo o una estricta separación de recursos.
Qué no incluye este escenario
Esta guía no configura una pasarela de pago, una integración contable, un servidor DNS ni un SMTP corporativo. Estos parámetros dependen del país, el banco y el proveedor elegido. Para los pagos también se necesitarán claves API y la comprobación de las direcciones de webhook.
4. Qué configuración de VPS se necesita para esta tarea
Invoice Ninja no requiere un servidor potente para varios usuarios; sin embargo, contar con suficiente RAM es importante para MySQL, Redis, Docker y la generación de PDF. No conviene orientarse únicamente por la carga media de la CPU: aparecen picos breves durante el envío masivo de facturas y la generación de documentos.
Requisitos mínimos
| Recurso | Mínimo | Opción práctica |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU |
| RAM | 4 GB | 8 GB |
| Disco | 40 GB SSD | 80–120 GB NVMe |
| Red | 100 Mbit/s | 1 Gbit/s o un buen burst |
| IPv4 | 1 dirección pública | 1 IPv4 y IPv6 si es necesario |
| SO | Ubuntu 24.04 LTS | Ubuntu 24.04 LTS |
La configuración mínima es adecuada para un propietario, varios empleados y un número reducido de facturas al mes. Si también funcionan CRM, GitLab, Mattermost o sistemas de monitorización, 4 GB de RAM se convertirán rápidamente en una limitación.
Para una empresa pequeña típica, se puede elegir un VPS adecuado con 4 vCPU, 8 GB de RAM, un disco NVMe de al menos 80 GB y copias de seguridad, o bien un almacenamiento S3 independiente.
Cuándo se necesita un servidor dedicado
Un servidor dedicado tiene sentido si Invoice Ninja atiende a decenas de miles de clientes, genera una gran cantidad de PDF simultáneamente o funciona junto a otros servicios que consumen muchos recursos. También resulta útil cuando se requieren núcleos dedicados, discos NVMe locales y un aislamiento completo de otros usuarios.
Para un único Invoice Ninja, un servidor dedicado suele ser excesivo. Los costes adicionales no eliminan la necesidad de realizar copias de seguridad, actualizaciones y configuraciones de seguridad. Antes de migrar, es mejor medir el uso de CPU, RAM, I/O y el tiempo de ejecución de la cola.
Ubicación del servidor
La ubicación influye en la latencia de la interfaz, la velocidad de carga de los PDF y los requisitos de almacenamiento de datos personales. Es recomendable ubicar el servidor cerca de los empleados y clientes que trabajan con el sistema con mayor frecuencia. Si los usuarios se encuentran en distintas regiones, elija un centro de datos con un buen peering internacional.
Para el correo electrónico, la ubicación geográfica es menos importante que la reputación de la dirección IP. Compruebe que el proveedor permite SMTP saliente y que el registro PTR se puede configurar correctamente. Para enviar correo, normalmente es más seguro utilizar un servicio SMTP externo que un servidor de correo propio.
5. Preparación del servidor
A continuación se presupone un Ubuntu Server 24.04 LTS limpio con acceso mediante un usuario que tenga privilegios de root. Todos los comandos se ejecutan en una sesión SSH. Sustituya los valores entre corchetes angulares por sus propios datos.
Creación de un usuario administrativo
# Создаём отдельного пользователя для администрирования
sudo adduser deploy
# Добавляем пользователя в группу sudo
sudo usermod -aG sudo deploy
# Проверяем членство в группе
id deploy
No utilice root para el trabajo cotidiano. El usuario deploy ejecutará los comandos mediante sudo, y los comandos de Docker se podrán ejecutar con su nombre después de añadirlo al grupo Docker.
Configuración de la clave SSH
En el equipo local, cree una clave Ed25519 si todavía no dispone de una:
# Выполняется на локальном компьютере
ssh-keygen -t ed25519 -C "deploy-invoiceninja"
# Копируем открытый ключ на сервер
ssh-copy-id deploy@SERVER_IP
Abra una sesión SSH independiente con el nuevo usuario y asegúrese de que el acceso funciona. Solo después de comprobarlo podrá desactivar el acceso mediante contraseña.
# Открываем конфигурацию SSH
sudo nano /etc/ssh/sshd_config.d/ hardening.conf
En el comando anterior no debe haber ningún espacio entre el nombre del directorio y el archivo. Utilice el comando correcto:
# Создаём файл дополнительных настроек SSH
sudo nano /etc/ssh/sshd_config.d/hardening.conf
Añada la configuración:
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no
PubkeyAuthentication yes
# Проверяем синтаксис конфигурации SSH
sudo sshd -t
# Перезапускаем SSH без закрытия текущей сессии
sudo systemctl reload ssh
Actualización de Ubuntu y utilidades básicas
# Обновляем индекс пакетов и устанавливаем последние исправления
sudo apt update && sudo apt full-upgrade -y
# Устанавливаем утилиты для администрирования, TLS и резервного копирования
sudo apt install -y ca-certificates curl gnupg lsb-release \
git unzip jq nano vim htop ncdu ufw fail2ban restic apache2-utils
# Перезагружаем сервер, если обновлялось ядро
sudo reboot
Después del reinicio, vuelva a conectarse con deploy. No instale varios servidores web simultáneamente. En esta guía, HTTP y HTTPS son atendidos por Caddy dentro de un contenedor.
Configuración de UFW
# Разрешаем SSH, HTTP и HTTPS
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# Включаем межсетевой экран
sudo ufw --force enable
# Проверяем активные правила
sudo ufw status verbose
No exponga los puertos de MySQL, Redis ni el puerto interno de la aplicación. La red de Docker proporciona la comunicación entre los contenedores, y solo Caddy debe permanecer accesible públicamente.
Configuración de Fail2ban
# Создаём локальную конфигурацию Fail2ban
sudo nano /etc/fail2ban/jail.d/sshd.local
[sshd]
enabled = true
port = 22
backend = systemd
maxretry = 5
findtime = 10m
bantime = 1h
# Запускаем Fail2ban и добавляем его в автозагрузку
sudo systemctl enable --now fail2ban
# Проверяем состояние SSH-защиты
sudo fail2ban-client status sshd
Fail2ban no sustituye a las claves SSH ni al firewall. Solo bloquea temporalmente las direcciones que infringen repetidamente las reglas de acceso.
6. Instalación del software — paso a paso
6. Instalación del software — paso a paso
Paso 1. Instalación de Docker Engine
Utilice el repositorio oficial de Docker, no los paquetes antiguos del repositorio estándar de Ubuntu. En 2026, para este esquema es adecuado Docker Engine 28.x o una versión compatible más reciente, además de Docker Compose v2.
# Создаём каталог для ключей репозитория Docker
sudo install -m 0755 -d /etc/apt/keyrings
# Загружаем официальный ключ репозитория
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# Разрешаем чтение ключа менеджеру пакетов
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# Добавляем официальный репозиторий Docker для Ubuntu 24.04
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu noble stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Обновляем индекс пакетов
sudo apt update
# Устанавливаем Docker Engine, CLI и Compose plugin
sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
# Запускаем Docker при старте системы
sudo systemctl enable --now docker
# Разрешаем пользователю deploy работать с Docker
sudo usermod -aG docker deploy
Salga de SSH y vuelva a entrar para actualizar el grupo del usuario:
# Проверяем версии Docker и Compose
docker version
docker compose version
# Проверяем работу Docker тестовым контейнером
docker run --rm hello-world
Paso 2. Creación del directorio de la aplicación
# Создаём отдельный каталог проекта
sudo mkdir -p /opt/invoiceninja/{caddy,data/mysql,data/redis,backups,config}
# Передаём каталог пользователю deploy
sudo chown -R deploy:deploy /opt/invoiceninja
# Переходим в рабочий каталог
cd /opt/invoiceninja
Paso 3. Creación del archivo de secretos
El archivo .env contiene las contraseñas de la base de datos y la clave de la aplicación. No debe incluirse en Git, en un directorio web público ni en una copia de seguridad pública sin cifrado.
# Генерируем случайные значения
APP_KEY_VALUE="base64:$(openssl rand -base64 32 | tr -d '\n')"
MYSQL_ROOT_VALUE="$(openssl rand -hex 24)"
MYSQL_PASSWORD_VALUE="$(openssl rand -hex 24)"
RESTIC_PASSWORD_VALUE="$(openssl rand -base64 32 | tr -d '\n')"
# Создаём файл окружения
cat > /opt/invoiceninja/.env <<EOF
TZ=UTC
APP_URL=https://billing.example.com
APP_KEY=${APP_KEY_VALUE}
APP_DEBUG=false
REQUIRE_HTTPS=true
MYSQL_DATABASE=ninja
MYSQL_USER=ninja
MYSQL_PASSWORD=${MYSQL_PASSWORD_VALUE}
MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_VALUE}
DB_HOST=db
DB_PORT=3306
DB_DATABASE=ninja
DB_USERNAME=ninja
DB_PASSWORD=${MYSQL_PASSWORD_VALUE}
REDIS_HOST=redis
REDIS_PORT=6379
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.net
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=CHANGE_ME_SMTP_PASSWORD
MAIL_ENCRYPTION=tls
[email protected]
MAIL_FROM_NAME=Billing
RESTIC_REPOSITORY=s3:s3.example.net/invoiceninja
RESTIC_PASSWORD=${RESTIC_PASSWORD_VALUE}
AWS_ACCESS_KEY_ID=CHANGE_ME_S3_KEY
AWS_SECRET_ACCESS_KEY=CHANGE_ME_S3_SECRET
EOF
# Ограничиваем доступ к секретам
chmod 600 /opt/invoiceninja/.env
Sustituya billing.example.com, los parámetros SMTP y las claves S3. No utilice la contraseña del panel de Invoice Ninja como contraseña de la base de datos o de SMTP.
Paso 4. Creación de Docker Compose
Cree el archivo compose.yml. La imagen de Invoice Ninja 5.x contiene una aplicación Laravel. Es preferible fijar la versión de la imagen en una etiqueta estable concreta después de revisar las release notes, en lugar de utilizar latest sin criterio.
services:
app:
image: invoiceninja/invoiceninja:5
restart: unless-stopped
env_file:
- .env
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
expose:
- "80"
volumes:
- app_storage:/var/www/app/storage
- app_public_storage:/var/www/app/public/storage
networks:
- internal
worker:
image: invoiceninja/invoiceninja:5
restart: unless-stopped
env_file:
- .env
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
command: ["php", "artisan", "queue:work", "--sleep=3", "--tries=3", "--timeout=120"]
volumes:
- app_storage:/var/www/app/storage
- app_public_storage:/var/www/app/public/storage
networks:
- internal
scheduler:
image: invoiceninja/invoiceninja:5
restart: unless-stopped
env_file:
- .env
depends_on:
db:
condition: service_healthy
redis:
condition: service_healthy
command: ["sh", "-c", "while true; do php artisan schedule:run; sleep 60; done"]
volumes:
- app_storage:/var/www/app/storage
- app_public_storage:/var/www/app/public/storage
networks:
- internal
db:
image: mysql:8.0
restart: unless-stopped
command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
environment:
MYSQL_DATABASE: ${MYSQL_DATABASE}
MYSQL_USER: ${MYSQL_USER}
MYSQL_PASSWORD: ${MYSQL_PASSWORD}
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
TZ: ${TZ}
volumes:
- ./data/mysql:/var/lib/mysql
healthcheck:
test: ["CMD-SHELL", "mysqladmin ping -h localhost -uroot -p$${MYSQL_ROOT_PASSWORD}"]
interval: 10s
timeout: 5s
retries: 20
networks:
- internal
redis:
image: redis:7-alpine
restart: unless-stopped
command: ["redis-server", "--appendonly", "yes"]
volumes:
- ./data/redis:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 10
networks:
- internal
caddy:
image: caddy:2
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./config/Caddyfile:/etc/caddy/Caddyfile:ro
- ./caddy/data:/data
- ./caddy/config:/config
depends_on:
- app
networks:
- internal
volumes:
app_storage:
app_public_storage:
networks:
internal:
driver: bridge
Conviene fijar las etiquetas de las imágenes después de realizar pruebas satisfactorias. Antes de actualizar, guarde la etiqueta actual y haga una copia de seguridad. No elimine los Docker volumes con el comando docker compose down -v si no desea destruir los datos.
Paso 5. Inicio de la base de datos y la aplicación
# Проверяем синтаксис Compose и подстановку переменных
docker compose config
# Загружаем образы и создаём контейнеры
docker compose pull
# Запускаем MySQL, Redis, Invoice Ninja, worker и scheduler
docker compose up -d
# Смотрим состояние всех сервисов
docker compose ps
El primer inicio puede tardar varios minutos. MySQL primero crea las tablas del sistema, después de lo cual Docker Compose marca el servicio como healthy.
Paso 6. Comprobación de migraciones y registros
# Просматриваем последние сообщения приложения
docker compose logs --tail=100 app
# Проверяем состояние базы данных и Redis
docker compose ps db redis
# При необходимости запускаем миграции вручную
docker compose exec app php artisan migrate --force
# Очищаем кэш конфигурации после изменения .env
docker compose exec app php artisan optimize:clear
Si la aplicación informa de que falta la clave de cifrado, compruebe que en .env se haya definido un APP_KEY válido. No genere una clave nueva en una instalación ya operativa: los datos cifrados antiguos podrían quedar inaccesibles.