eco Principiante Tutorial/Cómo hacer

Instalación de Invoice Ninja en un VPS: Docker, SSL, SMTP, cron y copias de seguridad

Ganamos comisiones cuando compras a través de los enlaces de esta página.

calendar_month Oct 29, 2026 schedule 19 min de lectura visibility 588 vistas
Установка Invoice Ninja на VPS: Docker, SSL, SMTP, cron и бэкапы
dns ¿No tienes servidor para esta guía? Vultr, DigitalOcean, Contabo

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.

  1. Definición de requisitos y arquitectura.
  2. Preparación del VPS y del acceso SSH.
  3. Instalación de Docker Engine y Compose.
  4. Creación de la configuración de Docker Compose.
  5. Configuración del dominio, Caddy y TLS.
  6. Conexión de SMTP y tareas en segundo plano.
  7. Configuración de las copias de seguridad.
  8. 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.

7. Configuración

DNS y nombre de dominio

Antes de iniciar Caddy, cree un registro A del dominio que apunte a la dirección IPv4 del VPS. Si utiliza IPv6, añada un registro AAAA solo después de comprobar que el servidor realmente está disponible mediante IPv6 y que el firewall está configurado para este protocolo.

# Проверяем, куда указывает домен
dig +short billing.example.com A
dig +short billing.example.com AAAA

El resultado esperado para el registro A es la dirección pública del VPS. Si el DNS aún no se ha actualizado, Caddy no podrá superar el challenge HTTP-01 ni obtener el certificado.

Configuración de Caddy

# Создаём конфигурацию reverse proxy
cat > /opt/invoiceninja/config/Caddyfile <<'EOF'
billing.example.com {
    encode gzip zstd

    reverse_proxy app:80

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "SAMEORIGIN"
        Referrer-Policy "strict-origin-when-cross-origin"
    }

    log {
        output file /data/access.log
        format json
    }
}
EOF

# Перезапускаем Caddy с новым доменом
docker compose up -d caddy

# Просматриваем получение сертификата
docker compose logs -f caddy

Caddy crea automáticamente el certificado mediante ACME y lo guarda en el directorio /opt/invoiceninja/caddy/data. Incluya siempre este directorio en las copias de seguridad o prepárese para obtener el certificado de nuevo durante la restauración.

Comprobación de HTTPS

# Проверяем HTTP-заголовки и TLS-ответ
curl -I https://billing.example.com

# Проверяем редирект или доступность HTTP
curl -I http://billing.example.com

# Проверяем, что приложение отвечает через локальный Docker DNS
docker compose exec caddy wget -qO- http://app/ | head

El comando curl debe recibir una respuesta de Caddy sin errores de certificado. Son aceptables los códigos 200, 302 o la página de inicio de sesión. Un error 502 significa que Caddy funciona, pero no puede conectarse al contenedor de la aplicación.

SMTP

Para enviar correos, utilice un proveedor SMTP con el puerto 587 y STARTTLS, o el puerto 465 con TLS si su servicio lo admite explícitamente. En la mayoría de los casos, el puerto 587 con MAIL_ENCRYPTION=tls es la opción más compatible.

# Открываем переменные окружения
nano /opt/invoiceninja/.env
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.net
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=длинный-пароль-или-app-password
MAIL_ENCRYPTION=tls
[email protected]
MAIL_FROM_NAME=Billing
# Пересоздаём контейнеры, чтобы они получили новые переменные
docker compose up -d --force-recreate app worker scheduler

# Очищаем кэш конфигурации приложения
docker compose exec app php artisan optimize:clear

# Проверяем логи приложения после тестовой отправки
docker compose logs --tail=100 app worker

Si el proveedor SMTP requiere una contraseña de aplicación independiente, utilice precisamente esa. La contraseña habitual del buzón puede estar prohibida por la política de seguridad. Compruebe también SPF, DKIM y DMARC del dominio del remitente; de lo contrario, los mensajes podrían terminar en la carpeta de spam.

Tareas en segundo plano y cron

En Compose se ejecutan dos servicios independientes. worker procesa la cola, mientras que scheduler ejecuta el planificador de Laravel cada minuto. Esto es preferible a utilizar un único cron dentro del contenedor: los procesos tienen registros independientes y Docker los reinicia automáticamente.

# Проверяем, что worker и scheduler запущены
docker compose ps worker scheduler

# Смотрим обработку очереди
docker compose logs --tail=100 worker

# Проверяем Redis
docker compose exec redis redis-cli ping

La respuesta PONG confirma que Redis está disponible. Si worker se reinicia constantemente, compruebe primero la conexión con MySQL, el valor de APP_KEY y los registros del contenedor.

Comprobación del estado de Docker

# Показываем контейнеры и их health status
docker compose ps

# Проверяем занятое место на диске
df -h

# Проверяем потребление ресурсов контейнерами
docker stats --no-stream

# Проверяем открытые TCP-порты на сервере
sudo ss -tulpn

En la lista de puertos públicos deben aparecer SSH, HTTP y HTTPS. MySQL y Redis no deben escuchar en la dirección del host. Si ve 0.0.0.0:3306 o 0.0.0.0:6379, compruebe el archivo Compose y elimine la publicación de estos puertos.

8. Copias de seguridad y mantenimiento

Qué es necesario guardar

Para restaurar completamente Invoice Ninja no basta con guardar la base de datos. La base contiene clientes, facturas y configuraciones, pero los logotipos cargados, los archivos adjuntos y los archivos generados se encuentran en Docker volumes.

  • Volcado de MySQL.
  • Volumen app_storage.
  • Volumen app_public_storage.
  • Archivo .env.
  • Archivo compose.yml.
  • Archivo Caddyfile.
  • Directorio de Caddy con los datos de ACME.

Una copia de seguridad en el mismo VPS no constituye una protección completa. Si se elimina el servidor, falla el disco o se compromete root, un atacante también puede eliminar las copias locales. Utilice un storage externo compatible con S3, un VPS separado o un almacenamiento de objetos con versioning y políticas de lifecycle.

Instalación y configuración de Restic

Restic cifra los datos antes de enviarlos al almacenamiento remoto. No se debe perder la contraseña del repositorio: sin ella es imposible restaurar los archivos. Guárdela por separado del servidor, por ejemplo, en un gestor de secretos.

# Инициализируем репозиторий Restic в S3
cd /opt/invoiceninja
set -a
. ./.env
set +a
restic init

El comando solicitará la contraseña si la variable RESTIC_PASSWORD no se ha pasado al entorno. Asegúrese de que la ruta S3 sea correcta para su proveedor.

Script de copia de seguridad

# Создаём каталог временных файлов
mkdir -p /opt/invoiceninja/backups/tmp

# Создаём скрипт резервного копирования
cat > /opt/invoiceninja/backup.sh <<'EOF'
#!/usr/bin/env bash
set -Eeuo pipefail

PROJECT="/opt/invoiceninja"
TMP="${PROJECT}/backups/tmp"
STAMP="$(date -u +%Y-%m-%d_%H-%M-%S)"

cd "$PROJECT"
set -a
. "$PROJECT/.env"
set +a

mkdir -p "$TMP/$STAMP"

echo "[$(date -Is)] Creating MySQL dump"
docker compose exec -T db sh -c \
  'exec mysqldump --single-transaction --quick --routines --triggers \
  -uroot -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE"' \
  > "$TMP/$STAMP/mysql.sql"

echo "[$(date -Is)] Archiving application files"
tar -czf "$TMP/$STAMP/application.tar.gz" \
  .env compose.yml config/Caddyfile \
  caddy/data caddy/config \
  "$(docker volume inspect --format '{{.Mountpoint}}' invoiceninja_app_storage)" \
  "$(docker volume inspect --format '{{.Mountpoint}}' invoiceninja_app_public_storage)"

echo "[$(date -Is)] Uploading encrypted snapshot"
restic backup "$TMP/$STAMP" --tag invoiceninja

echo "[$(date -Is)] Removing temporary files"
rm -rf "$TMP/$STAMP"

echo "[$(date -Is)] Applying retention policy"
restic forget --tag invoiceninja \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  --prune

echo "[$(date -Is)] Backup completed"
EOF

# Делаем скрипт исполняемым
chmod 700 /opt/invoiceninja/backup.sh

Los nombres de Docker volumes dependen del nombre del proyecto Compose. Si se ha cambiado el nombre del directorio del proyecto, el comando docker volume inspect puede devolver otro nombre. Compruébelo de antemano:

# Показываем реальные имена томов
docker volume ls | grep invoiceninja

Si el nombre es diferente, sustitúyalo en el script. Antes de utilizarlo en cron, ejecute manualmente la copia de seguridad.

# Выполняем первый полный бэкап
sudo -u deploy /opt/invoiceninja/backup.sh

# Проверяем список snapshot в удалённом репозитории
cd /opt/invoiceninja
set -a
. ./.env
set +a
restic snapshots

Ejecución mediante cron

# Открываем cron пользователя deploy
crontab -e
# Ежедневный бэкап в 03:15 UTC
15 3    /opt/invoiceninja/backup.sh >> /opt/invoiceninja/backups/backup.log 2>&1

Elija la hora teniendo en cuenta la zona horaria y la carga. Para una facturación crítica, puede realizar copias adicionales antes de actualizar. El registro de cron también debe limitarse por tamaño o limpiarse periódicamente.

Comprobación de la restauración

Una copia de seguridad que nunca se ha restaurado no puede considerarse verificada. La prueba mínima consiste en descargar el último snapshot en una máquina de pruebas independiente y comprobar que el volcado SQL se abre y que los archivos de usuario están presentes.

# Просматриваем содержимое последнего snapshot
restic snapshots

# Восстанавливаем последний snapshot во временный каталог
mkdir -p /tmp/invoiceninja-restore
restic restore latest --target /tmp/invoiceninja-restore

# Проверяем SQL-файл
ls -lh /tmp/invoiceninja-restore
head -n 20 /tmp/invoiceninja-restore//mysql.sql

Realice la restauración completa en un servidor nuevo: instale Docker, restaure .env, despliegue el archivo Compose, importe la base de datos y copie los datos en los volúmenes. No experimente con la restauración de la única instalación en funcionamiento.

Actualizaciones

Antes de actualizar, cree un snapshot y registre las versiones actuales de las imágenes:

# Сохраняем конфигурацию перед обновлением
cd /opt/invoiceninja
docker compose config > compose-resolved-before-update.yml
./backup.sh

# Загружаем новые образы
docker compose pull

# Пересоздаём контейнеры без удаления volumes
docker compose up -d

# Проверяем логи после обновления
docker compose logs --tail=200 app worker scheduler

Para un proyecto pequeño basta con una breve ventana de mantenimiento. Antes de una actualización importante, pruebe primero la nueva etiqueta en una copia independiente. No actualice Ubuntu, Docker, MySQL e Invoice Ninja simultáneamente sin necesidad: en caso de error será más difícil determinar la causa.

Es posible realizar una actualización Rolling de varias instancias de la aplicación, pero normalmente no es necesario en un VPS pequeño. Con una sola instancia, es más seguro programar unos minutos de indisponibilidad y comprobar las migraciones, el inicio de sesión, la creación de PDF y el envío de correos.

Control mensual

  • Compruebe el espacio disponible con el comando df -h.
  • Elimine las imágenes antiguas de Docker después de comprobar la actualización.
  • Compruebe que cron se ejecuta correctamente y la fecha del último snapshot de Restic.
  • Compruebe la validez del certificado TLS.
  • Pruebe el envío de correos y la generación de PDF.
  • Revise los registros de Caddy, de la aplicación y de worker.
  • Actualice Ubuntu y Docker durante la ventana acordada.
# Удаляем неиспользуемые образы, но не volumes
docker image prune -f

# Проверяем состояние служб ОС
systemctl --failed

# Проверяем дату последней резервной копии
restic snapshots --tag invoiceninja

9. Troubleshooting y preguntas frecuentes

¿Por qué Caddy devuelve 502 Bad Gateway?

Primero compruebe docker compose ps y los registros con el comando docker compose logs app caddy. El código 502 suele indicar que el contenedor de la aplicación no está iniciado, que todavía está ejecutando migraciones o que Caddy utiliza un nombre de servicio incorrecto. En Caddyfile debe aparecer la dirección app:80, y ambos contenedores deben estar en la misma red de Docker. Compruebe también que la aplicación no se haya detenido debido a un APP_KEY o a unos parámetros de base de datos incorrectos.

El certificado HTTPS no se emite. ¿Qué se debe comprobar?

Asegúrese de que el registro DNS A apunte a este VPS y de que los puertos 80 y 443 estén permitidos en UFW y en el firewall externo del proveedor. Caddy debe recibir las solicitudes entrantes directamente, sin un modo CDN cerrado ni un NAT incorrecto. Consulte los registros con docker compose logs caddy. Si el dominio aún no se ha delegado o conserva un registro AAAA antiguo, la comprobación ACME puede llegar a otro servidor.

¿Qué configuración mínima de VPS es adecuada?

Para una instalación pequeña basta con 2 vCPU, 4 GB de RAM y 40 GB de SSD. Esta opción es adecuada para varios usuarios y un número moderado de facturas, pero no deja mucho margen para otros servicios. Un mínimo más práctico es 4 vCPU, 8 GB de RAM y 80 GB de NVMe. Elija el disco teniendo en cuenta los PDF, los archivos adjuntos, los registros y el espacio temporal local, aunque las copias principales estén en S3.

¿Qué elegir: VPS o dedicated para esta tarea?

Para un Invoice Ninja o una empresa pequeña, elija un VPS: es más económico, escala con mayor facilidad y normalmente ofrece recursos suficientes. Un dedicated está justificado con una carga alta constante, un gran número de tareas PDF simultáneas, varias aplicaciones en el mismo servidor o requisitos de hardware dedicado. Antes de cambiar, mida la RAM, la CPU y el I/O del disco. Si el único cuello de botella es el disco, a veces basta con un VPS con NVMe más rápido.

Los correos no se envían aunque los datos SMTP sean correctos

Compruebe el puerto, el tipo de cifrado y los requisitos del proveedor SMTP. Para el puerto 587 normalmente se utiliza MAIL_ENCRYPTION=tls, mientras que para el 465 la configuración puede ser diferente. Después de modificar .env, vuelva a crear los contenedores y ejecute php artisan optimize:clear. Consulte los registros de worker: el correo puede estar en la cola, pero no procesarse. Compruebe también que el proveedor permita la dirección del remitente y que tenga registros SPF/DKIM correctos.

Worker se reinicia constantemente

Ejecute docker compose logs --tail=200 worker. Las causas frecuentes son una base de datos inaccesible, una contraseña de MySQL incorrecta, la ausencia de APP_KEY o un Redis configurado incorrectamente. Compruebe docker compose exec redis redis-cli ping y el estado de la base mediante docker compose ps db. Después de corregir el entorno, ejecute docker compose up -d --force-recreate worker. No elimine los volúmenes para intentar corregir un error normal de configuración.

Se está agotando el espacio del disco

Primero busque los directorios grandes con los comandos df -h, du -xh /opt/invoiceninja | sort -h | tail y docker system df. Compruebe los registros de Caddy y Docker, el directorio local de copias temporales y el tamaño de los archivos adjuntos de los usuarios. No elimine manualmente archivos de MySQL. Las imágenes antiguas pueden eliminarse mediante docker image prune, y el periodo de conservación de Restic puede configurarse con la política forget. Si los datos siguen creciendo, aumente el disco con antelación.

¿Cómo recuperar el acceso después de un error de configuración?

Si los contenedores se inician, restaure el último .env y el archivo Compose funcionales desde la copia de seguridad cifrada, ejecute después docker compose config y reinicie los servicios. Si el problema apareció después de actualizar la imagen, vuelva a la etiqueta comprobada anterior. No genere un nuevo APP_KEY ni elimine la base de datos: esto puede hacer que los datos cifrados y los registros de usuario sean inaccesibles.

¿Es necesario ejecutar un cron independiente del sistema para Invoice Ninja?

En este esquema no se necesita un cron independiente para la aplicación: el contenedor scheduler ejecuta php artisan schedule:run cada minuto, y worker procesa la cola. El cron del sistema se utiliza únicamente para las copias de seguridad. Si scheduler se detiene, compruebe su estado y sus registros. En production es mejor mantener worker y scheduler como servicios independientes para poder reiniciarlos sin depender de la aplicación web.

10. Conclusiones y siguientes pasos

Como resultado, Invoice Ninja funciona en un VPS con Docker: la aplicación está separada de MySQL y Redis, Caddy se encarga de HTTPS, SMTP gestiona el envío de documentos y una copia diaria de Restic protege la base de datos y los archivos de usuario.

A continuación conviene añadir la supervisión del espacio disponible y de la disponibilidad de HTTPS, probar periódicamente la restauración y actualizar las imágenes durante una ventana de mantenimiento independiente. Si aumenta la carga, mida la cola, el I/O del disco y el consumo de memoria; después puede trasladar MySQL o Redis a un servidor independiente, añadir réplicas de la aplicación y conectar un storage externo de objetos para los archivos.

Enlaces de afiliado: podemos recibir una comisión, el precio para ti no cambia.

¿Te fue útil esta guía?

Tus comentarios nos ayudan a mejorar nuestras guías.

Compartir esta publicación:

Envía esta guía a alguien a quien pueda resultarle útil.

Telegram VKVK WhatsApp Facebook LinkedIn XX

instalación de Invoice Ninja en VPS: Docker, SSL, SMTP, cron y copias de seguridad