El 18 de septiembre ClewWiki no tenía ni una sola versión publicada. Cuando escribí sobre los claims de página, no había imagen ni paquete npm: solo se podía compilar desde el código fuente. Diecisiete días después salió la versión 0.9.0: el décimo tag seguido, la imagen está en GHCR y el servidor MCP se instala con npx.
Este artículo es para quienes eligen una wiki para su equipo y quieren tenerla en su propia infraestructura. Sin agentes ni MCP: eso tiene su propio artículo. Aquí va solo lo que necesitan las personas: cómo instalarla, cómo traer a los compañeros, cómo mover las páginas existentes y en qué el proyecto todavía queda por detrás de herramientas con años de uso.
Qué hace falta para levantarla#
Docker con Compose, git y openssl. Nada más. Ni Redis, ni servidor de correo, ni cuenta en un proveedor de inicio de sesión externo. Todo el stack es la aplicación y PostgreSQL 16.
git clone https://github.com/Dodecaidr/clewwiki.git
cd clewwiki
cp .env.example .env && chmod 600 .env
sed -i "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(openssl rand -hex 32)|" .env
sed -i "s|^BETTER_AUTH_SECRET=.*|BETTER_AUTH_SECRET=$(openssl rand -base64 48)|" .env
docker compose up -d
docker compose logs web | grep "setup token"En macOS se escribe sed -i '' en lugar de sed -i. Después, http://localhost:3000, el token de configuración del log y el primer administrador. No hay contraseñas por defecto, así que no hay nada que adivinar.
En un servidor hacen falta dos cosas más: BETTER_AUTH_URL con la dirección pública https:// y un proxy inverso delante de la aplicación. La aplicación habla HTTP plano y publica su puerto solo en 127.0.0.1, de modo que el TLS queda en tus manos. docs/deploy.md explica Caddy, Traefik y nginx.
Las pocas dependencias son intencionadas. En un equipo pequeño, la wiki suele montarla alguien que no tiene ni el tiempo ni las ganas de administrar cuatro servicios. Cada contenedor extra es una cosa más que se cae un sábado.
Cómo traer a la gente sin servidor de correo#
No hay registro abierto. Una persona entra en la wiki por uno de tres caminos.
Un enlace de invitación. Un administrador escribe una dirección y un rol en Members y recibe un enlace. Se muestra una vez, funciona una vez y dura siete días. No se envía ningún correo: el enlace lo entregas tú, por chat o en persona. Por eso una instancia sin SMTP está completa. En la base de datos solo se guarda el hash del enlace.
Una solicitud para unirse. Si los administradores la activan, la página de inicio de sesión ofrece Ask to join. La persona deja nombre, dirección, contraseña y una nota, y ve «pendiente de aprobación» hasta que un administrador la aprueba con un rol concreto o la rechaza. Nadie se deja entrar a sí mismo. Cinco solicitudes por hora por dirección de cliente.
Inicio de sesión único con OpenID Connect. Bastan tres variables (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET) para que aparezca un botón en la página de inicio de sesión. El acceso con contraseña sigue funcionando, así que si el proveedor cae, el administrador no se queda fuera. El proveedor decide quién es alguien, no si entra: un perfil sin email_verified se rechaza, OIDC_ALLOWED_EMAIL_DOMAINS acota por dominio y la pertenencia sigue siendo decisión del administrador hasta que activas explícitamente OIDC_SIGN_UP.
Hay tres roles. El administrador gestiona miembros, tokens de agentes y espacios. El editor escribe páginas, participa en discusiones y revisa los cambios de los agentes. El viewer, añadido en 0.6, es para quienes leen la wiki: un product manager, un tester, el ingeniero de un cliente. Lee todo lo que puede ver (páginas, discusiones, historial, búsqueda, exportaciones) y no cambia nada. El límite está donde está el de un token de agente de solo lectura: una petición que necesita más recibe 403. Al último administrador no se le puede degradar ni eliminar.
Antes, una contraseña olvidada se resolvía eliminando a la persona e invitándola de nuevo, lo que creaba otra cuenta. Ahora un administrador genera un enlace de restablecimiento: de un solo uso, válido 24 horas, guardado como hash, y al usarse cierra todas las sesiones de esa cuenta.
Varios equipos en un mismo servidor#
La 0.8 trajo las organizaciones. Una instancia aloja varias, cada una con sus miembros, espacios, tokens de agentes, administradores y ajustes. Una cuenta puede pertenecer a varias y cambiar entre ellas desde el menú junto al logo, y cada organización tiene su propia entrada en /o/<dirección>.
Dentro de una organización hay espacios por proyecto, también restringidos, que solo ven sus miembros. Si quitas a alguien de una organización, su cuenta y su pertenencia a las demás se mantienen.
Para un estudio o una agencia que lleva la documentación de varios clientes, es justo el caso que antes obligaba a montar una wiki por cliente.
Cómo mover lo que ya tienes escrito#
Nadie elige una wiki a la que no se puede mudar. Toda importación a ClewWiki pasa por un paso intermedio: ves el árbol de páginas que resultaría, la ruta de cada página, su Markdown y una nota sobre lo que no se pudo convertir. Hasta que pulsas el botón, no se crea nada.
Desde dónde puedes mudarte:
- Un espacio de Confluence: Cloud mediante la REST API v2, tu propio Server o Data Center mediante la v1. Se trasladan la jerarquía, los títulos, las listas, las tablas, los bloques de código con su lenguaje, los paneles informativos, los bloques desplegables, los enlaces entre páginas importadas y las imágenes. Con los archivos activados, también llegan los adjuntos, con sus versiones anteriores, fechas y comentarios.
- Una exportación de Notion y un archivo de Markdown, con las imágenes y los archivos que enlazan sus páginas.
- PDF de hasta 200 MB.
La salida es igual de amplia: una página se exporta a Markdown o HTML, un espacio a un ZIP, con sus archivos si quieres. Las páginas se guardan como Markdown, así que irse de ClewWiki es descargar un archivo.
Aquí importan las limitaciones, y las diré claramente. De Confluence no se leen los comentarios, las etiquetas, los permisos ni el historial de páginas. Una macro sin equivalente en Markdown (listas de Jira, árboles de páginas, inclusiones, gráficos) se convierte en una nota visible con su nombre en lugar de contenido funcional. La importación desde Server y Data Center se ha probado contra una instancia pública real y contra fixtures, pero no tiene años de uso detrás. Si tu wiki depende de macros y del Marketplace, la mudanza no será indolora, y docs/compare.md en el repositorio lo dice tal cual.
Por qué el tema es actual: Atlassian pone fin a Data Center el 28 de marzo de 2029, cuando esas instalaciones pasan a ser de solo lectura, y no se lo vende a clientes nuevos desde la primavera de 2026. Los equipos que tenían su wiki en casa por motivos de seguridad o legales siguen teniendo esos motivos. Lo que se va es el producto.
Archivos junto a la documentación#
Desde la 0.7 se puede adjuntar a una página un archivo de cualquier tipo: una build, un instalador, una especificación. La lógica la tomé de cómo los equipos publican de verdad sus versiones.
Sube un archivo con un nombre que la página ya tiene y obtienes la siguiente versión bajo el mismo enlace. El enlace siempre sirve la última, así que puedes pegarlo una vez en las release notes y olvidarte; ?version=3 fija una concreta. Los mismos bytes por segunda vez no añaden nada. Restore convierte una versión antigua en la última añadiéndola como nueva, de modo que una versión que alguien ya descargó nunca cambia.
Quien sigue la página o el espacio ve la nueva versión en su bandeja de entrada. Los archivos viven en un disco local o en cualquier bucket compatible con S3. Un pipeline de build publica uno con un solo comando:
curl -fsS -X PUT --data-binary @dist/app-2.4.1.apk \
-H "Authorization: Bearer $CLEWWIKI_TOKEN" \
"https://wiki.example.com/api/v1/pages/$PAGE_ID/files/app-2.4.1.apk?note=Signed%20build"El token necesita el scope pages:write y nada más. Repetir la misma petición devuelve 200 en lugar de 201 y no crea una versión nueva, así que los reintentos en CI son seguros.
Incidencias y hojas de cálculo dentro de las páginas#
En la 0.8 la wiki aprendió a mirar hacia fuera.
Gestores de incidencias. YouTrack, Jira y cualquier tracker con claves tipo KEY-123. Un administrador de la organización indica la dirección, las claves de proyecto y el nombre de una variable de entorno con un token de lectura. El token en sí nunca entra en la base de datos. A partir de ahí, las claves de incidencias en el texto se vuelven enlaces y la página lista las incidencias que menciona, con estado y responsable. Desde el editor puedes insertar una incidencia completa, con descripción y comentarios, o una tabla de incidencias a partir de una consulta de YouTrack o de JQL.
Una advertencia que no voy a esconder: los clientes de YouTrack y Jira están probados contra respuestas de API grabadas, todavía no contra una instancia real. Si tienes un proyecto de pruebas, tus comentarios serán muy bienvenidos.
Hojas de cálculo. El diálogo Import table or document acepta un libro de Excel (.xlsx), CSV y TSV, incluidos los separados por punto y coma como los guarda Excel en ruso o en alemán, e inserta las hojas como tablas. Las celdas llegan tal como se ven: una fórmula como su resultado, una fecha como fecha, las hojas ocultas se omiten. Un enlace a Google Sheets o Google Docs compartido con «cualquier persona con el enlace» también funciona. En sentido inverso, una página con tablas se exporta a .xlsx: una hoja por tabla, con el nombre del título que tiene encima y la fila de cabecera en negrita e inmovilizada. Todo es código propio del proyecto, sin librería de hojas de cálculo. El antiguo .xls binario no se lee.
Dónde ve el equipo qué se publica#
La versión 0.9.0, publicada el 5 de octubre, añade a cada espacio una sección Development. Responde a la pregunta que los equipos pequeños hacen en cada llamada: «¿esto ya está en la release?»
La sección lee el repositorio git vinculado al espacio y mantiene una línea de trabajo por cada rama: su último commit, cuánto va por delante y por detrás de la rama principal, si está fusionada, si se borró. Cada línea lleva un objetivo, sus incidencias con su estado, una página de documentación y «problemas», es decir, discusiones sobre lo que la bloquea. Cuando un problema se resuelve, la decisión se escribe como página en la documentación de esa línea.
Lo que me parece más útil es la lista resaltada de trabajo fusionado sin release: cambios que ya están en la rama principal pero que ninguna release planificada recogió. Son justo las cosas que luego aparecen como «¿y eso llegamos a publicarlo?». Una release se niega a marcarse como publicada mientras tenga líneas sin fusionar. Se puede publicar igualmente, pero eso queda en la auditoría junto con lo que se quedó fuera.
Qué no hay todavía#
Una lista honesta, la misma que tiene el README:
- SAML y LDAP. El inicio de sesión único solo habla OpenID Connect, sin sincronización con directorio.
- App móvil. La interfaz web funciona en el teléfono; no hay cliente nativo.
- Años en producción. El primer tag es del 18 de septiembre de 2026. Los vecinos de
docs/compare.mdllevan entre tres y más de veinte años. Las migraciones entre versiones 0.x son frecuentes por ahora, y hacer copia de la base de datos antes de actualizar no es una formalidad. - Una comunidad o una empresa detrás. Es un proyecto de código abierto de un solo autor. Si necesitas un proveedor con SLA, ClewWiki no es para ti ahora mismo.
Lo que obtienes a cambio: una sola edición bajo AGPL-3.0, donde todo lo anterior es gratis y no está escondido tras un plan por usuario, y un stack que se levanta con un comando. La interfaz está en inglés y en ruso.
Por dónde empezar#
Levanta una instancia en tu portátil con los comandos de arriba, importa un espacio pequeño y mira la pantalla intermedia. En diez minutos verás si tu wiki se muda o choca con las macros. El código, la documentación y el gestor de incidencias están en el repositorio de GitHub, y la visión general del proyecto, en la página de ClewWiki.
Si tu equipo tiene agentes de IA conectados a su wiki, o pronto los tendrá, el siguiente artículo cuenta qué obtienen en la 0.9.
