Llevaba tiempo queriendo un sitio único para mi documentación personal: notas técnicas, chuletas, procedimientos que siempre acabo rebuscando. Los requisitos eran claros: local, sin suscripciones, sin sincronizaciones mágicas, y con una prueba de fuego muy concreta — poder llevármelo todo a otra máquina copiando dos ficheros.
De ahí salió documentador: una sola aplicación escrita en Go que hace de CLI, de servidor web y de API, con todo el estado en un único fichero SQLite. Binario + base de datos = instalación completa.
Una app, tres puertas
- CLI para el día a día: crear, buscar, editar y etiquetar documentos desde la terminal, con salida
--jsonpara automatizar. - Web embebida en el propio binario: lista con búsqueda, render de Markdown, modo claro/oscuro, y usable desde el móvil.
- API JSON para trabajar en remoto: los mismos documentos, desde cualquier sitio, con tokens revocables.
Los documentos se escriben en Markdown y la búsqueda es de texto completo (FTS5 de SQLite), con fragmentos resaltados. Lo que no es texto —imágenes, PDFs— también vive dentro de la base de datos, como adjuntos: la portabilidad no admite excepciones.
El stack, deliberadamente aburrido
| Pieza | Elección | Por qué |
|---|---|---|
| Base de datos | SQLite en Go puro (sin CGO) | compila a binario único y cruza-compila a cualquier plataforma |
| CLI | cobra | subcomandos y flags estándar |
| Markdown | goldmark + GFM | tablas, tachado, autolinks |
| Web | net/http + html/template + embed | cero frameworks, todo dentro del binario |
Protegido por defecto
En cuanto defines una contraseña, la web exige sesión y la API exige token Bearer. Y hay un detalle del que estoy especialmente contento: el servidor se niega a escuchar fuera de localhost si no hay autenticación configurada. Es imposible exponerlo abierto a internet por descuido; tienes que pedirlo explícitamente con un flag que deja claro lo que estás asumiendo.
Para compartir algo puntual sin dar acceso a nada más, cada documento puede generar un enlace público de solo lectura: una URL con un token aleatorio de 128 bits, revocable al instante, que muestra ese documento (y solo ese) sin login y con noindex para los buscadores.
Desplegarlo donde quieras
Para servirlo desde un servidor hay una imagen Docker construida from scratch: unos 14 MB que contienen solo el binario, corriendo sin root, con los datos en un volumen. La primera arrancada obliga a definir la contraseña; después, actualizar la versión nunca toca los datos.
docker volume create documentador-data
echo 'mi-clave' | docker run -i --rm -v documentador-data:/data \
documentador auth set-password --password-stdin
docker run -d -p 8080:8080 -v documentador-data:/data documentadorLo más interesante: cómo se construyó
El proyecto entero está desarrollado con una metodología que combina tres cosas: SDD (Spec-Driven Development: las especificaciones son el contrato, y nada se implementa sin spec), TDD (el test en rojo antes que el código) y orquestación de agentes de IA — una sesión principal que diseña y verifica, delegando la implementación en subagentes que trabajan por fases, cada uno con propiedad exclusiva de sus ficheros.
El resultado: unos 185 tests, cero regresiones entre fases, y una lección que me llevo — una spec detallada convierte a un modelo de IA medio en un implementador sorprendentemente fiable. El gasto en especificar se recupera multiplicado.
Los tests prueban unidades; el orquestador prueba la historia completa. Lo que ninguno de los dos ve —un CSS que se rompe a 390 píxeles, un proxy que cachea ocho días— lo encuentra la verificación con el sistema de verdad.
Si te interesa el detalle de la metodología —specs, fases, prompts de subagentes y trucos para no quemar contexto—, dará para otra entrada.