Instalación de Vikunja en un VPS: gestor de tareas autohospedado con Docker, SSL y copias de seguridad

Qué configuramos y por qué

Vikunja es un gestor de tareas y proyectos de código abierto con interfaz web, listas de tareas, tableros kanban, etiquetas, plazos, tareas recurrentes, adjuntos, acceso compartido y API. Es adecuado para la planificación personal, pequeños equipos de desarrollo, procesos internos de empresas y trabajo en equipo sin transferir datos de trabajo a un servicio SaaS de terceros.

En estas instrucciones, Vikunja funcionará en Ubuntu Server 24.04 LTS. La arquitectura consta de cuatro contenedores: la API de Vikunja, el frontend web, PostgreSQL 17 y Caddy 2.10. Caddy acepta conexiones desde Internet, obtiene automáticamente un certificado TLS de Let’s Encrypt y redirige las solicitudes a Vikunja.

Tras completar la configuración, el servicio estará disponible en una dirección como https://tasks.example.com. Los usuarios podrán registrarse por sí mismos si esta función está habilitada, o el administrador podrá crear la primera cuenta y deshabilitar el registro público.

Resultado final

• Vikunja en Docker Compose sin instalar dependencias de la aplicación en el sistema.
• PostgreSQL con un usuario independiente y un Docker volume persistente.
• Dominio con HTTPS y renovación automática del certificado.
• Puertos internos cerrados: PostgreSQL y la API no son accesibles desde Internet.
• Archivo con secretos, excluido de Git y de copias de seguridad sin cifrar.
• Copia de seguridad diaria cifrada o remota de la base de datos y la configuración.

Self-hosted o servicio en la nube

La opción self-hosted requiere disciplina: hay que supervisar las actualizaciones, comprobar las copias de seguridad y proteger el acceso SSH. A cambio, obtiene independencia de los planes de precios, los límites de usuarios y los cambios repentinos en las condiciones de un producto en la nube.

Qué configuración de VPS se necesita para esta tarea

Vikunja consume pocos recursos por sí mismo. PostgreSQL utiliza la mayor parte de la memoria, mientras que el espacio en disco se destina a la base de datos, archivos adjuntos, imágenes de Docker, registros y copias de seguridad. No se necesita un servidor potente para empezar, pero un VPS demasiado pequeño causará problemas al actualizar imágenes y crear volcados de la base de datos.

Una opción inicial práctica es 2 vCPU, 2 GB de RAM, 40 GB NVMe y una dirección IPv4 pública. Esta configuración es suficiente para Vikunja, PostgreSQL, Caddy, una copia de seguridad diaria y varias decenas de usuarios activos. Por ejemplo, puede elegir un VPS con las características indicadas o un servidor similar de otro proveedor.

Cuándo se necesitará más memoria

Aumente la RAM a 4–8 GB si en el mismo host se ejecutan un servidor Git, Mattermost, monitorización, runners de CI u otros contenedores. PostgreSQL puede utilizar la caché de archivos de Linux, por lo que la memoria adicional suele tener un efecto más notable que un mayor número de vCPU.

Cuándo se necesita un dedicado en lugar de un VPS

Para una instalación habitual de Vikunja no se necesita un servidor dedicado. Se justifica si almacena cientos de gigabytes de adjuntos, atiende a cientos de usuarios activos, ejecuta varios servicios pesados en un mismo host o necesita IOPS garantizados y CPU dedicadas. En la mayoría de los casos, es más sencillo comenzar con un VPS y ampliar el plan sin migrar la aplicación.

Cómo elegir la ubicación

Elija un centro de datos más cercano al equipo principal: esto reducirá la latencia al abrir la interfaz y cargar adjuntos. Si los requisitos de tratamiento de datos personales son importantes, tenga en cuenta el país de alojamiento, el contrato con el proveedor y el lugar donde se almacenan las copias de seguridad. Es mejor mantener la copia de seguridad en otro centro de datos o con otro proveedor: un único fallo no debe destruir tanto los datos operativos como su copia.

Preparación del servidor

A continuación se asume un servidor limpio con Ubuntu Server 24.04 LTS y acceso como usuario root. Antes de la instalación, cree un registro DNS de tipo A que apunte a la dirección IPv4 del servidor. Los ejemplos utilizan el dominio tasks.example.com; sustitúyalo por el suyo.

Actualice el sistema

Primero instale las actualizaciones de seguridad actuales y las utilidades básicas.

apt update && apt upgrade -y
apt install -y curl ca-certificates gnupg ufw fail2ban unattended-upgrades nano

Reinicie el servidor si se actualizaron el kernel o las bibliotecas del sistema.

reboot

Cree un usuario independiente

No realice la administración diaria como root. Cree el usuario deploy, añádalo al grupo sudo y configure el acceso mediante clave SSH.

adduser deploy
usermod -aG sudo deploy
mkdir -p /home/deploy/.ssh
chmod 700 /home/deploy/.ssh
nano /home/deploy/.ssh/authorized_keys
chmod 600 /home/deploy/.ssh/authorized_keys
chown -R deploy:deploy /home/deploy/.ssh

Inserte su clave pública SSH en el archivo authorized_keys, por ejemplo el contenido de ~/.ssh/id_ed25519.pub en su equipo local. Compruebe la conexión en una segunda ventana de terminal sin cerrar la sesión root actual.

ssh deploy@SERVER_IP

Deshabilite el acceso por contraseña mediante SSH

Después de comprobar correctamente la clave, cree un archivo de configuración SSH independiente. Es más seguro que editar el archivo principal del paquete.

sudo nano /etc/ssh/sshd_config.d/99-hardening.conf

PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
X11Forwarding no
MaxAuthTries 3

Compruebe la sintaxis y reinicie el servicio SSH.

sudo sshd -t && sudo systemctl restart ssh

Configure el firewall

Solo deben permanecer abiertos SSH, HTTP y HTTPS. No exponga al exterior los puertos de PostgreSQL 5432, la API de Vikunja 3456 ni el frontend 80 dentro de Docker.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Habilite Fail2ban y las actualizaciones automáticas de seguridad

Fail2ban bloquea temporalmente direcciones IP después de intentos sospechosos de acceso SSH. Las actualizaciones automáticas corrigen vulnerabilidades conocidas de Ubuntu sin intervención manual.

sudo systemctl enable --now fail2ban
sudo dpkg-reconfigure -plow unattended-upgrades
sudo fail2ban-client status sshd

Antes de deshabilitar el acceso por contraseña, asegúrese de que la clave SSH funciona. La pérdida de la única clave privada sin acceso a la consola del proveedor puede bloquear la administración del servidor.

Instalación del software, paso a paso

Para el despliegue se utiliza Docker Engine 28.x o una versión estable más reciente, junto con el plugin Docker Compose. Es preferible fijar las imágenes de Vikunja a una etiqueta específica en lugar de utilizar latest: así, la actualización no se producirá accidentalmente en la siguiente ejecución.

Instale Docker desde el repositorio oficial

Elimine los paquetes que puedan entrar en conflicto si se instalaron desde el repositorio estándar de Ubuntu.

sudo apt remove -y docker.io docker-compose docker-compose-v2 podman-docker containerd runc || true

Añada la clave y el repositorio de 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

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

Instale Docker Engine, CLI, Buildx y el plugin Compose.

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker --version
sudo docker compose version

Añada el usuario deploy al grupo Docker. Después del comando, cierre la sesión SSH y vuelva a iniciarla para que se aplique el grupo.

sudo usermod -aG docker deploy
exit

Vuelva a conectarse y asegúrese de que Docker está disponible sin sudo.

ssh deploy@SERVER_IP
docker ps

Cree la estructura de trabajo

Todos los archivos del servicio se almacenarán en /opt/vikunja. El directorio será accesible para el usuario deploy, pero no estará abierto a otros usuarios locales.

sudo mkdir -p /opt/vikunja/{caddy,data,backups,scripts}
sudo chown -R deploy:deploy /opt/vikunja
chmod 750 /opt/vikunja
cd /opt/vikunja

Compruebe la disponibilidad del dominio

Antes de iniciar Caddy, el registro DNS ya debe apuntar al servidor. La comprobación desde el propio servidor mostrará qué dirección devuelve el DNS público.

getent ahostsv4 tasks.example.com

Si se muestra una IP distinta a la de su VPS, corrija el DNS y espere a que el registro se propague. Para emitir el certificado de Let’s Encrypt, los puertos entrantes 80 y 443 también deben estar disponibles.

Configuración de Vikunja, Docker y SSL

A continuación se utiliza la versión de Vikunja 0.24.6 como ejemplo de una etiqueta estable fijada. Antes del despliegue en producción, compruebe la versión estable actual en las release notes oficiales de Vikunja y sustituya el valor de la variable si es necesario. No utilice una etiqueta sin verificar solo porque sea más reciente: primero haga una copia de seguridad y pruebe la actualización.

Cree un archivo con variables de entorno

Genere dos secretos aleatorios: la contraseña de PostgreSQL y el secreto JWT de Vikunja. La contraseña no debe contener espacios ni caracteres que puedan ser interpretados incorrectamente por el shell.

cd /opt/vikunja
openssl rand -base64 32
openssl rand -hex 32

Cree el archivo .env e introduzca sus propios valores. El valor de VIKUNJA_SERVICE_PUBLICURL debe terminar obligatoriamente con una barra.

nano /opt/vikunja/.env
chmod 600 /opt/vikunja/.env

VIKUNJA_VERSION=0.24.6
POSTGRES_DB=vikunja
POSTGRES_USER=vikunja
POSTGRES_PASSWORD=CHANGE_TO_LONG_RANDOM_DATABASE_PASSWORD
VIKUNJA_SERVICE_JWTSECRET=CHANGE_TO_LONG_RANDOM_JWT_SECRET
VIKUNJA_SERVICE_PUBLICURL=https://tasks.example.com/
VIKUNJA_SERVICE_ENABLEREGISTRATION=true
VIKUNJA_SERVICE_TIMEZONE=Europe/Moscow
VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE=20971520
DOMAIN=tasks.example.com

El parámetro VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE se establece en bytes y limita el tamaño de un archivo adjunto a 20 MB. Para archivos más grandes, aumente el límite y tenga en cuenta el espacio libre en disco. Después de crear el primer administrador, normalmente se desactiva el registro público.

Cree el archivo Docker Compose

El archivo Compose crea una red aislada. Solo los puertos de Caddy se publican en Internet; PostgreSQL, la API y el frontend solo están disponibles para los contenedores dentro de la red.

nano /opt/vikunja/compose.yaml

services:
  db:
    image: postgres:17-alpine
    container_name: vikunja-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 10
    networks:
      - vikunja

  api:
    image: vikunja/api:${VIKUNJA_VERSION}
    container_name: vikunja-api
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: ${POSTGRES_USER}
      VIKUNJA_DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
      VIKUNJA_DATABASE_DATABASE: ${POSTGRES_DB}
      VIKUNJA_DATABASE_SSLMODE: disable
      VIKUNJA_SERVICE_JWTSECRET: ${VIKUNJA_SERVICE_JWTSECRET}
      VIKUNJA_SERVICE_PUBLICURL: ${VIKUNJA_SERVICE_PUBLICURL}
      VIKUNJA_SERVICE_ENABLEREGISTRATION: ${VIKUNJA_SERVICE_ENABLEREGISTRATION}
      VIKUNJA_SERVICE_TIMEZONE: ${VIKUNJA_SERVICE_TIMEZONE}
      VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE: ${VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE}
    volumes:
      - vikunja_files:/app/vikunja/files
    networks:
      - vikunja

  frontend:
    image: vikunja/frontend:${VIKUNJA_VERSION}
    container_name: vikunja-frontend
    restart: unless-stopped
    depends_on:
      - api
    networks:
      - vikunja

  caddy:
    image: caddy:2.10-alpine
    container_name: vikunja-caddy
    restart: unless-stopped
    depends_on:
      - frontend
      - api
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    environment:
      DOMAIN: ${DOMAIN}
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - vikunja

networks:
  vikunja:
    name: vikunja-network

volumes:
  postgres_data:
  vikunja_files:
  caddy_data:
  caddy_config:

Configure Caddy

Caddy solicitará automáticamente un certificado de Let’s Encrypt, lo renovará y redirigirá el tráfico HTTP a HTTPS. El frontend recibe solicitudes normales, mientras que las solicitudes de la API con el prefijo /api/ se dirigen al contenedor de la API de Vikunja.

nano /opt/vikunja/caddy/Caddyfile

{$DOMAIN} {
    encode zstd gzip

    @api path /api/
    reverse_proxy @api api:3456

    reverse_proxy frontend:80

    header {
        -Server
        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 stdout
        format console
    }
}

cd /opt/vikunja
docker compose config --quiet

cd /opt/vikunja
docker compose pull
docker compose up -d
docker compose ps

docker compose logs --tail=100 api
docker compose logs --tail=100 caddy

curl -I https://tasks.example.com
curl -fsS https://tasks.example.com/api/v1/info

sed -i 's/VIKUNJA_SERVICE_ENABLEREGISTRATION=true/VIKUNJA_SERVICE_ENABLEREGISTRATION=false/' /opt/vikunja/.env
cd /opt/vikunja
docker compose up -d --force-recreate api

sudo apt update
sudo apt install -y restic

nano /opt/vikunja/.restic-env
chmod 600 /opt/vikunja/.restic-env

export RESTIC_REPOSITORY="s3:https://s3.example.net/vikunja-backups"
export RESTIC_PASSWORD="CHANGE_TO_A_LONG_UNIQUE_BACKUP_PASSWORD"
export AWS_ACCESS_KEY_ID="S3_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="S3_SECRET_KEY"

source /opt/vikunja/.restic-env
restic init

nano /opt/vikunja/scripts/backup.sh
chmod 700 /opt/vikunja/scripts/backup.sh

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="/opt/vikunja"
BACKUP_DIR="${APP_DIR}/backups"
DATE="$(date +%F_%H-%M-%S)"

source "${APP_DIR}/.restic-env"
mkdir -p "${BACKUP_DIR}"

cd "${APP_DIR}"

docker compose exec -T db pg_dump \
  -U "${POSTGRES_USER}" \
  -d "${POSTGRES_DB}" \
  -Fc > "${BACKUP_DIR}/vikunja_${DATE}.dump"

docker run --rm \
  -v vikunja_vikunja_files:/source:ro \
  -v "${BACKUP_DIR}:/backup" \
  alpine:3.21 \
  tar -czf "/backup/vikunja_files_${DATE}.tar.gz" -C /source .

restic backup \
  "${BACKUP_DIR}/vikunja_${DATE}.dump" \
  "${BACKUP_DIR}/vikunja_files_${DATE}.tar.gz" \
  "${APP_DIR}/compose.yaml" \
  "${APP_DIR}/.env" \
  "${APP_DIR}/caddy/Caddyfile"

restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune

rm -f "${BACKUP_DIR}/vikunja_${DATE}.dump"
rm -f "${BACKUP_DIR}/vikunja_files_${DATE}.tar.gz"

/opt/vikunja/scripts/backup.sh
source /opt/vikunja/.restic-env
restic snapshots

crontab -e

30 3    /opt/vikunja/scripts/backup.sh >> /opt/vikunja/backups/backup.log 2>&1

Comprobación de restauración

Al menos una vez por trimestre, restaure una copia de seguridad en un VPS de prueba o en un directorio independiente. La existencia de snapshots no garantiza que la contraseña del repositorio se haya conservado, que el archivo no esté dañado ni que el procedimiento de restauración sea claro en una situación de emergencia.

source /opt/vikunja/.restic-env
restic restore latest --target /tmp/vikunja-restore-test
find /tmp/vikunja-restore-test -type f | head

Plan de actualización

Para una instalación pequeña, actualice Vikunja durante una ventana de mantenimiento cada 1–2 meses. Primero cree una copia de seguridad, lea el changelog de la versión objetivo, cambie VIKUNJA_VERSION en .env, descargue las imágenes y vuelva a crear los contenedores. No cambie la versión major de PostgreSQL simplemente modificando la etiqueta: requiere un procedimiento independiente de migración de datos.

cd /opt/vikunja
/opt/vikunja/scripts/backup.sh
nano .env
docker compose pull
docker compose up -d
docker compose logs --tail=100 api
curl -fsS https://tasks.example.com/api/v1/info

Una actualización continua tiene sentido con varias instancias de la API y una base de datos independiente. Para un solo VPS, basta con una interrupción breve y controlada: normalmente la interfaz no está disponible durante menos de un minuto y el riesgo de una actualización incorrecta es menor.

Resolución de problemas y FAQ

¿Por qué Caddy no obtiene un certificado SSL?

Compruebe que el registro DNS A del dominio apunte a la IP pública del servidor y que los puertos 80 y 443 estén permitidos en UFW y en el firewall de red del proveedor. Consulte el registro con el comando docker compose logs caddy. Una causa frecuente es que el dominio se proxifique mediante una CDN con un modo SSL inadecuado o que exista un registro AAAA IPv6 que apunte a otro servidor. Si IPv6 no está configurado, elimine el registro AAAA incorrecto.

¿Por qué se abre la interfaz, pero la API devuelve 502 Bad Gateway?

El código 502 significa que Caddy no puede conectarse al contenedor de la API. Compruebe los estados mediante docker compose ps y el registro con docker compose logs api. Normalmente, la API no se inicia debido a una contraseña de PostgreSQL incorrecta, un JWT-secret ausente o una inicialización de la base de datos incompleta. Asegúrese también de que Caddyfile especifique la dirección api:3456 y no localhost: los contenedores utilizan la red interna de Docker.

¿Por qué Vikunja muestra un error de conexión a PostgreSQL?

Primero ejecute docker compose logs db y asegúrese de que el contenedor de la base de datos tenga el estado healthy. Si la contraseña POSTGRES_PASSWORD se modificó después del primer inicio de PostgreSQL, la base de datos seguirá utilizando la contraseña anterior del volume existente. Restaure la contraseña anterior o cree manualmente un nuevo usuario dentro de PostgreSQL. No elimine el volume de la base de datos como forma de «corregir» el error: esto eliminará todas las tareas y usuarios.

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

Para una persona o varios usuarios, bastan como mínimo 1 vCPU, 1 GB de RAM y 25 GB de SSD. Sin embargo, una configuración más práctica es 2 vCPU, 2 GB de RAM y 40 GB de NVMe: permite realizar con mayor comodidad actualizaciones de Docker, crear archivos y conservar varios días de copias de seguridad temporales locales. Si se prevén archivos adjuntos grandes, aumente primero el disco y después la memoria.

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

Para Vikunja, un VPS casi siempre es suficiente. La aplicación no requiere un servidor físico dedicado si la utiliza un equipo normal de hasta cien personas. Un dedicated tiene sentido con requisitos elevados de rendimiento de disco, un gran volumen de archivos, alojamiento conjunto de servicios pesados o necesidad de recursos dedicados garantizados. Empezar con un VPS es más sencillo, económico y normalmente más seguro desde el punto de vista de la administración.

¿Por qué después de una actualización el frontend muestra una versión antigua o una página en blanco?

Primero borre la caché del navegador o abra el servicio en una ventana privada: el frontend es una aplicación estática y puede quedar almacenado en caché. Después, compruebe que la API y el frontend utilicen etiquetas compatibles de Vikunja en .env. No actualice solo una de las dos imágenes. Consulte los registros del frontend y de Caddy, y luego ejecute docker compose pull && docker compose up -d.

¿Cómo aumentar el tamaño permitido de los archivos adjuntos?

Modifique el parámetro VIKUNJA_SERVICE_MAXIMUMATTACHMENTSIZE en el archivo .env. El valor se indica en bytes: por ejemplo, 104857600 corresponde a 100 MB. Después del cambio, vuelva a crear el contenedor de la API con el comando docker compose up -d --force-recreate api. Compruebe el espacio libre mediante df -h; los archivos adjuntos grandes aumentan rápidamente el tamaño del Docker volume y el tiempo de copia de seguridad.

¿Se puede migrar Vikunja a otro servidor?

Sí. En el nuevo servidor, instale Docker, cree el directorio /opt/vikunja, restaure compose.yaml, .env y Caddyfile. Después, restaure el volcado de PostgreSQL en la nueva base de datos y descomprima el archivo de archivos en el volume vikunja_vikunja_files. Tras cambiar el DNS, compruebe el inicio de sesión, los proyectos y los archivos adjuntos. Durante la migración, es mejor detener el servicio antiguo para no perder tareas creadas después de la copia de seguridad final.

Conclusiones y próximos pasos

Ahora Vikunja funciona en un VPS dentro de contenedores Docker aislados, está disponible mediante HTTPS y protegido por reglas básicas de firewall. Los datos de las tareas se encuentran en PostgreSQL, y los archivos adjuntos y la configuración están incluidos en el plan de copias de seguridad.

1. Cree proyectos de prueba, configure los permisos de los equipos y desactive el registro público si no lo necesita.
2. Pruebe la restauración de una copia de seguridad en una máquina independiente antes de que el servicio se vuelva crítico para el trabajo.
3. A medida que crezca el equipo, traslade las copias de seguridad a un almacenamiento independiente, configure la supervisión del espacio libre y las actualizaciones programadas.