Desplegar un proyecto PHP en Railway desde GitHub, base de datos y acceso a ficheros

1. Inmersión rápida: qué hacer en el caso tratado

Si tuviera que reducir todo el artículo a una secuencia operativa segura para este caso, sería esta:

1. Abrir el proyecto PHP en GitHub Codespaces.

2. Instalar la Railway CLI si aún no está instalada.

3. Autenticarse con railway login o railway login --browserless.

4. Enlazar el directorio al proyecto Railway con railway link.

5. Verificar o enlazar el servicio correcto si el proyecto tiene varios.

6. Cargar las variables necesarias con railway vars set.

7. Si hace falta base de datos, añadir un servicio MySQL desde el Project Canvas y usar sus variables de conexión.

8. Desplegar con railway up.

9. Generar la URL pública con railway domain o desde Settings → Networking → Public Networking → Generate Domain.

10. Si la aplicación necesita persistir ficheros, añadir un Volume y montar la ruta correcta.

11. Si hay que inspeccionar el contenedor, usar railway ssh; si hay que entrar en la base de datos, usar railway connect.

1.1. Despliegue desde Codespaces

railway login --browserless
railway link
railway vars set APP_ENV=prod
railway up
railway domain

1.2. Acceso al servicio desplegado

railway ssh

Permite abrir una shell en el contenedor, si el servicio dispone de shell. No sirve para SCP/SFTP.

1.3. Acceso interactivo a MySQL

railway connect

Si el servicio MySQL está presente y el cliente mysql está disponible, Railway documenta este comando para abrir la shell interactiva de base de datos.

2. Introducción

Railway permite desplegar una aplicación de varias formas, pero en la práctica hay dos flujos que se confunden con facilidad:

• Conectar un repositorio de GitHub al servicio para que Railway despliegue automáticamente cada nuevo commit de la rama enlazada.

• Subir el código del directorio actual con la CLI, algo especialmente útil si trabajas desde GitHub Codespaces.

En el caso tratado aquí, el flujo que encaja con el checklist compartido en la conversación es el segundo: Codespaces + Railway CLI.

Esta distinción evita muchos errores operativos al configurar variables, dominio y servicio destino.

3. Las dos vías de despliegue que más se confunden

3.1. Despliegue desde GitHub conectado a Railway

Railway permite crear un proyecto nuevo desde el panel, elegir Deploy from GitHub repo, seleccionar el repositorio y arrancar el primer despliegue.

Cuando un servicio está conectado a un repositorio y una rama concreta, cada nuevo commit en la rama enlazada provoca automáticamente una nueva build y un nuevo despliegue.

3.2. Despliegue desde Codespaces con la Railway CLI

Railway también documenta el despliegue desde el directorio local. La guía rápida indica que el flujo mínimo con CLI consiste en:

1. abrir una terminal dentro del proyecto;

2. ejecutar railway init;

3. ejecutar railway up.

En este flujo, railway up escanea, comprime y sube los ficheros del directorio actual; después Railway los construye y despliega.

3.3. Qué flujo aplica al caso tratado

Para el caso de esta conversación, el flujo correcto es Codespaces + CLI. No hace falta esperar a un push a GitHub para desplegar, porque railway up despliega directamente el contenido del directorio actual.

4. Cuándo conviene cada flujo

4.1. GitHub conectado a Railway

Conviene cuando quieres que el repositorio sea la fuente de verdad del despliegue, buscas autodeploy por rama o prefieres un flujo más cercano a CI/CD tradicional.

4.2. Codespaces + CLI

Conviene cuando trabajas activamente desde Codespaces, necesitas desplegar sin pasar aún por commit y push, quieres controlar el despliegue desde terminal, o el proyecto ya existe en Railway y solo necesitas enlazarlo y subir el estado actual del directorio.

5. Requisitos previos realistas para un proyecto PHP

5.1. Lo que sí puede afirmarse

Railway construye servicios a partir de repositorios de código o de imágenes Docker. Si encuentra un Dockerfile, lo usa automáticamente. Si no, puede construir con Railpack, que analiza el código, detecta lenguaje y framework, instala runtime y dependencias y genera la imagen optimizada.

Para un proyecto PHP moderno, Railway dispone de guías específicas para Laravel y Symfony. En Laravel detecta la app y la ejecuta con php-fpm y Caddy. En Symfony documenta el uso de RAILPACKPHPROOT_DIR="/app/public" para que el servicio web apunte al directorio público correcto.

5.2. Lo que no consta en este caso

No consta si el proyecto es PHP puro, Laravel, Symfony u otro framework; cuál es su estructura real; qué variables concretas exige; cuál es su comando de inicio exacto; o si necesita varios servicios adicionales.

6. Paso a paso: desplegar desde GitHub Codespaces con la Railway CLI

6.1. Instalar y autenticar la CLI

La Railway CLI puede instalarse mediante npm, Homebrew, Scoop o desde código fuente.

Dentro de Codespaces, la autenticación puede hacerse con:

railway login

o, si se prefiere un flujo sin apertura de navegador en el propio entorno:

railway login --browserless

6.2. Enlazar el directorio al proyecto correcto

Si el proyecto de Railway ya existe:

railway link

Railway documenta que railway link enlaza un proyecto existente con el directorio actual y que, una vez enlazado, comandos como railway up y railway logs apuntarán a ese proyecto.

6.3. Cargar variables de entorno

railway vars set APPENV=prod APPDEBUG=false

o, si hay que apuntar a un servicio concreto:

railway vars set -s app APP_ENV=prod

6.4. Desplegar el directorio actual

railway up

Si trabajas desde Codespaces, railway up despliega el estado local del directorio, no necesariamente el último commit ya empujado a GitHub.

6.5. Consultar estado y logs

En una operativa prudente, tras el enlace y antes del despliegue conviene comprobar el contexto para no desplegar sobre el servicio equivocado.

7. Si en lugar de Codespaces quieres conectar GitHub a Railway

1. crear un proyecto nuevo;

2. elegir Deploy from GitHub repo;

3. seleccionar el repositorio;

4. decidir entre Deploy Now o Add Variables;

5. desplegar.

Una vez conectado el repositorio, Railway documenta que los nuevos commits en la rama enlazada disparan despliegues automáticos. Además, existe la opción Wait for CI para que Railway espere a que los workflows de GitHub Actions terminen antes de desplegar.

8. Crear la base de datos en Railway

8.1. Crear un servicio MySQL

Railway dispone de una plantilla de MySQL que puede añadirse al proyecto desde el menú Ctrl/Cmd + K o desde el botón + New en el Project Canvas. Una vez desplegado, Railway crea un servicio MySQL en el proyecto a partir de la imagen oficial de MySQL en Docker Hub.

8.2. Variables de conexión

Railway documenta que el servicio MySQL expone variables de entorno utilizables desde otros servicios del mismo proyecto:

• MYSQLHOST

• MYSQLPORT

• MYSQLUSER

• MYSQLPASSWORD

• MYSQLDATABASE

• MYSQL_URL

8.3. Conexión interna y externa

Para comunicación entre servicios del mismo proyecto, Railway ofrece Private Networking sobre DNS interno y túneles WireGuard.

Para MySQL desde fuera del proyecto, Railway documenta que puede conectarse externamente mediante TCP Proxy, habilitado por defecto en el servicio MySQL.

8.4. Migrations, schema y seed

Railway documenta la creación del servicio MySQL y las variables de conexión, pero el comando exacto de migración, schema o seed depende del stack real (Laravel, Symfony con Doctrine, PHP puro u otro framework).

9. Cómo obtener la URL pública de la aplicación

Railway documenta que para exponer un servicio a Internet hay que ir a:

1. Settings del servicio;

2. Networking → Public Networking;

3. Generate Domain.

Por CLI:

railway domain

Este comando puede generar un dominio de tipo *.up.railway.app. La URL pública se gestiona a nivel de servicio, no a nivel de proyecto.

10. Acceso a ficheros en Railway: qué existe de verdad

10.1. El código y los ficheros de la app viven en /app

Railway documenta que su sistema de build coloca los archivos de la aplicación en /app dentro del contenedor. Si la app escribe datos en una ruta relativa y quieres persistirlos, el volumen debe montarse con una ruta absoluta que incluya /app, por ejemplo /app/data.

10.2. El almacenamiento local del servicio es efímero

Cada despliegue dispone de almacenamiento efímero. Si los datos deben persistir entre despliegues, hay que añadir un Volume.

10.3. Volumes: el mecanismo de persistencia de ficheros

Railway documenta que un Volume:

• proporciona datos persistentes a un servicio;

• se monta en una ruta absoluta del contenedor;

• queda disponible cuando el servicio arranca, no durante build;

• expone automáticamente las variables RAILWAYVOLUMENAME y RAILWAYVOLUMEMOUNT_PATH.

11. Acceso a ficheros desde la web-app

Desde el punto de vista técnico, la web-app solo puede mostrar o descargar los ficheros que la propia aplicación sirva mediante HTTP o que ponga a disposición desde un directorio público o un endpoint controlado. Public Networking expone servicios HTTP/HTTPS, no carpetas arbitrarias del contenedor como si fuera un explorador de archivos.

12. Acceso a ficheros mediante terminal

12.1. railway shell

Railway documenta railway shell como una shell local que abre una sesión con las variables del servicio inyectadas en el entorno local. No es acceso remoto al contenedor desplegado.

12.2. railway ssh

Para entrar en una shell del servicio desplegado, Railway documenta railway ssh. Esa funcionalidad:

• funciona con un protocolo propio basado en WebSocket;

• no requiere daemon SSH dentro del contenedor;

• funciona con cualquier contenedor que tenga shell disponible.

Limitaciones:

• no hay SCP/SFTP;

• no hay tunelización SSH ni port forwarding;

• no hay integración con Remote-SSH de VS Code.

12.3. Acceso a la base de datos por terminal

railway connect

Abre un cliente interactivo según el tipo de base. En el caso de MySQL, el cliente requerido es mysql.

13. Conclusión

Railway soporta tanto despliegue desde GitHub como despliegue desde un directorio local, pero no deben confundirse. Si trabajas en GitHub Codespaces y usas railway link más railway up, el flujo real es el de despliegue desde CLI.

Puntos clave:

• la base de datos MySQL puede añadirse como servicio en el proyecto y consumirse mediante variables de entorno del propio servicio MySQL;

• la URL pública no se obtiene en cualquier pantalla del proyecto, sino en la configuración del servicio, mediante Public Networking o railway domain;

• los ficheros escritos en el sistema local del contenedor son efímeros salvo que se monte un Volume;

• el acceso por terminal al servicio existe, pero con las limitaciones propias de railway ssh, que no sustituye a un servidor SFTP tradicional.

Sobre el autor

PáginaVIVA publica contenidos relacionados con estrategia digital, presencia online y aplicación práctica de soluciones tecnológicas, con especial atención a la claridad, la utilidad y el contexto real de cada proyecto.

PáginaVIVA