gistly: la alternativa self-hosted a GitHub Gists con Docker

En pocas palabras: Fedya Serafiev creó gistly, una alternativa self-hosted a GitHub Gists hecha con Next.js, TypeScript y Prisma sobre SQLite. Corre en un solo archivo y se despliega con 4 comandos vía Docker. Es MIT, bilingüe inglés/búlgaro y suma dashboard de insights y command palette.

El desarrollador Fedya Serafiev publicó gistly, una alternativa self-hosted a GitHub Gists construida con Next.js y Prisma, que corre en un solo archivo SQLite y se despliega con un comando Docker. El proyecto es de código abierto bajo licencia MIT y suma dashboard de insights, command palette e interfaz bilingüe inglés/búlgaro, según el posteo original del autor en dev.to.

gistly es una aplicación de código abierto para compartir fragmentos de código que funciona como alternativa self-hosted a GitHub Gists. Serafiev la construyó con Next.js, TypeScript y Prisma sobre SQLite, y permite correr un servidor propio de snippets con autenticación de administrador único, visibilidad configurable y un dashboard de métricas, todo bajo licencia MIT.

¿Qué problema resuelve gistly frente a GitHub Gists?

gistly resuelve la dependencia total de GitHub Gists: ahí no podés self-hostear nada, no hay tags, no hay estadísticas de uso y el snippet vive bajo los términos de GitHub, no en tu servidor ni tu dominio. Serafiev usó Gists y OpenGist durante años y, en algún momento, decidió construir su propia versión con otro enfoque.

Según cuenta en su propio relato, algo le molestaba desde hace tiempo: ningún idioma búlgaro en la interfaz (sí, en serio, ese fue el punto de partida). OpenGist le parecía un gran proyecto, incluso inspiró partes del suyo, pero quería otra cosa: un dashboard moderno, un command palette y un setup tan simple que todo el “cluster” terminara siendo un archivo SQLite y un comando Docker.

¿Y qué hizo con esa frustración acumulada? Lo de siempre: se armó su propia herramienta.

¿Qué funcionalidades tiene gistly?

gistly tiene resaltado de sintaxis con Shiki, modo single-admin, tres niveles de visibilidad y un command palette activado con Ctrl+K. La lista completa, tal como la describe el autor, es la siguiente:

• Syntax highlighting con Shiki: temas oficiales GitHub Light y Dark, más de 40 lenguajes, números de línea y toggle de soft-wrap.
• Markdown preview con GFM: los archivos .md renderizan tablas, task lists y bloques de código resaltados.
• Modo single-admin: solo el administrador, con login por contraseña, crea y edita gists. El resto de la gente abre links.
• Tres niveles de visibilidad: Public (listado), Unlisted (solo con link) y Secret (link más token).
• Búsqueda full-text y tags: con nube de tags clickeable (#typescript, #sql, etc).
• Command palette: Ctrl+K en cualquier pantalla, para buscar gists y ejecutar comandos, al estilo VS Code o Linear.
• Paginación load-more: con contadores en vivo.
• Tema oscuro y claro: con interfaz bilingüe EN/BG completa.
• Docker-first: imagen multi-stage, volumen persistente de SQLite y un script ./deploy.sh para levantar todo.

El propio Serafiev admite que el dashboard de Insights y el command palette son las dos cosas que más le faltaban en otras herramientas. Nada muy misterioso, pero tiene sentido: son justo las funciones que uno termina extrañando cuando pasa de GitHub a cualquier self-hosted más básico. Para más detalles técnicos, mirá cómo armamos nuestro pipeline de CI/CD.

¿Qué muestra el dashboard de Insights de gistly?

El dashboard de Insights de gistly muestra un heatmap de actividad estilo GitHub (26 semanas, una celda por día, en violeta en vez de verde), breakdown por lenguaje y por tag, y el gist más visto junto con el más reciente. Todo se calcula con un único Promise.all paralelo que corre los counts y los groupBy de tags, lenguajes y visibilidad.

Lo interesante es cómo cuenta las líneas de código sin cargar el contenido completo en Node: usa una query SQL cruda con $queryRaw que suma los saltos de línea directo en SQLite. Para un proyecto que se jacta de ser “liviano”, es una decisión coherente, nada de traer archivos enteros a memoria para un número que podés calcular en la base.

El heatmap, según el propio código que describe el autor, es de 182 buckets diarios alineados a domingos. Barato de calcular y rápido de renderizar en el cliente.

¿Con qué stack técnico está construido gistly?

gistly está construido con Next.js (App Router), TypeScript, Tailwind CSS 4 y shadcn/ui en el frontend, y Prisma sobre SQLite en el backend, sin servidor de base de datos separado. El resaltado de código corre con Shiki, el mismo motor que usa VS Code.

El resto del stack suma Framer Motion para las animaciones, next-themes para el toggle de tema y Sonner para las notificaciones. El build es multi-stage con Docker usando Bun, y la imagen final corre Next.js en modo standalone, aplicando el schema de Prisma al arrancar el contenedor para que un container nuevo funcione sin pasos manuales. Cubrimos ese tema en detalle en la comparativa entre Jenkins y GitHub Actions.

Nada revolucionario en la elección de piezas (son todas tecnologías conocidas), pero la combinación apunta a un objetivo claro: que toda la infraestructura quepa en un archivo SQLite que podés sacar con un docker cp y listo, tenés tu backup.

¿Cómo se instala gistly con Docker?

gistly se instala con 4 comandos: clonás el repo, armás un archivo .env con la contraseña de admin y un secret generado con OpenSSL, y corrés ./deploy.sh. Los pasos exactos que publica el autor son estos:

• git clone https://github.com/fedya-dev/gistly.git
• cd gistly
• echo "ADMIN_PASSWORD=change-me" > .env
• echo "AUTH_SECRET=$(openssl rand -hex 32)" >> .env
• ./deploy.sh

Con eso, la app queda corriendo en el puerto 3000 y los datos persisten en el volumen gistly_data aunque reconstruyas el contenedor. Cualquier reverse proxy puede ponerse adelante, Caddy por ejemplo te da HTTPS automático sin configurar certificados a mano.

Si estás pensando en levantar esto en un VPS propio para no depender de servicios de terceros, en Donweb podés conseguir infraestructura cloud en Argentina para alojar este tipo de proyectos.

¿Qué errores técnicos encontró el autor al desarrollar gistly?

Serafiev documentó dos bugs concretos durante el desarrollo: la Clipboard API que no funciona en HTTP plano, y BuildKit Bake que rechaza network: host desde la versión 2.36 de Docker Compose en adelante. Los dos tienen solución simple, pero valen la pena como advertencia para quien clone el proyecto.

El primero: navigator.clipboard no existe fuera de contextos seguros. El botón de “Copy link” le funcionaba en localhost y explotaba con un TypeError en http://ip-del-servidor:3000, porque la Clipboard API solo vive en HTTPS o localhost. ¿La solución? El fallback de siempre: si hay contexto seguro y la API existe, usarla; si no, un <textarea> oculto con document.execCommand('copy'). Con los dos caminos cubiertos, el botón funciona antes y después de configurar TLS. Más contexto en las ventajas de privacidad frente a GitHub.

El segundo bug es más de infraestructura que de código: su docker-compose.yml builda en la network del host (porque algunos VPS tienen la bridge de Docker rota, con el clásico EAI_AGAIN colgando el bun install). El tema es que las versiones nuevas de Compose, 2.36 en adelante, buildean con BuildKit Bake y rechazan esa configuración con un error de permisos. La solución terminó siendo un script chico: docker buildx build --allow=network.host --network=host -t gistly:latest . seguido de docker compose up -d. Si tu networking de Docker anda bien, el docker compose up -d --build de siempre te sirve igual.

¿Qué planea agregar el autor a gistly a futuro?

Serafiev listó cuatro ideas para próximas versiones: acortador de URLs crudas, gists que expiran automáticamente, modo multi-usuario opcional y OG images que renderizan las primeras líneas de código para preview de links. Ninguna fecha confirmada, son ideas en el backlog del proyecto.

El proyecto entero es MIT licensed, lo suficientemente chico como para leerlo en una sentada, según palabras del propio autor. Las PRs y los “issue rants” (como los llama él) son bienvenidos en el repositorio.

Errores comunes al instalar una alternativa self-hosted a GitHub Gists

• Dejar la contraseña de ejemplo: el .env de gistly viene con ADMIN_PASSWORD=change-me a propósito. Si no la cambiás antes de exponer el puerto a internet, cualquiera con el link puede intentar loguearse como admin.
• Exponer el puerto 3000 sin proxy: correr la app directo en HTTP, sin Caddy ni ningún reverse proxy con TLS, deja la Clipboard API rota (el bug que ya documentó el autor) y los datos viajando sin cifrar.
• No hacer backup del volumen: toda la base vive en un archivo SQLite dentro del volumen gistly_data. Si no lo sacás con un docker cp de forma periódica, un disco corrupto se lleva todos los snippets de una.
• Generar el AUTH_SECRET a mano: usar una clave corta o predecible en vez de openssl rand -hex 32 debilita la sesión de autenticación del admin, aunque el password sea fuerte.

Preguntas Frecuentes

¿Qué es gistly y para qué sirve?

gistly es una aplicación open source para compartir fragmentos de código, creada por Fedya Serafiev como alternativa self-hosted a GitHub Gists. Sirve para pegar código, generar un link y compartirlo, pero con el control total del servidor, el dominio y los datos en tus propias manos.

¿Cómo instalar una alternativa self-hosted a GitHub Gists con Docker?

En el caso de gistly, se instala con 4 comandos: clonar el repositorio, crear un archivo .env con ADMIN_PASSWORD y AUTH_SECRET, y correr el script ./deploy.sh. La app queda disponible en el puerto 3000 con los datos persistidos en un volumen Docker. Relacionado: nuestro análisis de Microsoft y GitHub.

¿Qué diferencia a gistly de OpenGist?

gistly agrega un dashboard de Insights con heatmap de actividad, un command palette con Ctrl+K y una interfaz bilingüe EN/BG, funciones que el autor no encontraba en OpenGist. La base de datos de ambos es distinta en enfoque: gistly corre todo en un único archivo SQLite sin servidor de base de datos separado.

¿Qué incluye el dashboard de insights de gistly?

El dashboard de Insights de gistly incluye un heatmap de actividad de 26 semanas estilo GitHub, breakdown por lenguaje y por tag, y el gist más visto junto con el más reciente. Los datos se calculan con queries SQL optimizadas que evitan cargar el contenido completo de los archivos en memoria.

¿Es seguro usar gistly en modo single-admin?

El modo single-admin de gistly es seguro si cambiás la contraseña por defecto y generás el AUTH_SECRET con openssl rand -hex 32 en vez de dejar los valores de ejemplo del .env. Sin un reverse proxy con HTTPS adelante, de todas formas, la sesión de login viaja sin cifrar.

Conclusión

gistly no inventa nada que no exista ya en el ecosistema self-hosted, pero suma piezas concretas que faltaban: un dashboard de métricas real, un command palette que de verdad agiliza buscar snippets viejos, y un setup que cabe en un archivo SQLite y un script de deploy. Para quien ya usa OpenGist o sigue atado a GitHub Gists por costumbre, vale la pena mirar el repositorio y probarlo en un VPS chico antes de migrar nada en serio.

Lo que el artículo original no responde es qué tan maduro está el modo multi-usuario (todavía no existe, es un ítem del roadmap) ni qué pasa con la performance a gran escala, porque SQLite tiene límites conocidos de concurrencia que un proyecto personal rara vez estresa. Antes de poner esto en producción para un equipo, conviene revisar el código fuente, los issues abiertos y probar el backup del volumen SQLite con una restauración real, no solo confiar en que “funciona en el demo”.

Fuentes

• Fedya Serafiev en dev.to – relato original sobre el desarrollo de gistly, sus funciones y los bugs documentados
• github.com/fedya-dev/gistly – repositorio oficial del proyecto, mencionado por el autor como código fuente abierto bajo licencia MIT