Cómo autoalojar NoteDiscovery en un VPS con Docker

En resumen. NoteDiscovery es una app de notas de código abierto y autoalojada que guarda las notas como archivos Markdown planos. Esta guía la despliega en un VPS de Contabo con Docker Compose, detrás de un proxy inverso Caddy con HTTPS automático. Contratas un Cloud VPS 4 (4 núcleos vCPU, 8 GB de RAM), descargas la imagen oficial ghcr.io/gamosoft/notediscovery, activas la contraseña, conectas un asistente de IA por MCP y programas respaldos. Toma unos 20 minutos.

Requisitos

NoteDiscovery es una base de conocimiento ligera y autoalojada, así que corre sin problemas en un VPS pequeño. Antes de empezar, ten listo lo siguiente:

• Un Contabo Cloud VPS 4 (4 núcleos vCPU, 8 GB de RAM) o mayor, con Ubuntu 24.04 o posterior
• Docker y el plugin Docker Compose instalados en el servidor
• Un dominio con un registro A que apunte a la dirección IP de tu VPS
• Caddy para SSL automático, o un proxy inverso existente si ya tienes uno en marcha

Si vienes de una bóveda sincronizada en una app como Obsidian, los montajes autoalojados siguen la misma forma que esta guía: un contenedor Docker, un volumen de datos y un proxy inverso al frente. La diferencia es que NoteDiscovery trae su propia interfaz web, así que no hay un plugin de sincronización aparte que configurar.

Los 20 minutos indicados asumen que el VPS ya está aprovisionado y que el DNS ya apunta hacia él. La propagación de DNS puede sumar su propia espera según tu registrador, así que arranca por ese paso si vas siguiendo la guía en tiempo real. Acceso root solo lo necesitas para la configuración inicial del servidor. Una vez instalado Docker, cada paso restante es una operación de contenedor o una edición de un archivo de configuración montado.

Paso 1: aprovisiona tu VPS e instala Docker

El aprovisionamiento toma unos cinco minutos y es la única parte de esta guía que haces fuera de Docker. Lanza un Cloud VPS 4 desde el Contabo Customer Control Panel, elige Ubuntu 24.04 o posterior y agrega tu llave SSH durante la configuración para saltarte por completo los inicios de sesión con contraseña. Si todavía no tienes un par de llaves, genera uno localmente con ssh-keygen -t ed25519 antes de abrir el formulario de pedido. El Customer Control Panel te deja pegar la llave pública directamente en la pantalla de aprovisionamiento.

Cuando el servidor arranque, conéctate y asegúralo antes de instalar nada. Las reglas de firewall de abajo abren solo lo que esta guía realmente necesita: SSH para administración y los puertos 80 y 443 para que Caddy sirva HTTP y HTTPS. Todo lo demás en el servidor queda inalcanzable desde fuera, y eso importa más aquí que en una app web común, porque tus notas viven en esa misma máquina.

ssh root@your-server-ip
ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Con el firewall activo, instala Docker y el plugin Compose:

curl -fsSL https://get.docker.com | sh
apt install docker-compose-plugin -y
docker --version
docker compose version

Esta es la misma base que usa cualquier base de conocimiento autoalojada que corra en contenedores, y es exactamente lo que NoteDiscovery necesita antes de que arranque su propio contenedor: un firewall cerrado, Docker Engine actualizado y el plugin Compose para que un stack de varios contenedores quede a un solo comando de distancia. Confirma que ambos comandos de versión devuelvan salida antes de continuar.

Paso 2: despliega NoteDiscovery con Docker Compose

NoteDiscovery se despliega como un solo contenedor, así que todo el stack cabe en un archivo. Crea primero un directorio de proyecto y una carpeta de datos, porque la carpeta de datos tiene que existir antes de que el contenedor arranque:

mkdir -p notediscovery/data && cd notediscovery

Después crea docker-compose.yml:

services:
  notediscovery:
    image: ghcr.io/gamosoft/notediscovery:latest
    container_name: notediscovery
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data

Cada línea hace un trabajo: image descarga la compilación oficial directamente desde GitHub Container Registry, restart: unless-stopped regresa NoteDiscovery después de un reinicio o una caída, ports mapea el puerto 8000 del contenedor al mismo puerto del host, y esa única línea de volumen es lo que vuelve persistentes tus notas en lugar de que desaparezcan con el contenedor. No hace falta ningún servicio de base de datos, porque NoteDiscovery no tiene ninguna.

Levanta el stack:

docker compose up -d
docker compose logs -f notediscovery

NoteDiscovery ya está escuchando en el puerto 8000 y tus notas viven en ./data como archivos Markdown planos, no en una base de datos. Visita http://your-server-ip:8000 y confirma que la interfaz carga antes de poner el proxy inverso al frente. Si el contenedor se cierra de inmediato, revisa que la carpeta data exista y tenga permisos de escritura. Un volumen vacío o ausente es la causa más común de un primer arranque fallido.

Paso 3: configura el proxy inverso Caddy con HTTPS

Caddy se coloca frente a NoteDiscovery y maneja HTTPS de forma automática, así que este paso necesita un Caddyfile y nada más. Antes de instalar Caddy, confirma que el registro A de tu dominio apunta a la dirección IP del VPS. La solicitud automática de certificado de Caddy falla en silencio si el dominio todavía no resuelve al servidor, así que vale la pena revisar primero que un dig notes.example.com devuelva la IP de tu servidor. Instala Caddy en el host:

apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update && apt install caddy -y

Después apunta el Caddyfile a tu dominio y al puerto del contenedor:

notes.example.com {
    reverse_proxy localhost:8000
}

Recarga Caddy y él solicita un certificado a Let’s Encrypt por su cuenta:

systemctl reload caddy

En unos segundos tu dominio sirve NoteDiscovery sobre HTTPS sin que toques ningún certificado. Es el mismo patrón que usas para acceder a Obsidian desde el navegador y para una bóveda de Obsidian autoalojada movida a un dominio público: Caddy termina TLS y el contenedor de la app nunca necesita saber que hay cifrado de por medio.

Paso 4: activa la contraseña

La protección con contraseña viene desactivada de fábrica y la contraseña predeterminada incluida es admin. Por eso, activarla, generar una llave secreta real y cambiar esa contraseña es lo primero que toca hacer en cuanto HTTPS esté funcionando.

Empieza generando una llave secreta, que cifra las cookies de sesión, desde dentro del contenedor en marcha:

docker exec -it notediscovery python -c "import secrets; print(secrets.token_hex(32))"

Guarda ese valor y después descarga el archivo de configuración predeterminado de NoteDiscovery para tener tu propia copia editable:

curl -o config.yaml https://raw.githubusercontent.com/gamosoft/notediscovery/main/config.yaml

Edita el nuevo config.yaml y define:

authentication:
  enabled: true
  password: "your-strong-password-here"
  secret_key: "the-value-from-the-command-above"

Monta el archivo dentro del contenedor para que tus ediciones sobrevivan a los reinicios y a las actualizaciones de imagen. Agrégalo a docker-compose.yml junto al volumen de datos existente:

    volumes:
      - ./data:/app/data
      - ./config.yaml:/app/config.yaml

Recrea el contenedor para que tome el nuevo volumen:

docker compose up -d

Recarga el sitio y NoteDiscovery pedirá la contraseña antes de mostrar cualquier nota. Saltarte este paso no es buena idea: la app escucha en todas las interfaces de red de forma predeterminada, así que una instancia sin autenticación detrás de un dominio público queda al alcance de cualquiera que encuentre la URL. Elige una contraseña con entropía real, no una palabra corta con un número al final, y nunca reutilices la llave secreta en otras aplicaciones. Juntas son lo único que se interpone entre internet y toda tu bóveda.

Paso 5: conecta tu asistente de IA (MCP)

NoteDiscovery incluye un servidor MCP integrado, así que conectar un asistente de IA es un fragmento de configuración y no una instalación aparte. Agrega esto a la configuración de servidores MCP de tu asistente, sea Claude Desktop, Cursor u otro cliente compatible con MCP:

{
  "mcpServers": {
    "notediscovery": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e",
        "NOTEDISCOVERY_URL=https://notes.example.com",
        "ghcr.io/gamosoft/notediscovery:latest", "python", "-m",
        "mcp_server"]
    }
  }
}

Reemplaza el valor de NOTEDISCOVERY_URL con tu propio dominio del Paso 3. Cuando el asistente recargue sus servidores MCP, podrá buscar en tus notas, crear notas nuevas a partir de una instrucción, seguir etiquetas y enlaces internos por toda tu bóveda y añadir texto a una nota existente, por ejemplo un diario personal. Todo eso sin salir de la ventana de chat. Una instrucción como “encuentra todas mis notas sobre despliegue con Docker” o “agrega esta idea a la entrada de hoy en mi diario” se resuelve con las mismas herramientas MCP que una persona iría clicando en la interfaz web.

Esta es la función que más separa a NoteDiscovery de una base de conocimiento pensada solo para personas: las mismas notas quedan legibles para un asistente de IA a través de un protocolo documentado, no leídas a la fuerza por una extensión de navegador. Si el cliente de tu asistente se autentica por HTTPS en vez de con un comando Docker local, apúntalo al dominio público del Paso 3 y no a la URL entre contenedores de arriba.

Paso 6: respalda tus notas

Las notas viven en ./data como archivos Markdown planos, así que respaldarlas es un trabajo de sincronización de archivos y no una exportación de base de datos. La opción más simple es una sincronización programada hacia tu destino de almacenamiento:

apt install rclone -y
rclone config
# create a remote named "storage" pointing at your storage location
rclone sync /root/notediscovery/data storage:notediscovery-backup

Agrega una entrada diaria en cron para que la sincronización corra sin supervisión:

crontab -e
# 0 3 * * * rclone sync /root/notediscovery/data storage:notediscovery-backup

Como toda la bóveda son archivos Markdown en disco, una base de conocimiento así es fácil de restaurar: copia la carpeta de datos respaldada a un VPS nuevo, apunta el mismo archivo de Docker Compose hacia ella y arranca el contenedor. Vale la pena ejecutar esa restauración una vez de verdad, contra un VPS libre o una instalación local de Docker, porque un respaldo cuya restauración nunca probaste es apenas una suposición. Conserva al menos unos días de historial en tu bucket de almacenamiento en lugar de sobrescribir una sola instantánea, para que una sincronización mala o un borrado accidental no arrase con la única copia que tienes.

Solución de problemas

Casi todo lo que puede salir mal en este montaje se remite a una de tres causas: un volumen faltante, una solicitud de certificado que corrió antes de que el DNS estuviera listo, o un cambio de configuración que solo vivió dentro del contenedor.

El contenedor se cierra de inmediato tras docker compose up -d. La causa más común es una carpeta de datos ausente o sin permisos de escritura, porque NoteDiscovery espera que ya exista. Ejecuta otra vez mkdir -p notediscovery/data del Paso 2, confirma que la carpeta pertenezca a tu usuario o a root, y levanta el stack una vez más con docker compose up -d.

Caddy nunca obtiene certificado y el sitio se queda en HTTP. Casi siempre significa que el registro A del dominio todavía no apuntaba a la IP del VPS cuando Caddy hizo su primera solicitud. Confirma la resolución con dig notes.example.com y recarga Caddy con systemctl reload caddy en cuanto el registro se haya propagado. No hace falta cambiar nada en el Caddyfile.

El cambio de contraseña o de llave secreta del Paso 4 no surte efecto. Un docker compose restart simple reutiliza el contenedor existente, así que no tomará un volumen config.yaml que acabas de agregar a docker-compose.yml. Usa docker compose up -d en su lugar, que recrea el contenedor con el nuevo volumen montado.

FAQ: configuración de NoteDiscovery