Guía de Railway Nivel Medio: Despliegue, Servicios, Env Vars y Dominios por Santiago Soñora

“Hola, mundo” en Railway

Desplegar una aplicación web básica (ej. Node.js, Python, etc.) en Railway conectada a tu repositorio Git con la CLI.

📋 Copiar

railway init # Crea un nuevo proyecto en Railway y lo enlaza con tu directorio local
railway link # (Opcional si ya tienes un proyecto) Enlaza con un repositorio de GitHub
railway up # Detecta tu código, lo construye y lo despliega en Railway

Resultado:

Output

🚀 Proyecto desplegado exitosamente en https://myapp-xxxx.up.railway.app

Comandos básicos

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

Instalar Railway CLI
📋 Copiar
```
npm install -g @railwaydev/cli
```
Instala la interfaz de línea de comandos de Railway globalmente.
Login en Railway CLI
📋 Copiar
```
railway login
```
Autentica tu CLI de Railway con tu cuenta a través del navegador.
Inicializar un nuevo proyecto Railway
📋 Copiar
```
railway init
```
Crea un nuevo proyecto en Railway y lo asocia al directorio actual de tu máquina local. Útil para empezar desde cero.
Enlazar proyecto local a uno existente en Railway
📋 Copiar
```
railway link
```
Conecta tu directorio local con un proyecto existente en tu cuenta de Railway. Te pedirá seleccionar un proyecto de la lista.
Enlazar a un repositorio de GitHub
📋 Copiar
```
railway link --github
```
Vincula tu proyecto Railway con un repositorio en GitHub para habilitar despliegues automáticos cada vez que haces un push.
Desplegar el proyecto
📋 Copiar
```
railway up
```
Detecta automáticamente tu código (lenguaje, Dockerfile), lo construye y lo despliega en tu proyecto Railway enlazado. Si está enlazado a Git, usa el código local; si no, usa el del repositorio Git enlazado.
Desplegar una rama específica de Git
📋 Copiar
```
railway up --branch feature/nueva-funcionalidad
```
Despliega la aplicación desde una rama específica de tu repositorio Git enlazado en lugar de la rama por defecto.
Ver estado del proyecto actual
📋 Copiar
```
railway status
```
Muestra información detallada sobre el proyecto Railway asociado a tu directorio actual, incluyendo servicios, estados de despliegue, IDs, etc.
Ver logs del proyecto o un servicio
📋 Copiar
```
railway logs
```
Muestra los logs en tiempo real de todos los servicios en tu proyecto. Usa `railway logs --service <id_o_nombre_servicio>` para ver logs de un servicio específico.
Abrir panel web del proyecto
📋 Copiar
```
railway open
```
Abre la interfaz web de Railway para el proyecto asociado en tu navegador por defecto.
Añadir un servicio gestionado (base de datos, etc.)
📋 Copiar
```
railway add
```
Inicia un asistente interactivo para añadir servicios gestionados a tu proyecto, como bases de datos (PostgreSQL, MySQL, MongoDB, Redis), colas de mensajes, etc. Genera variables de entorno de conexión.
Ver variables de entorno de un servicio
📋 Copiar
```
railway env
```
Lista todas las variables de entorno configuradas para el servicio (o proyecto) actual. Incluye las generadas automáticamente por Railway y las que añadas manualmente.
Añadir una variable de entorno
📋 Copiar
```
railway env add NOMBRE_VARIABLE "valor de la variable"
```
Añade o actualiza una variable de entorno con el nombre y valor especificados para el servicio actual.
Eliminar una variable de entorno
📋 Copiar
```
railway env remove NOMBRE_VARIABLE
```
Elimina la variable de entorno especificada del servicio actual.
Ver uso de recursos del proyecto
📋 Copiar
```
railway usage
```
Muestra el consumo actual y el histórico de recursos (CPU, RAM, Storage, etc.) por proyecto y por servicio, útil para monitorear costos.
Conectarse a la base de datos (CLI)
📋 Copiar
```
railway connect
```
Permite establecer una conexión directa a la base de datos gestionada (si existe) asociada a tu proyecto desde la terminal. Soporta diferentes tipos de bases de datos.

Conceptos Clave

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

Infraestructura Abstraída:

Railway se encarga de la complejidad de la infraestructura subyacente (servidores, orquestación, balanceo de carga, redes, etc.), permitiendo a los desarrolladores desplegar aplicaciones sin necesidad de configurar o administrar servidores. Te enfocas solo en tu código.
Servicios (Aplicación y Base de Datos):

Un proyecto en Railway se compone de Servicios. Estos pueden ser tu aplicación (el código que despliegas, construido desde Git o Dockerfile) o servicios gestionados de bases de datos (PostgreSQL, MySQL, MongoDB, Redis) o otros add-ons que Railway administra por ti.
Despliegues Automáticos (desde Git o Dockerfile):

Integrando tu proyecto Railway con un repositorio Git, puedes configurar despliegues automáticos cada vez que haces un push a una rama específica. Railway detecta tu código (usando Buildpacks) o tu Dockerfile, lo construye y lo despliega. También puedes desplegar imágenes Docker existentes.
Variables de Entorno y Secretos:

Gestionar la configuración específica del entorno de la aplicación y los secretos (credenciales de base de datos, claves API) de forma segura y desacoplada del código, utilizando el sistema de variables de entorno de Railway (accesible vía CLI y panel web).
Conexión y Comunicación entre Servicios:

Los servicios dentro del mismo proyecto Railway (ej: tu aplicación backend y tu base de datos PostgreSQL) pueden comunicarse entre sí de forma segura. Railway inyecta automáticamente las variables de entorno con la información de conexión necesaria en los servicios que dependen de ellos.
Asignación de Recursos y Escalamiento:

Railway asigna recursos (CPU, RAM, Storage) a tus servicios basándose en su demanda y el plan que tengas. Puedes monitorear el uso de recursos y, para ciertos tipos de servicios, configurar opciones de escalado automático o manual.
Almacenamiento Persistente (Volúmenes):

Para aplicaciones que necesitan almacenar datos en el sistema de archivos que persistan más allá del ciclo de vida de un despliegue (ej: archivos subidos por usuarios, configuraciones en disco), Railway proporciona Volúmenes de almacenamiento persistente que se pueden montar en tu servicio.
Dominios Personalizados:

Configurar tu propio nombre de dominio (`www.miempresa.com`) para apuntar a tu aplicación desplegada en Railway, reemplazando el subdominio por defecto (`.up.railway.app`). Railway también gestiona automáticamente los certificados SSL/TLS para tus dominios personalizados.
Soporte para Monorepos:

Railway permite desplegar servicios específicos (aplicaciones o APIs) que residen dentro de un monorepo, configurando la ruta del código fuente dentro del repositorio que corresponde a cada servicio.
Entornos:

Organizar tu proyecto en diferentes entornos (ej: `production`, `staging`, `development`). Cada entorno puede desplegar una rama diferente de tu repositorio Git, tener variables de entorno distintas y recursos aislados, facilitando los flujos de trabajo de desarrollo y despliegue.
CLI de Railway y Web UI:

La interfaz de línea de comandos (`railway`) es tu herramienta para interactuar con Railway desde la terminal, inicializar proyectos, desplegar, gestionar variables y ver logs. La interfaz web es un panel visual para monitorear, configurar y administrar tus proyectos, servicios y recursos.
Buildpacks vs Dockerfile:

Railway puede detectar automáticamente el lenguaje y framework de tu aplicación y usar Buildpacks para construir una imagen de contenedor sin necesidad de escribir un Dockerfile. Alternativamente, puedes proporcionar un Dockerfile personalizado en la raíz de tu proyecto si necesitas un control más granular sobre el proceso de construcción.

Casos de uso

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

Desplegar una aplicación fullstack con frontend, backend y base de datos gestionada:

Utilizar Railway para hostear los diferentes componentes de tu aplicación en servicios separados dentro de un proyecto, incluyendo una base de datos gestionada como PostgreSQL o MongoDB.
Alojar APIs REST o GraphQL con bases de datos gestionadas y manejar la configuración con variables de entorno:

Desplegar el servicio de tu API y conectarlo de forma segura a una base de datos gestionada por Railway, utilizando variables de entorno para las credenciales y otras configuraciones.
Gestionar múltiples servicios (ej: microservicios, background workers) dentro de un único proyecto Railway:

Configurar y desplegar varios servicios interconectados en un proyecto para representar los diferentes componentes de una arquitectura de microservicios o una aplicación distribuida.
Automatizar el despliegue continuo de nuevas versiones desde un repositorio de GitHub:

Enlazar tu proyecto Railway con GitHub y configurar la integración para que cada push a la rama principal (o a una rama específica) active automáticamente un nuevo despliegue en Railway.
Configurar dominios personalizados y asegurar tus aplicaciones con certificados SSL/TLS automáticos:

Añadir tus propios dominios a los servicios de Railway y configurar tus registros DNS para que apunten a Railway, y Railway gestionará la provisión y renovación de certificados SSL/TLS.
Desplegar diferentes ramas o versiones de tu aplicación a entornos separados (staging, preview):

Utilizar la función de Entornos de Railway para desplegar ramas específicas de tu repositorio Git a entornos aislados para pruebas o demostraciones antes de desplegar en producción.
Utilizar almacenamiento persistente para aplicaciones que necesitan guardar archivos o datos en disco:

Configurar Volúmenes en tu servicio de aplicación para asegurar que ciertos directorios (ej: para uploads de usuarios, archivos de log específicos de la aplicación) persistan incluso si el servicio se reinicia o se redespliega.
Desplegar aplicaciones desde un Monorepo, seleccionando la ruta del código fuente para cada servicio:

Configurar servicios en Railway para que construyan y desplieguen código desde subdirectorios específicos dentro de un monorepo Git.

Consejos para Principiantes

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

Entiende la Metáfora de los Servicios:

Piensa en tu proyecto Railway como una colección de 'servicios' interconectados. Tu código de aplicación es un servicio, tu base de datos es otro, un cache Redis es otro más. Cada uno se gestiona (despliega, escala, monitorea) de forma independiente dentro del proyecto.
Domina la Gestión de Variables de Entorno:

Es la forma principal de configurar tu aplicación y conectarla a otros servicios (especialmente las bases de datos gestionadas). Usa `railway env add` en la CLI o el panel web para gestionarlas de forma segura. ¡Nunca hardcodees secretos en tu código!
Aprovecha la CLI de Railway y la Interfaz Web:

La CLI (`railway up`, `railway logs`, `railway env`) es excelente para flujos de trabajo de desarrollo local y automatización. La interfaz web (`railway open`) es indispensable para visualizar el estado del proyecto, monitorear recursos, configurar servicios y gestionar variables de forma visual.
Enlaza tu Proyecto a GitHub para Despliegues Automáticos:

Una de las mayores ventajas de Railway es su integración con Git. Configura tu proyecto para desplegar automáticamente desde una rama específica cada vez que haces un push. Esto simplifica enormemente tu pipeline de CI/CD.
Entiende Cómo se Asignan los Recursos y Monitorea tu Uso:

Railway asigna recursos dinámicamente. Usa `railway usage` en la CLI o la sección de uso en el panel web para ver cuánto consumes (CPU, RAM, almacenamiento) y cómo esto se traduce en costos. Optimiza tu aplicación para usar menos recursos si es necesario.
Utiliza Almacenamiento Persistente (Volúmenes) para Datos que Deben Sobrevivir:

Si tu aplicación necesita guardar archivos o datos en disco (ej: uploads de usuarios, una base de datos no gestionada que autohostees), configura Volúmenes en tu servicio. Los datos en el sistema de archivos del contenedor *no* persisten entre despliegues.
Explora la Biblioteca de Templates de Railway:

Los templates son un excelente punto de partida para desplegar rápidamente stacks tecnológicos comunes (ej: una aplicación web con una base de datos específica). Te ahorran tiempo de configuración inicial y te muestran cómo se enlazan los servicios.
Aprende sobre los Entornos de Railway:

Usa entornos separados (ej: `production`, `staging`, `development`) para aislar diferentes fases de desarrollo o ramas. Cada entorno puede tener su propia configuración y recursos.
Considera Usar Dockerfile si Necesitas Control Fino sobre el Build:

Si los Buildpacks automáticos de Railway no detectan correctamente tu aplicación o necesitas un control más granular sobre cómo se construye la imagen de tu contenedor, añade un `Dockerfile` a la raíz de tu proyecto. Railway lo detectará y usará.

Herramientas relacionadas

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

Recursos útiles

Amplía tus conocimientos con estos enlaces y materiales: