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

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


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:

1

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


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.

Desplegar Joplin Server en Synology DSM 7.x

En Synology DSM 7.x, la forma más cómoda de desplegar Joplin Server es usar la función “Project” de Container Manager. En el fondo es Docker Compose: un contenedor PostgreSQL, un contenedor Joplin Server, y Synology se encarga de descargar imágenes, crear contenedores y gestionar el arranque diario.

Esta es la versión específica para Synology. Se centra en directorios de File Station, proyectos de Container Manager, acceso LAN, sincronización remota y proxy inverso. Si ya escribes docker-compose.yml a mano en servidores Linux, el flujo te resultará familiar. Si usas sobre todo la interfaz gráfica de Synology, también puedes seguirlo paso a paso.

Cuándo tiene sentido

Joplin Server sirve si quieres guardar los datos de sincronización de notas en tu propio dispositivo. Permite que clientes Windows, macOS, iOS, Android y otros sincronicen a través de tu propio servidor, sin depender de una nube de terceros.

Desplegarlo en Synology encaja bien si:

tu NAS está encendido de forma permanente y puede actuar como servidor personal o doméstico de sincronización;
solo quieres sincronizar ordenadores y teléfonos dentro de la LAN;
quieres sincronización remota mediante Tailscale, WireGuard o un proxy inverso;
prefieres gestionar contenedores desde Container Manager en lugar de usar SSH todo el tiempo.

Si solo estás probando Joplin de forma temporal, no necesitas necesariamente Joplin Server. Joplin también soporta WebDAV, S3, Dropbox y otros métodos de sincronización. Pero para self-hosting a largo plazo, Joplin Server es una opción más completa.

Paso 1: preparar directorios en File Station

Abre File Station en Synology y entra en la carpeta compartida docker.

Crea un directorio:

1

docker/joplin

Dentro de joplin, crea otro subdirectorio:

1

postgres_data

La estructura final debería quedar más o menos así:

1
2
3


docker/
└── joplin/
    └── postgres_data/

postgres_data sirve para guardar la base de datos PostgreSQL. Los datos de sincronización de Joplin Server viven principalmente en la base de datos, así que este directorio debe persistir. Cuando actualices o recrees contenedores, los datos no desaparecerán mientras este directorio siga existiendo.

Paso 2: crear un proyecto en Container Manager

Abre Container Manager en Synology:

haz clic en Project en la barra izquierda;
haz clic en Create;
usa joplin-server como nombre del proyecto;
elige la ruta /docker/joplin que creaste;
selecciona Create docker-compose.yml como origen.

Pega esta configuración Compose:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


version: '3'

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

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

Debes cambiar dos valores:

POSTGRES_PASSWORD: la contraseña de la base de datos. Debe ser idéntica en ambos lugares;
APP_BASE_URL: la dirección real que los clientes de Joplin usarán para llegar al servidor.

Si solo lo usas dentro de la LAN, cambia APP_BASE_URL por la IP local de Synology:

1

- APP_BASE_URL=http://192.168.1.100:22300

Si ya tienes un proxy inverso HTTPS, escribe directamente el dominio externo:

1

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

No rellenes APP_BASE_URL al azar. La sincronización de clientes, las redirecciones web y los enlaces de adjuntos dependen de ese valor. Debe ser la dirección que realmente vas a usar.

Tras confirmar la configuración, continúa hasta finalizar. Container Manager descargará postgres:16 y joplin/server:latest, y luego iniciará los dos contenedores.

Paso 3: comprobar el estado de los contenedores

Después de crear el proyecto, abre la página del proyecto joplin-server en Container Manager.

Normalmente verás dos contenedores:

joplin-db
joplin-server

Si ambos están en verde y ejecutándose, puedes continuar.

Si no arrancan correctamente, revisa primero los logs del proyecto. Las causas frecuentes son:

las dos contraseñas de base de datos no coinciden;
el directorio postgres_data tiene problemas de permisos;
el puerto 22300 de Synology ya está ocupado por otro servicio;
la indentación YAML se rompió.

Paso 4: primer inicio de sesión en Joplin Server

Abre en el navegador:

1

http://群晖IP:22300

Por ejemplo:

1

http://192.168.1.100:22300

La cuenta administradora predeterminada es:

1

admin@localhost

La contraseña predeterminada es:

1

admin

Después del primer inicio de sesión, cambia la contraseña del administrador de inmediato. No te saltes este paso, especialmente si planeas configurar acceso remoto.

Si el panel permite cambiar el correo del administrador, también conviene poner tu propio correo para identificar mejor la cuenta.

Paso 5: ¿crear un usuario normal?

Si solo lo usas tú, puedes sincronizar con la cuenta administradora ya actualizada. Pero una práctica más limpia es crear un usuario normal para sincronizar notas, dejando la cuenta administradora solo para gestionar el panel.

En el panel de administración:

entra en Users;
haz clic en Add user;
escribe correo y contraseña;
guarda.

Si no configuraste SMTP, el sistema dirá que envió un correo de activación, pero no lo recibirás. En ese caso, entra en la página Emails del panel, busca el correo de activación no enviado, copia el enlace de activación y ábrelo en el navegador para activar la cuenta.

Para uso personal, no configurar SMTP no es un problema. Para varios usuarios a largo plazo, conviene añadir SMTP después, porque registro, activación y restablecimiento de contraseña serán menos molestos.

Paso 6: configurar la sincronización del cliente Joplin

Abre el cliente Joplin en tu ordenador o teléfono:

entra en Options / Settings;
abre Synchronization;
elige Joplin Server como destino de sincronización;
en Joplin Server URL, escribe el APP_BASE_URL configurado antes;
como usuario, escribe el correo del administrador o del usuario normal;
escribe la contraseña correspondiente;
pulsa Check synchronization configuration.

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

Si falla, confirma primero si el cliente puede abrir Joplin Server en el navegador. Muchos problemas de sincronización no vienen de Joplin, sino de un APP_BASE_URL incorrecto, una cuenta sin activar, un certificado roto en el proxy inverso o un teléfono que no está en la misma red.

Opción remota 1: Tailscale o WireGuard

La forma más segura y cómoda de sincronizar desde fuera es conectar el teléfono y el ordenador de vuelta a la red de casa mediante VPN.

Opciones comunes:

Tailscale;
WireGuard;
ZeroTier.

La ventaja es que Joplin Server no necesita exponerse directamente a internet. La URL en el cliente Joplin puede seguir siendo la IP local de Synology, por ejemplo:

1

http://192.168.1.100:22300

Cuando el teléfono esté fuera, conecta primero Tailscale o WireGuard y luego abre Joplin para sincronizar.

Si no quieres tratar con IP pública, DDNS, certificados y reenvío de puertos, esta es la ruta más estable. La desventaja es que cada dispositivo externo debe conectarse primero a la VPN.

Opción remota 2: proxy inverso HTTPS de Synology

Si quieres que Joplin sincronice directamente desde cualquier red, configura un dominio HTTPS.

El flujo general es:

prepara un dominio o DDNS;
reenvía el puerto 443 del router a Synology;
en Synology Control Panel -> Login Portal -> Advanced -> Reverse Proxy, crea una regla nueva;
usa https://joplin.example.com:443 como origen;
usa http://127.0.0.1:22300 o http://群晖内网IP:22300 como destino;
solicita y asigna un certificado HTTPS para el dominio;
cambia APP_BASE_URL en Compose a https://joplin.example.com;
redepliega el proyecto en Container Manager.

Al usar proxy inverso, conviene añadir cabeceras reenviadas comunes en los encabezados personalizados:

1
2
3
4


Host: $host
X-Real-IP: $remote_addr
X-Forwarded-For: $proxy_add_x_forwarded_for
X-Forwarded-Proto: $scheme

Si usas la interfaz de proxy inverso integrada en Synology, los nombres de campos pueden variar ligeramente entre versiones menores de DSM. Añádelos mediante las opciones de “custom header” o relacionadas con “WebSocket” que aparezcan en la interfaz.

Joplin también puede encontrar límites de subida al sincronizar adjuntos grandes. Si usas Nginx Proxy Manager o Nginx manual, configura:

1

client_max_body_size 100M;

Si el proxy inverso integrado de Synology no ofrece esa opción, prueba primero la sincronización con adjuntos normales. Si sincronizas archivos grandes con frecuencia, Nginx Proxy Manager o Caddy serán más flexibles.

Redeplegar después de cambiar APP_BASE_URL

Mucha gente prueba primero con una IP local y luego cambia a un dominio HTTPS. Está bien, pero no cambies solo el cliente.

También debes modificar la configuración Compose del proyecto en Container Manager:

1

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

Después redepliega el proyecto para que las variables de entorno del contenedor surtan efecto.

Si APP_BASE_URL sigue apuntando a la dirección antigua, pueden aparecer estos problemas:

la comprobación de sincronización del cliente falla;
después de iniciar sesión redirige a una dirección incorrecta;
los enlaces de adjuntos fallan;
el protocolo se detecta mal detrás del proxy inverso.

Prioridades de copia de seguridad

En Synology, el directorio más importante es:

1

docker/joplin/postgres_data

Ahí está la base de datos PostgreSQL, es decir, los datos centrales de sincronización de Joplin Server. Conviene incluirlo en Hyper Backup u otro plan de copia de seguridad.

Una estrategia más sólida:

hacer copias periódicas de docker/joplin/postgres_data;
mantener una copia local de las notas en los clientes Joplin;
exportar notas importantes como JEX de vez en cuando;
confirmar que la copia funciona antes de actualizar contenedores.

No respaldes solo la imagen o la configuración del contenedor de Joplin Server. Las imágenes se pueden descargar de nuevo; la base de datos es tu información.

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.