Autohospede Meratyn

Meratyn es un servicio Node portátil para intercambiar proyectos .meratyn.json. El monorepo incluye un espacio de trabajo de gestión autenticado, gestión de versiones, colecciones, tokens personales de API, miniaturas y el contrato HTTP usado por el diálogo Share de Meratyn desktop.

Ya no depende de Cloudflare:

• Bun sirve el shell SPA de TanStack Start y la API desde un solo proceso.
• SQLite almacena usuarios, metadatos, colecciones y hashes SHA-256 de los tokens de API.
• Un sistema de archivos montado almacena versiones inmutables de proyectos y miniaturas.
• Clerk sigue siendo opcional y se limita a la consola de gestión. Las superficies de visor, escritorio y embed permanecen locales y no heredan la autenticación de gestión; Meratyn no añade otro proveedor de identidad alojado para esas superficies.
• Un contenedor nginx ligero sirve el visor local de Meratyn usado por los mapas incrustados y los enlaces «Open in Meratyn».

Ejecute con Docker Compose

Se requiere Docker Desktop u otro Docker Engine con Compose v2.

cp .env.example .env
docker compose -f docker/compose/admin.yaml up --build -d
docker compose -f docker/compose/admin.yaml ps

Abra https://admin.mappview.mapptech.com.co. El visor de Meratyn se ejecuta en https://mappview.mapptech.com.co. El perfil Compose por defecto crea una cuenta local llamada local-mapper para acceso de API y pruebas usando el token ADMIN_LOCAL_TOKEN exclusivo de desarrollo del archivo .env copiado. El navegador permanece sin sesión iniciada por defecto y muestra solo la puerta de autenticación. Para abrir el espacio de trabajo sin conexión sin Clerk, defina ADMIN_BROWSER_TOKEN con el mismo valor que ADMIN_LOCAL_TOKEN y recompile. Si las claves de Clerk están presentes, la sesión de Clerk tiene precedencia sobre ese respaldo y el espacio de trabajo usa el inicio de sesión modal y el menú de usuario de Clerk.

No reutilice el token de ejemplo fuera del desarrollo en loopback. Reemplácelo con un valor aleatorio largo mappview_… antes de exponer el servicio a otra máquina.

Para detener el servicio sin borrar datos:

docker compose -f docker/compose/admin.yaml down

Los datos del proyecto persisten a través del volumen lógico management-data. Su nombre de volumen Docker por defecto es mappview-management-data, y la base de datos se guarda en /data/admin.db. Defina ADMIN_DATA_VOLUME o ADMIN_DB_PATH cuando quiera intencionalmente elegir otra ubicación. Para eliminar explícitamente los datos locales de prueba, añada --volumes al comando down.

Para publicar y gestionar archivos GIS locales, inicie el perfil opcional headless de GeoNode y GeoServer:

docker compose -f docker/compose/admin.yaml --profile hosted-layers up --build -d

Reemplace primero las contraseñas de desarrollo de .env.example. Vea Desplegar capas alojadas para la topología de servicios, la configuración y los requisitos de producción.

Cargue las capas vectorial y ráster de muestra

Cuando el perfil hosted-layers esté saludable, siembre dos pequeños ejemplos públicos:

bun run seed:online-layers

El comando lee ADMIN_LOCAL_TOKEN del shell o del .env de la raíz del repositorio, sube tests/fixtures/sample-colombia-cities.geojson y tests/fixtures/striped.tif, espera la publicación e imprime sus URLs de gestión de Share. Es idempotente para las muestras que creó previamente. También falla si la publicación cambia el título introducido por el usuario o devuelve un detalle interno de publicación en el modelo público de la capa.

Configuración

Defina las sustituciones de Compose en un archivo .env local o en el shell:

CORS_ORIGINS incluye por defecto el visor local y los orígenes de la WebView de Tauri, de modo que el visor y una compilación desktop configurada para este autohospedaje puedan obtener el JSON de proyectos de Share. Si alguno de los puertos publicados cambia, actualice VIEWER_URL, APP_ORIGIN y CORS_ORIGINS juntos antes de recompilar.

STUDIO_PASSWORD activa el estudio de demostración en /studio: una sola contraseña, sin cuentas y con una cookie de sesión de 12 horas. El estudio fija los valores de escenario de los showcases en vivo (inundación por lluvia en Mocoa, calidad del aire en Bogotá y la ciudad inteligente de Medellín). Sus capas son públicas en /api/studio/feeds/<feed>/layers/<layer>, combinan los valores guardados con datos en vivo de Open-Meteo y se generan una vez por ciclo de 5 segundos, así que un cambio guardado llega a un caso abierto en segundos. Cada capa lleva un ETag, de modo que los visores omiten las capas que no cambiaron desde el ciclo anterior. Los proyectos de showcase cargan estas capas desde STUDIO_FEED_ORIGIN en scripts/assets/showcases/studio.ts; cámbielo y recompile los showcases para servirlas desde otro despliegue.

Las aplicaciones del navegador también compilan enlaces hacia los servicios circundantes de Meratyn. Los valores locales se listan en .env.defaults; anúlelos cuando los servicios vivan en dominios distintos. Los valores por defecto de localhost solo se resuelven en la máquina donde corre Compose —antes de exponer el despliegue, defina cada VITE_MAPPVIEW_*_URL con su origen HTTPS público; de lo contrario los enlaces, incrustaciones y enlaces de ayuda generados apuntarán a la máquina del usuario:

La compilación Vite de escritorio lee estas variables tanto del .env a nivel del repositorio como del entorno local de la app. Son valores de tiempo de compilación, así que recompile las imágenes del navegador después de cambiarlos. El widget Python usa MAPPVIEW_VIEWER_URL (y acepta VITE_MAPPVIEW_VIEWER_URL como alternativa).

En un runtime Docker, MAPPVIEW_CAPABILITIES es una política de autoridad opcional, separada por comas, que comparten el visor y el sidecar. Úsela junto con un perfil de interfaz de quiosco o aula cuando deba denegar acciones; no confíe solo en ocultar el menú. El sidecar requiere processing:run en el despliegue y processing:sidecar en la política de aplicación. Consulte capacidades de despliegue.

El propio documento del registro confiable se obtiene en tiempo de ejecución. Una vez que su URL se ha compilado en el visor, publicar nuevas entradas versionadas en esa misma URL no requiere otro despliegue del visor.

Los puertos por defecto solo se vinculan a loopback porque el token de arranque por defecto es una credencial conocida de desarrollo local. Antes de definir cualquiera de las direcciones de enlace con 0.0.0.0 u otra interfaz accesible externamente, reemplace ADMIN_LOCAL_TOKEN con un valor aleatorio largo o configure Clerk. Defina ADMIN_BROWSER_TOKEN solo en una máquina local confiable: incrusta esa credencial en el paquete del navegador y, por tanto, jamás debe usarse en un despliegue expuesto a internet.

Autenticación con Clerk

El plan Hobby de Clerk basta para pruebas locales y despliegues pequeños. No requiere tarjeta de crédito e incluye las interfaces preconstruidas de inicio de sesión, registro y perfil de usuario. Copie .env.example a .env, cree una aplicación en el panel de Clerk y complete:

CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
CLERK_AUTHORIZED_PARTIES=http://localhost:8787,http://127.0.0.1:8787,http://localhost:5174,http://127.0.0.1:5174

Luego recompile porque TanStack Start y Vite compilan la clave publicable en el paquete del navegador:

docker compose -f docker/compose/admin.yaml up --build -d

El frontend usa @clerk/tanstack-react-start con ClerkProvider, un SignInButton modal, UserButton y getToken() de sesión para las peticiones de API autenticadas. El servicio Node verifica esos tokens con @clerk/backend. Ninguna clave de Clerk está comprometida al repositorio.

Los dos orígenes 5174 autorizan el servidor de desarrollo dividido iniciado por bun run dev:admin; el lanzador además los fusiona automáticamente en CLERK_AUTHORIZED_PARTIES. Mantenga los orígenes 8787 para la compilación Compose de mismo origen. Añada cualquier otro origen de navegador que pueda emitir tokens de Clerk, incluidas ambas variantes de hostname cuando su equipo use ambas, o la API rechazará correctamente esas sesiones con HTTP 401.

Autenticación de producción

Para un despliegue no local, defina explícitamente ADMIN_LOCAL_TOKEN y ADMIN_BROWSER_TOKEN con valores vacíos, proporcione CLERK_PUBLISHABLE_KEY, y defina CLERK_SECRET_KEY o CLERK_JWT_KEY. Defina CLERK_AUTHORIZED_PARTIES, APP_ORIGIN y CORS_ORIGINS con los orígenes reales del navegador, del visor y de la WebView de Tauri. Defina ADMIN_BIND_ADDRESS según la ruta de red del proxy inverso y ponga TLS frente al puerto 8787. Defina ADMIN_TRUST_PROXY=true solo cuando Share sea alcanzable exclusivamente a través de un proxy que reemplace CF-Connecting-IP o X-Forwarded-For; esto preserva los conteos de vistas por cliente sin permitir que clientes directos falsifiquen su dirección.

El archivo Compose está deliberadamente optimizado para pruebas locales. Los operadores de producción deberían usar secrets en lugar de valores de entorno planos y deberían respaldar el volumen /data.

Desarrolle sin Docker

Use Bun 1.4.2 o posterior:

bun install
bun run dev:admin

El comando inicia la API de gestión en el puerto 8787 y el frontend Vite en https://admin.mappview.mapptech.com.co, con vigilancia de fuentes para ambos procesos. Carga el .env de la raíz del repositorio y mapea CLERK_PUBLISHABLE_KEY a Vite; cuando Clerk no está configurado, suministra en cambio un token local de desarrollo coincidente. El lanzador reutiliza una API de gestión saludable que ya escuche en el puerto 8787, como el servicio de Docker Compose. El servicio guarda los datos locales en services/admin/data/admin.db y services/admin/data/objects; el directorio es ignorado por Git. Defina ADMIN_BOOTSTRAP_TOKEN o VITE_ADMIN_LOCAL_TOKEN antes de iniciar para sobrescribir el token de desarrollo por defecto.

Ejecute la suite portable de integración con:

bun run test:admin

Verifica el shell TanStack Start compilado, el endpoint de salud, la publicación, descargas sin procesar, versiones, forks, miniaturas, colecciones, acceso privado y tokens personales hasheados.

Con la pila Compose en ejecución, verifique la paridad de rutas, la petición al visor local, los anchos móviles requeridos y la accesibilidad con:

bun run test:admin:e2e

Conecte Meratyn desktop

Defina la variable de la compilación desktop/web con su origen de gestión:

VITE_MAPPVIEW_SHARE_URL=http://localhost:8787

Las compilaciones desktop empaquetadas usan browser fetch para orígenes Share personalizados. Por tanto, el servicio Share debe incluir tauri://localhost y http://tauri.localhost en CORS_ORIGINS; los valores por defecto de Compose ya lo hacen.

Los usuarios crean un token personal bajo Settings de Meratyn, luego pegan ese token mappview_… en Settings de Meratyn. Las versiones de origen de los proyectos son inmutables; restaurar una versión crea una nueva.

Respaldo y restauración

Respalde el volumen completo /data como una sola unidad. admin.db contiene los metadatos, mientras que objects/ contiene el JSON de proyectos y las miniaturas. Restaurar solo una de las dos partes dejará el inventario de proyectos y los archivos guardados inconsistentes.