Configurar dominios personalizados

Configuración y ajustes

Antes de cualquier paso, lea Antes de comenzar y Conceptos básicos del terminal. Estas instrucciones suponen que abrió el monorepo supastack completo en VS Code; su paquete raíz.json marca la raíz del repositorio. En los comandos pnpm, un paquete de espacio de trabajo es una aplicación o una carpeta de código compartido; En el producto, un espacio de trabajo es el contenedor de datos y el límite de seguridad de un equipo. corepack pnpm --filter ... selecciona un paquete del monorepo mientras los comandos se ejecutan desde su raíz. Si abrió solo una carpeta sincronizada para dispositivos móviles o de escritorio, no contiene el backend web, la configuración de Docker ni los scripts raíz: ejecute el backend desde este monorepo o un servidor alojado accesible y use los propios scripts de la carpeta de la plataforma. Una variable de entorno es una configuración con nombre almacenada en un archivo .env local o en su panel de hosting; reinicie la aplicación correspondiente después de cambiarla y mantenga los secretos del servidor fuera de los valores NEXT_PUBLIC_ y EXPO_PUBLIC_.

1. Abra apps/web/.env.local y use CUSTOM_DOMAINS_PROVIDER=local para obtener una vista previa de la pantalla Dominios sin cambios en DNS.

2. Para un nombre de host de cliente real, configure Cloudflare para SaaS con su propia zona, un token API limitado a esa zona y el objetivo CNAME; introduzca los valores exclusivos del servidor en el servidor web, no en el navegador.

3. Ejecute Web con corepack pnpm --filter @supastack/web dev y abra Configuración → Dominios como propietario/administrador del espacio de trabajo. Previsto: el adaptador local activa un dominio de prueba inmediatamente; el adaptador Cloudflare espera los registros DNS mostrados.

Configura CUSTOM_DOMAINS_PROVIDER=cloudflare con CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID y CUSTOM_DOMAIN_CNAME_TARGET. El token de API necesita permiso SSL y Certificates:Edit en la zona (la API Custom Hostnames está en /zones/{zone_id}/custom_hostnames). El destino CNAME es un nombre de host de tu zona de Cloudflare —por ejemplo customers.example.com— que resuelve a la aplicación desplegada.

Añade un registro DNS en la zona que apunte el destino CNAME al origen (el origen alternativo según la terminología de Cloudflare for SaaS). Cloudflare emite para cada nombre de host personalizado un registro TXT de DCV y un registro TXT opcional de propiedad; la pantalla de configuración muestra a los clientes exactamente qué registros deben crear.

Para desarrollo local, usa CUSTOM_DOMAINS_PROVIDER=local, que marca cada nombre de host como activo de inmediato con el destino customers.localhost. CUSTOM_DOMAINS_PROVIDER=off (el valor predeterminado) oculta los controles de esta sección.

CUSTOM_DOMAINS_PROVIDER=cloudflare
CLOUDFLARE_API_TOKEN=cf_token_with_ssl_edit
CLOUDFLARE_ZONE_ID=zone_id
CUSTOM_DOMAIN_CNAME_TARGET=customers.example.com

Comandos para copiar

Siga los comentarios para ver en qué carpeta se ejecuta un comando. Si dos terminales están etiquetados, abra dos ventanas de terminal y mantenga el primer comando ejecutándose mientras usa el segundo.

corepack pnpm --filter @supastack/web dev

Flujo de implementación

Los owners y admins del espacio de trabajo gestionan dominios en Configuración → Dominios (cinco por espacio de trabajo). Los clientes apuntan un registro CNAME de su nombre de host al destino CNAME, añaden los registros TXT mostrados para la propiedad y la validación del certificado, y luego pulsan Actualizar estado. Cuando Cloudflare indica que el nombre de host está activo, pasa a ser un origen de confianza para la autenticación en ese despliegue y el nombre/logotipo del espacio de trabajo da marca al chrome de la aplicación en ese nombre de host.

Los dominios raíz (apex) no pueden ser CNAME en la mayoría de proveedores DNS: los clientes deben usar un subdominio como portal.example.com o un proveedor con aplanamiento de CNAME. Las cookies se limitan a cada host, así que un dominio de cliente tiene un inicio de sesión separado; el inicio de sesión único entre dominios personalizados queda fuera del alcance.

Verificación y solución de problemas

Si Cloudflare permanece pendiente, compare los registros CNAME y TXT del cliente con los valores exactos que se muestran en la tarjeta de dominio y permita que DNS se actualice. Utilice un subdominio cuando el proveedor DNS no pueda aplanar un dominio raíz CNAME. Si el menú no está, verifique que la función esté habilitada y que el usuario que inició sesión sea propietario o administrador del espacio de trabajo.

Un estado pendiente durante mucho tiempo suele significar que falta el CNAME del cliente o que aún se está propagando: vuelve a comprobar los registros DNS que aparecen en la tarjeta del dominio. Un estado de traslado o fallo significa que Cloudflare ya no puede resolver el nombre de host hacia la zona; elimínalo y vuelve a añadirlo. Los datos de validación se guardan como JSON del proveedor para que futuras formas de validación de Cloudflare no requieran un cambio de esquema.