Cómo instalar Joplin Server: servidor privado de sincronización con Docker Compose

Fri, 05 Jun 2026 21:31:17 +0800

Joplin Server es el servidor oficial de sincronización de Joplin. Al alojarlo tú mismo, tus notas pueden quedar en tu VPS, NAS o servidor doméstico, y los clientes de escritorio y móvil pueden sincronizar sin depender de una nube de terceros.

El método más cómodo actualmente es Docker Compose: un contenedor PostgreSQL, un contenedor Joplin Server y un APP_BASE_URL bien configurado.

Esta guía está pensada para despliegues prácticos en Ubuntu, Debian, CentOS, Synology, Unraid, OpenMediaVault o cualquier entorno capaz de ejecutar Docker.

Requisitos

Antes de empezar, confirma que tienes:

un servidor o NAS que pueda estar encendido de forma estable;
Docker y Docker Compose instalados;
una IP interna si solo necesitas sincronización en LAN;
un dominio y proxy inverso HTTPS si necesitas acceso desde fuera;
una contraseña real para la base de datos. No uses la contraseña de ejemplo.

Si solo sincronizas varios dispositivos en casa, http://IP-LAN:22300 basta para empezar. Si necesitas sincronizar desde fuera con el móvil, usa Nginx Proxy Manager, Caddy, Traefik o una herramienta similar con HTTPS. Evita exponer un servicio HTTP sin cifrar directamente a internet.

Crear el directorio de trabajo de Joplin

Prepara un directorio dedicado para la configuración de Joplin Server y los datos de la base de datos:

1
2

mkdir -p /data/joplin
cd /data/joplin

Puedes usar otra ruta, como /opt/joplin o /volume1/docker/joplin. Lo importante es persistir el directorio de la base de datos, para que los datos de PostgreSQL no desaparezcan al borrar el contenedor.

Escribir docker-compose.yml

Crea el archivo Compose en el directorio de trabajo:

`1`	`nano docker-compose.yml`

Pega esta configuración:

version: '3.8'

services:
  db:
    image: postgres:16
    container_name: joplin-db
    restart: unless-stopped
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=change_this_database_password
      - POSTGRES_DB=joplin

  app:
    image: joplin/server:latest
    container_name: joplin-app
    depends_on:
      - db
    restart: unless-stopped
    ports:
      - "22300:22300"
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=http://your-server-ip:22300
      - DB_CLIENT=pg
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=change_this_database_password
      - POSTGRES_DATABASE=joplin
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432

Debes cambiar sobre todo dos valores:

POSTGRES_PASSWORD: la contraseña de la base de datos. Debe ser idéntica en los servicios db y app;
APP_BASE_URL: la dirección fija que usarán los clientes de Joplin para acceder al servidor.

APP_BASE_URL es crítico. Debe ser la dirección que los clientes realmente puedan abrir:

solo LAN: http://192.168.1.10:22300
IP pública: http://your-public-ip:22300
dominio con HTTPS: https://joplin.example.com

Si más adelante cambias la dirección de acceso, actualiza también APP_BASE_URL y reinicia el servicio. Si no, la sincronización, las redirecciones web o los enlaces de adjuntos pueden fallar.

Iniciar Joplin Server

Ejecuta esto en el directorio donde está docker-compose.yml:

`1`	`docker compose up -d`

Comprueba el estado de los contenedores:

`1`	`docker compose ps`

Si el primer arranque tarda, mira los logs:

`1`	`docker compose logs -f`

Normalmente Joplin Server escucha en el puerto 22300. Abre en el navegador el APP_BASE_URL configurado. Si aparece la página de inicio de sesión, el despliegue básico funciona.

Primer inicio de sesión como administrador

La cuenta administradora predeterminada es:

`1`	`admin@localhost`

La contraseña predeterminada es:

admin

Después del primer inicio de sesión, haz una cosa de inmediato: cambia la contraseña del administrador. No dejes la contraseña predeterminada en el servidor, especialmente si el servicio es accesible desde internet.

En el panel de administración, entra en Change Password y reemplaza admin por una contraseña fuerte.

Crear una cuenta diaria de sincronización

No conviene usar la cuenta administradora para sincronizar notas a diario. Es más limpio crear un usuario normal y usarlo en los clientes de escritorio y móvil.

En el panel de administración:

entra en Users;
haz clic en Add user;
introduce el correo y la contraseña que quieras usar;
crea el usuario.

Hay una trampa común: si SMTP no está configurado, Joplin Server dirá que envió un correo de activación, pero no lo recibirás.

La solución es sencilla:

vuelve al panel de administración;
abre el menú Emails;
busca el correo de activación no enviado;
copia el enlace de activación que contiene;
abre el enlace en una nueva pestaña del navegador para activar la cuenta.

Después de activarla, este usuario normal puede usarse para sincronizar clientes.

Configurar la sincronización del cliente Joplin

En la app de Joplin de escritorio o móvil:

abre Options o los ajustes;
entra en Synchronization;
elige Joplin Server como destino de sincronización;
escribe tu APP_BASE_URL en Joplin Server URL;
escribe el correo del usuario normal activado en Email / Username;
escribe la contraseña de ese usuario;
pulsa Check sync configuration.

Si la comprobación funciona, guarda la configuración y empieza a sincronizar.

Si falla, revisa primero:

si el cliente puede abrir APP_BASE_URL en un navegador;
si APP_BASE_URL coincide con el archivo Compose;
si el usuario normal ya está activado, no solo creado.

Usar HTTPS para acceso externo

HTTP suele ser suficiente si solo usas la red local. Para acceso público, usa un proxy inverso con HTTPS.

Opciones comunes:

Nginx Proxy Manager;
Caddy;
Traefik;
configuración manual de Nginx.

Con proxy inverso, APP_BASE_URL debe ser la dirección HTTPS final que usarán los clientes, por ejemplo:

`1`	`- APP_BASE_URL=https://joplin.example.com`

Si configuras Nginx manualmente, presta atención al menos a dos cosas:

aumenta el límite de subida, por ejemplo client_max_body_size 100M;, o las notas con adjuntos grandes pueden fallar al sincronizar;
reenvía correctamente Host, X-Forwarded-For, X-Forwarded-Proto y cabeceras relacionadas, para que Joplin Server detecte bien la URL y el protocolo.

Ejemplo simplificado de proxy inverso con Nginx:

server {
    listen 443 ssl http2;
    server_name joplin.example.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:22300;
        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;
    }
}

Con Nginx Proxy Manager, normalmente basta con apuntar el dominio al puerto 22300 del servidor y activar el certificado SSL. Recuerda cambiar también APP_BASE_URL en Compose al dominio HTTPS.

Problemas comunes

APP_BASE_URL no cambia después de editarlo

Después de modificar docker-compose.yml, recrea los contenedores:

`1`	`docker compose up -d`

Si sigue fallando, verifica que las variables de entorno del contenedor hayan cambiado de verdad. No basta con editar el archivo si el servicio no se reinicia.

El cliente muestra error de red al sincronizar

Revisa primero:

si el móvil o el ordenador puede abrir Joplin Server en el navegador;
si el certificado del proxy inverso es válido;
si APP_BASE_URL es la dirección real usada por los clientes;
si el firewall permite 22300 o el puerto HTTPS;
si el usuario normal ya está activado.

Fallan los adjuntos grandes

Si accedes a través de Nginx u otro proxy inverso, revisa primero el límite de subida. Los valores predeterminados de Nginx pueden ser bajos, así que configura:

`1`	`client_max_body_size 100M;`

Si tus adjuntos son más grandes, aumenta el valor.

¿Se puede usar sin SMTP?

Sí. Para uso personal o familiar, SMTP no es obligatorio. Después de crear un usuario, abre la página Emails en el panel de administración y copia manualmente el enlace de activación.

Para uso de equipo a largo plazo, configura SMTP para que funcionen mejor el registro, el restablecimiento de contraseñas y las notificaciones.

Recomendaciones de copia de seguridad

Los datos más importantes de Joplin Server están en PostgreSQL. En el ejemplo anterior, están en:

`1`	`/data/joplin/data/postgres`

Haz copias regulares de este directorio, o usa pg_dump de PostgreSQL para respaldar la base de datos. Copiar solo el contenedor de Joplin Server no sirve de mucho: el contenedor se puede volver a descargar, pero la base de datos contiene los datos de sincronización.

Los clientes locales también conservan copias de las notas, pero no los trates como la única copia de seguridad. Una estrategia más sólida es backup de la base de datos del servidor + copias locales en clientes + exportaciones JEX ocasionales.

Resumen

Desplegar Joplin Server con Docker Compose no es complicado. Los puntos donde más se suele tropezar son:

APP_BASE_URL debe ser la dirección real usada por los clientes;
la contraseña administradora predeterminada admin debe cambiarse de inmediato;
sin SMTP, los usuarios nuevos deben activarse desde la página Emails del panel de administración.

Para uso en LAN, http://IP:22300 basta para sincronizar. Para acceso público, usa un proxy inverso HTTPS y ajusta el límite de subida. Con esos detalles resueltos, Joplin Server es una solución estable de sincronización privada de notas.

PostgreSQL on KnightLi Blog