Guía de zrok Nivel Medio: Comparticiones Públicas/Privadas, Reservas y Modos Backend por Santiago Soñora

“Hola, mundo” en zrok

El 'Hola, mundo' en zrok: habilitar tu entorno local con tu token de cuenta y compartir un servidor local básico públicamente.

📋 Copiar

zrok enable <tu_token_de_cuenta>
# Asumiendo que tienes un servidor web local en el puerto 8080
zrok share public 8080

Resultado:

Output

zrok is enabled!
Environment '...' is now enabled.

sharing 'public' with backend 'http://localhost:8080'
public share: https://<random_subdomain>.share.zrok.io

Comandos básicos

Familiarizarse con estos comandos es esencial para interactuar eficientemente con zrok:

Instalar zrok
📋 Copiar
```
curl -s https://install.zrok.io | bash
# O usando gestor de paquetes (ver docs)
```
Descarga e instala el binario de zrok. Sigue las instrucciones específicas para tu sistema operativo.
Habilitar entorno zrok con token
📋 Copiar
```
zrok enable <tu_token_de_cuenta>
```
Configura tu instalación de zrok local para usar tu cuenta. El token se obtiene del panel web de zrok.io.
Ver estado del entorno zrok
📋 Copiar
```
zrok status
```
Muestra si tu entorno zrok está habilitado, el token de cuenta asociado, y otra información de configuración local.
Deshabilitar entorno zrok
📋 Copiar
```
zrok disable
```
Limpia la configuración local del entorno zrok. No cierra comparticiones activas, deben cerrarse primero.
Compartir servidor HTTP públicamente
📋 Copiar
```
zrok share public http://localhost:3000
```
Crea una compartición pública para tu servicio web o API corriendo en el puerto 3000 local.
Compartir túnel TCP públicamente
📋 Copiar
```
zrok share public tcp://localhost:22
```
Crea una compartición pública a través de un túnel TCP al puerto 22 local (ej: SSH). Útil para acceso remoto no web.
Compartir carpeta como sitio web público
📋 Copiar
```
zrok share public --backend-mode web /ruta/a/tu/carpeta
```
Configura zrok para servir el contenido de una carpeta local como un sitio web estático accesible públicamente.
Compartir un recurso privado
📋 Copiar
```
zrok share private http://localhost:5000
```
Crea una compartición privada para tu servicio en el puerto 5000. Genera un token que otros usuarios zrok pueden usar para acceder de forma segura.
Crear un enlace reservado (público)
📋 Copiar
```
zrok reserve public --backend-mode http mi-app-dev
```
Reserva un endpoint público persistente con el nombre `mi-app-dev` y modo backend HTTP. Tendrá una URL estable.
Crear un enlace reservado (privado)
📋 Copiar
```
zrok reserve private --backend-mode tcp mi-ssh-privado
```
Reserva un endpoint privado persistente con el nombre `mi-ssh-privado` y modo backend TCP. Genera un token para acceso seguro.
Listar enlaces reservados
📋 Copiar
```
zrok list shares
```
Muestra una lista de todas tus comparticiones (activas o reservadas) en tu cuenta.
Eliminar un enlace reservado
📋 Copiar
```
zrok delete share nombre_del_enlace_reservado
```
Elimina un enlace reservado previamente creado. Asegúrate de que no esté activo antes de eliminarlo.
Usar/Activar un enlace reservado
📋 Copiar
```
zrok share reserved nombre_del_enlace_reservado --backend http://localhost:8080
```
Activa una compartición utilizando un enlace reservado existente, apuntándolo a tu servicio local (el modo backend ya está definido en la reserva).
Acceder a un recurso privado compartido
📋 Copiar
```
zrok access private <token_del_recurso_privado>
```
Permite que tu máquina local acceda al recurso compartido de forma privada, estableciendo un túnel seguro a través de la red de zrok. Necesitas estar habilitado con zrok.
Cerrar una compartición activa
📋 Copiar
```
zrok share shutdown <ID_de_la_comparticion>
```
Detiene una compartición que está activa. El ID se obtiene de la salida de `zrok share` o `zrok list shares`.

Ejemplo de configuración en ~/.zrok/zrok.yaml (parcial)

📋 Copiar

# Contenido del archivo de configuración por defecto (~/.zrok/zrok.yaml)
environments:
  - description: "Mi Entorno de Desarrollo"
    metrics: true
    
shares:
  - name: "mi-app-web"
    backendMode: http
    backend: "http://localhost:8000"
    public: true
  - name: "mi-servicio-ssh"
    backendMode: tcp
    backend: "tcp://localhost:22"
    private: true

Define un entorno y dos comparticiones (una pública HTTP, una privada TCP) en el archivo de configuración.

Iniciar túneles desde archivo de configuración
📋 Copiar
```
zrok start mi-app-web
```
Inicia la compartición definida bajo el nombre `mi-app-web` en tu archivo `~/.zrok/zrok.yaml`.
Iniciar todos los túneles desde archivo de configuración
📋 Copiar
```
zrok start --all
```
Inicia todas las comparticiones definidas en tu archivo `~/.zrok/zrok.yaml`.

Conceptos Clave

Comprender estos conceptos fundamentales te ayudará a dominar zrok de forma más organizada y eficiente:

Comparticiones Públicas vs Privadas:

Entender la diferencia fundamental. Las comparticiones públicas (`zrok share public`) generan una URL accesible para cualquier persona en internet, ideal para demos o APIs públicas. Las comparticiones privadas (`zrok share private`) generan un token único y solo son accesibles para usuarios zrok autenticados que usan `zrok access private`, ofreciendo una capa de seguridad adicional para recursos sensibles.
Modos Backend (HTTP, TCP, Web, TLS):

Definen cómo zrok interactúa con tu servicio local. El modo HTTP es para tráfico web y APIs. El modo TCP es para cualquier protocolo basado en TCP (SSH, RDP, bases de datos, etc.). El modo Web sirve archivos estáticos directamente desde una carpeta local. El modo TLS es para servicios que esperan tráfico TLS directamente.
Enlaces Reservados (Reserved Shares):

Permiten crear endpoints con nombres persistentes (`zrok reserve <nombre>`) que no cambian cada vez que inicias una compartición. A diferencia de las comparticiones temporales, los enlaces reservados mantienen su URL o token privado incluso cuando no están activos. Se activan posteriormente con `zrok share reserved <nombre>`. Crucial para URLs estables.
Gestión del Entorno zrok:

Comprender cómo `zrok enable` configura tu máquina local con un entorno único enlazado a tu cuenta zrok. `zrok disable` limpia esta configuración. El comando `zrok status` te ayuda a verificar el estado de tu entorno local y cuenta.
Acceso a Recursos Privados:

El mecanismo para consumir comparticiones privadas. Un usuario que quiera acceder a un recurso privado compartido debe tener zrok instalado y habilitado con su propia cuenta, y luego usar el comando `zrok access private <token_comparticion_privada>` para establecer una conexión segura a través de la red de zrok. La autenticación se maneja a través de zrok.
Arquitectura de zrok (Controlador, Frontend, Routers):

Una comprensión básica de los componentes. El Controlador es el 'cerebro' que gestiona cuentas, entornos y comparticiones. Los Frontends son los puntos de entrada en la red de zrok que reciben el tráfico. Los Routers son procesos (a menudo el agente zrok local) que establecen túneles seguros desde tu máquina a los Frontends para exponer tu servicio local.
Seguridad y Cifrado Extremo a Extremo:

zrok se centra en la seguridad. Los túneles suelen estar cifrados de extremo a extremo (desde el agente local hasta el Frontend de zrok y viceversa). Las comparticiones privadas añaden una capa de autenticación y aislamiento a nivel de zrok.
Archivo de Configuración (`~/.zrok/zrok.yaml`):

El archivo central para configurar tu entorno zrok, definir múltiples comparticiones (con sus nombres, modos backend, destinos locales, opciones públicas/privadas), y otras configuraciones avanzadas de forma persistente. Permite usar `zrok start` para iniciar comparticiones definidas.
Compartir Servicios con Docker:

Integrar zrok en flujos de trabajo de desarrollo con Docker. Compartir servicios que se ejecutan dentro de contenedores Docker, mapeando puertos o utilizando la red de Docker para permitir que zrok acceda al servicio contenerizado.
Service Endpoints:

Las direcciones locales (ej: `http://localhost:8080`, `tcp://localhost:22`) a las que el agente zrok se conecta para exponer tu servicio. Deben ser accesibles desde donde se ejecuta el agente zrok.

Casos de uso

Algunos ejemplos de aplicaciones prácticas donde se utiliza zrok:

Compartir de forma segura entornos de desarrollo o staging con acceso restringido (comparticiones privadas):

Exponer una aplicación web, API o herramienta interna que no debe ser accesible públicamente, compartiéndola de forma privada con un token para que solo usuarios autorizados (que usen `zrok access`) puedan conectarse.
Probar webhooks de servicios externos que requieren un endpoint estable y posiblemente privado:

Utilizar un enlace reservado (público o privado) para obtener una URL estable que puedas configurar en servicios de terceros para recibir webhooks en tu entorno local. Usar comparticiones privadas si el webhook contiene datos sensibles.
Ejecutar demos de aplicaciones o servicios con una URL persistente y fácil de recordar (enlaces reservados públicos):

Crear un enlace reservado público con un nombre amigable para tu demo o prototipo, activándolo solo cuando lo necesitas para una presentación.
Compartir acceso seguro a servicios internos no HTTP (ej: base de datos, herramienta de administración, RDP) (túnel TCP privado):

Utilizar un túnel TCP en modo privado para permitir que usuarios específicos accedan a servicios que no usan HTTP en tu red local, como servidores SSH, escritorios remotos o interfaces de administración de bases de datos.
Integrar la exposición de servicios locales en flujos de desarrollo con Docker:

Configurar zrok para compartir servicios que se ejecutan dentro de contenedores Docker, facilitando las pruebas y demostraciones de aplicaciones contenerizadas, incluyendo la exposición de múltiples servicios de una aplicación Docker Compose.
Permitir acceso seguro a recursos en tu red local para trabajo remoto o colaboración interna:

Utilizar comparticiones privadas de zrok (HTTP, TCP, etc.) para crear túneles seguros hacia servicios en tu red doméstica o de oficina, permitiendo a los miembros del equipo acceder a ellos de forma remota.
Compartir múltiples servicios de un proyecto local simultáneamente con diferentes configuraciones:

Definir múltiples comparticiones (con diferentes modos backend, destinos locales y niveles de seguridad pública/privada) en el archivo de configuración `~/.zrok/zrok.yaml` y activarlas todas con `zrok start --all`.
Servir carpetas locales como sitios web estáticos de forma pública o privada:

Utilizar el modo backend `web` (`zrok share public --backend-mode web /path` o `zrok share private --backend-mode web /path`) para exponer el contenido de una carpeta local como un sitio web estático.

Consejos para Principiantes

Aquí tienes algunas recomendaciones para facilitar tus inicios en zrok:

Entiende la Diferencia Clave: Compartición Pública vs Privada:

Es la decisión más importante. Las comparticiones públicas son convenientes para demos rápidas, pero expone tu servicio a internet. Para cualquier recurso sensible o que solo deba ser accedido por personas específicas, usa SIEMPRE `zrok share private`.
Elige el Modo Backend Correcto para Tu Servicio:

Asegúrate de que el modo backend (`--backend-mode http`, `tcp`, `web`, `tls`) coincida con el protocolo y la naturaleza del servicio que estás exponiendo. La mayoría de las apps web son HTTP, pero SSH es TCP, servir archivos es Web, etc.
Usa Enlaces Reservados para URLs/Tokens Estables:

Si necesitas una URL pública o un token privado que no cambie cada vez que inicias la compartición (para integraciones, demos recurrentes, acceso interno), usa `zrok reserve <nombre>`. Luego activas esa reserva con `zrok share reserved <nombre>`.
Sé Consciente de la Seguridad (¡Especialmente Público!):

Al compartir públicamente, tu servicio está expuesto. Asegúrate de que la aplicación local sea segura. Las comparticiones privadas añaden autenticación y aislamiento a nivel de zrok, pero tu aplicación local aún debe ser segura.
Aprovecha el Archivo de Configuración (`~/.zrok/zrok.yaml`):

Para gestionar múltiples comparticiones o configuraciones avanzadas, define tus comparticiones con nombre en este archivo. Luego puedes iniciarlas fácilmente con `zrok start <nombre>` o `zrok start --all`. Es mucho más limpio que la línea de comandos.
Explora la Integración con Docker si Desarrollas con Contenedores:

zrok tiene soporte nativo para compartir servicios que se ejecutan dentro de contenedores Docker. Revisa la documentación para los comandos y configuraciones específicos.
Practica el Acceso a Recursos Privados (`zrok access private`):

Si vas a usar comparticiones privadas, asegúrate de que tú y tus colaboradores sepan cómo usar el comando `zrok access private <token>` para establecer la conexión segura antes de intentar acceder al servicio local (ej: en el navegador para HTTP).
Lee la Documentación Oficial para Profundizar:

La documentación de zrok es un buen recurso para entender a fondo los modos backend, las opciones de seguridad en comparticiones privadas, la arquitectura y el autohosting si te interesa.
Usa `zrok list shares` para Ver tus Comparticiones:

Este comando te muestra todas tus comparticiones, tanto activas como reservadas, junto con sus IDs, nombres, tokens privados (si aplican) y URLs.

Herramientas relacionadas

Si te interesa zrok, también podrías explorar estas herramientas:

Recursos útiles

Amplía tus conocimientos con estos enlaces y materiales: