Desplegar la documentación
Este sitio como segundo servicio de Dokploy, con su propio dominio.
Este sitio es un proyecto aparte dentro del mismo repositorio: apps/docs.
Tiene su propio Dockerfile, su propio dominio y su propio ciclo de despliegue.
No comparte base de datos, ni secretos, ni sesiones con la aplicación. Es HTML servido: no hay nada que pueda filtrar porque no hay nada dentro.
Por qué va aparte
Podría vivir en /docs dentro de la aplicación, pero serían dos cosas
mezcladas:
- La aplicación es privada y exige iniciar sesión. La documentación técnica no tiene por qué estar detrás de esa puerta, y meterla ahí obligaría a abrir un agujero en la autorización para dejarla pasar.
- Un fallo del sitio de documentación no puede tumbar el CRM, ni al revés. Servicios separados, dominios separados, despliegues separados.
- La imagen del CRM lleva Prisma, Argon2 y sharp. La del sitio no necesita nada de eso.
Crear el servicio
Aplicación nueva en el mismo proyecto
Create Service → Application, dentro del proyecto royal-clean.
| Campo | Valor |
|---|---|
| Name | royalclean-docs |
| Provider | GitHub |
| Repository | El mismo repositorio |
| Branch | main |
| Build Type | Dockerfile |
| Dockerfile Path | apps/docs/Dockerfile |
| Build Context | . (la raíz del repositorio) |
El contexto es la raíz, no `apps/docs`
El lockfile y la configuración del workspace viven en la raíz, y la instalación
los necesita para comprobar que las versiones son exactamente las probadas. Con
el contexto puesto en apps/docs, la construcción falla al no encontrarlos.
Sin variables de entorno
No hace falta ninguna. Si tu instalación de Dokploy exige al menos una:
NODE_ENV=productionDominio
Domains → Add Domain
| Campo | Valor |
|---|---|
| Host | docs.royalcleancr.com |
| Port | 3200 |
| HTTPS | Activado |
| Certificate | Let's Encrypt |
El puerto es 3200, distinto del 3000 de la aplicación, para que ambos puedan convivir.
Healthcheck
| Campo | Valor |
|---|---|
| Path | / |
| Interval | 30 s |
| Timeout | 5 s |
| Retries | 3 |
| Start period | 10 s |
El margen de arranque es corto a propósito: el sitio no migra nada ni espera a ninguna base, así que si en diez segundos no responde es que algo va mal de verdad.
Cómo se escribe
El contenido vive en apps/docs/content/docs como archivos MDX, versionados
junto al código.
Eso es deliberado: la documentación se revisa en la misma pull request que el cambio que documenta. No hay una copia en otra herramienta que se quede vieja sin que nadie se entere.
Añadir una página
Crea el archivo con su encabezado:
---
title: Título de la página
description: Una frase que explica de qué va.
---
El contenido, en Markdown normal.Aparece sola en la navegación y en el buscador. No hay ninguna lista de enlaces que actualizar: el árbol se construye del propio contenido, porque una lista escrita a mano se desincroniza el día que alguien añade una página con prisa.
Ordenar una sección
Cada carpeta lleva su meta.json:
{
"title": "Despliegue",
"description": "Poner el sistema en producción",
"pages": ["panorama", "dokploy", "variables"]
}Lo que no se nombra aparece después, por orden alfabético.
Componentes disponibles
Deliberadamente pocos. Cuantos más se ofrecen, más se usan por adorno y menos se lee el texto.
<Callout type="warn" title="Un título opcional">
El texto del aviso.
</Callout>Tipos: sin tipo (informativo), warn y error.
Trabajar en local
pnpm --filter royal-clean-docs devArranca en el puerto 3200, así que puede convivir con la aplicación en el 3000. Los cambios en el contenido se ven al instante.
Para comprobar que compila antes de subirlo:
pnpm --filter royal-clean-docs buildEl buscador
Índice estático construido desde el propio contenido en tiempo de compilación. Busca en el texto completo, no sólo en los títulos, y respeta los acentos.
No hay servicio externo que contratar, ni clave que rotar, ni una dependencia más que pueda caerse. Para un sitio de esta talla, buscar en el índice del navegador es instantáneo.
Se abre con Ctrl + K o ⌘ + K.