---
title: "Cómo instalar Vikunja con Docker en Ubuntu 24.04"
description: "Instala el gestor de tareas Vikunja con Docker Compose y PostgreSQL en Ubuntu 24.04, publícalo con Nginx y HTTPS y conecta CalDAV y la API REST con tokens."
category: "Productividad Self-Hosted"
language: es
source: https://cubepath.com/es/docs/productividad-self-hosted/instalacion-de-vikunja-gestion-de-tareas
updated: 2026-09-25
---

# Cómo instalar Vikunja con Docker en Ubuntu 24.04

Vikunja es una aplicación de código abierto para gestionar tareas y proyectos, con vistas de lista, tablero Kanban, tabla y Gantt, sincronización por CalDAV y una API REST completa. Es una alternativa autoalojada a Todoist o Trello. En esta guía desplegarás Vikunja con Docker Compose y PostgreSQL en Ubuntu 24.04, lo publicarás con Nginx y un certificado de Let's Encrypt, cerrarás el registro público y comprobarás la API y CalDAV.

## Requisitos previos

- Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 1 GB de RAM.
- Un usuario no root con privilegios `sudo`.
- Docker Engine y el plugin Docker Compose instalados desde el repositorio oficial de Docker.
- Un subdominio, por ejemplo `tareas.tu_dominio.com`, con un registro DNS `A` apuntando a la IP pública del servidor.
- Los puertos 80 y 443 accesibles desde Internet.

Sustituye `tareas.tu_dominio.com` por tu subdominio real.

## Paso 1: Preparar directorios y secretos

Desde la versión 0.24, la imagen `vikunja/vikunja` incluye la API y la interfaz web en un solo contenedor que escucha en el puerto 3456. Crea el directorio del despliegue y los subdirectorios para adjuntos y base de datos:

```bash
sudo mkdir -p /opt/vikunja/files /opt/vikunja/db
cd /opt/vikunja
```

El proceso de Vikunja se ejecuta con el UID 1000 dentro del contenedor, así que el directorio de adjuntos debe pertenecer a ese UID:

```bash
sudo chown 1000 /opt/vikunja/files
```

Genera dos valores aleatorios, uno para la contraseña de PostgreSQL y otro para el secreto con el que Vikunja firma los tokens de sesión:

```bash
openssl rand -hex 24
openssl rand -hex 32
```

Guárdalos en un archivo `.env` junto al archivo de Compose:

```bash
sudo nano /opt/vikunja/.env
```

```ini
DB_PASSWORD=primer_valor_generado
JWT_SECRET=segundo_valor_generado
PUBLIC_URL=https://tareas.tu_dominio.com/
```

```bash
sudo chmod 600 /opt/vikunja/.env
```

El secreto JWT debe mantenerse estable: si cambia, todas las sesiones abiertas dejan de ser válidas.

## Paso 2: Crear el archivo de Docker Compose

```bash
sudo nano /opt/vikunja/docker-compose.yml
```

```yaml
services:
  vikunja:
    image: vikunja/vikunja:latest
    container_name: vikunja
    restart: unless-stopped
    ports:
      - "127.0.0.1:3456:3456"
    environment:
      VIKUNJA_SERVICE_PUBLICURL: ${PUBLIC_URL}
      VIKUNJA_SERVICE_JWTSECRET: ${JWT_SECRET}
      VIKUNJA_SERVICE_TIMEZONE: Europe/Madrid
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "true"
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: ${DB_PASSWORD}
      VIKUNJA_DATABASE_DATABASE: vikunja
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    container_name: vikunja-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: vikunja
    volumes:
      - ./db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
      interval: 5s
      start_period: 30s
```

Algunos detalles importantes:

- `VIKUNJA_SERVICE_PUBLICURL` debe ser la URL pública final, con barra al final. Vikunja la usa para los enlaces de los correos y para CalDAV.
- El registro queda abierto de momento para que puedas crear tu cuenta; lo cerrarás en el Paso 5.
- La imagen de PostgreSQL se fija en la versión 17. Las versiones mayores de PostgreSQL no pueden abrir directamente un directorio de datos de otra versión, así que conviene no usar `latest`.
- El puerto se publica solo en `127.0.0.1`: el acceso público lo dará Nginx.

## Paso 3: Arrancar Vikunja

```bash
sudo docker compose up -d
```

Comprueba que los dos contenedores están en marcha y que la base de datos aparece como sana:

```bash
sudo docker compose ps
```

```output
NAME         IMAGE                    STATUS
vikunja      vikunja/vikunja:latest   Up 20 seconds
vikunja-db   postgres:17              Up 26 seconds (healthy)
```

El endpoint `/api/v1/info` devuelve la versión y la configuración pública del servidor, y sirve para confirmar que la API responde:

```bash
curl -s http://127.0.0.1:3456/api/v1/info
```

```output
{"version":"v1.0.0","frontend_url":"https://tareas.tu_dominio.com/","motd":"","link_sharing_enabled":true,"max_file_size":"20MB","registration_enabled":true, ...}
```

El número de versión dependerá de la imagen descargada. Si `frontend_url` no coincide con tu dominio, revisa `PUBLIC_URL` en `.env`.

## Paso 4: Publicar Vikunja con Nginx y HTTPS

Instala Nginx y Certbot:

```bash
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx
```

Crea el bloque de servidor:

```bash
sudo nano /etc/nginx/sites-available/vikunja
```

```nginx
server {
    listen 80;
    listen [::]:80;
    server_name tareas.tu_dominio.com;

    # Tamaño máximo de los adjuntos (Vikunja permite 20 MB por defecto)
    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:3456;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Activa el sitio y recarga Nginx:

```bash
sudo ln -s /etc/nginx/sites-available/vikunja /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

Si usas UFW, permite SSH y el tráfico web:

```bash
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
```

Obtén el certificado de Let's Encrypt. Certbot activará HTTPS y la redirección desde HTTP:

```bash
sudo certbot --nginx -d tareas.tu_dominio.com
```

Verifica que la API responde a través del dominio:

```bash
curl -s https://tareas.tu_dominio.com/api/v1/info | head -c 80; echo
```

```output
{"version":"v1.0.0","frontend_url":"https://tareas.tu_dominio.com/","motd":
```

## Paso 5: Crear tu cuenta y cerrar el registro

Abre `https://tareas.tu_dominio.com`, pulsa **Crear cuenta** y regístrate con tu usuario, correo y una contraseña robusta. Después crea un proyecto y una tarea de prueba para confirmar que todo funciona. Desde el selector de vistas del proyecto puedes pasar de **Lista** a **Tablero** para trabajar en modo Kanban.

Una vez creada tu cuenta, desactiva el registro público para que nadie más pueda darse de alta. Edita `docker-compose.yml` y cambia la variable:

```yaml
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
```

Recrea el contenedor para aplicar el cambio:

```bash
sudo docker compose up -d
```

Comprueba que el registro aparece desactivado:

```bash
curl -s https://tareas.tu_dominio.com/api/v1/info | grep -o '"registration_enabled":[a-z]*'
```

```output
"registration_enabled":false
```

Con el registro cerrado, puedes dar de alta a otros usuarios desde la línea de comandos. El binario de Vikunja incluye comandos de administración:

```bash
sudo docker compose exec vikunja /app/vikunja/vikunja user create -u otro_usuario -e otro_usuario@tu_dominio.com
sudo docker compose exec vikunja /app/vikunja/vikunja user list
```

El comando `user create` solicita la contraseña de forma interactiva si no la pasas como opción.

## Paso 6: Usar la API con un token

Para scripts e integraciones, en lugar de tu contraseña usa un token de API con permisos limitados. En la web, ve a **Ajustes > Tokens de API**, crea un token, elige los permisos (por ejemplo, lectura y creación de tareas en proyectos) y una fecha de caducidad, y copia el valor, que empieza por `tk_`.

Guárdalo en una variable de entorno de tu sesión y lista tus proyectos:

```bash
export VIKUNJA_TOKEN='tk_tu_token'
curl -s https://tareas.tu_dominio.com/api/v1/projects \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"
```

La respuesta es un array JSON con tus proyectos. Anota el `id` de uno de ellos y crea una tarea en él (Vikunja usa `PUT` para crear recursos):

```bash
curl -s -X PUT https://tareas.tu_dominio.com/api/v1/projects/1/tasks \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Revisar copias de seguridad", "priority": 3}'
```

La respuesta incluye la tarea creada con su `id`, y la verás en la web al recargar el proyecto. La documentación interactiva de todos los endpoints está en `https://tareas.tu_dominio.com/api/v1/docs`.

## Paso 7: Sincronizar tareas por CalDAV

Vikunja expone los proyectos como listas de tareas CalDAV, lo que permite usarlos desde Thunderbird, DAVx5 en Android o Recordatorios en macOS e iOS.

1. En la web, ve a **Ajustes > CalDAV**. Ahí se muestra la URL CalDAV de tu cuenta, del tipo `https://tareas.tu_dominio.com/dav/principals/tu_usuario/`.
2. Crea un **token CalDAV** en esa misma página. Úsalo como contraseña en el cliente: es obligatorio si tienes activada la autenticación en dos pasos y recomendable en cualquier caso.
3. En el cliente, añade una cuenta CalDAV con esa URL, tu nombre de usuario y el token.

Puedes comprobar que el endpoint responde desde el servidor. Debe devolver el código `207`:

```bash
curl -s -o /dev/null -w '%{http_code}\n' -X PROPFIND -H 'Depth: 1' \
  -u 'tu_usuario:tu_token_caldav' https://tareas.tu_dominio.com/dav/principals/tu_usuario/
```

```output
207
```

## Paso 8: Copias de seguridad

Los datos de Vikunja están en PostgreSQL y en el directorio de adjuntos. Vuelca la base de datos con `pg_dump` desde el propio contenedor:

```bash
cd /opt/vikunja
sudo docker compose exec -T db pg_dump -U vikunja vikunja | sudo tee /opt/vikunja/vikunja.sql > /dev/null
ls -lh /opt/vikunja/vikunja.sql
```

Copia `vikunja.sql` y el directorio `/opt/vikunja/files` a un almacenamiento externo. Para actualizar Vikunja, ejecuta `sudo docker compose pull` y `sudo docker compose up -d`; las migraciones de la base de datos se aplican solas al arrancar.

## Solución de problemas

**La web carga pero no puedes iniciar sesión, o aparece "Token is invalid".** Suele deberse a que `JWT_SECRET` cambió entre reinicios. Déjalo fijo en `.env` y vuelve a iniciar sesión.

**Error al subir adjuntos.** Comprueba que `/opt/vikunja/files` pertenece al UID 1000 con `ls -ln /opt/vikunja` y que `client_max_body_size` en Nginx es al menos igual al tamaño máximo configurado en Vikunja.

**Vikunja no arranca y los logs muestran errores de conexión a la base de datos.** Revisa ambos servicios:

```bash
sudo docker compose logs --tail 50 vikunja
sudo docker compose logs --tail 20 db
```

Si PostgreSQL rechaza la contraseña, ten en cuenta que `POSTGRES_PASSWORD` solo se aplica al inicializar `./db` por primera vez. Cambiarla después en `.env` no modifica la contraseña ya guardada.

## Conclusión

Tienes Vikunja funcionando con PostgreSQL, publicado con HTTPS, con el registro cerrado y accesible por API y CalDAV. Como siguientes pasos, configura el correo saliente con las variables `VIKUNJA_MAILER_*` para recibir recordatorios, crea equipos para compartir proyectos con otros usuarios y programa el volcado del Paso 8 con un temporizador de systemd.