Cómo alojar aplicaciones Phoenix en Square Cloud

El framework Phoenix ofrece un rendimiento espectacular gracias a la máquina virtual de Erlang (BEAM). Para extraer el máximo de esa arquitectura en Square Cloud, no ejecutamos el código fuente en bruto en producción; en su lugar, generamos una Release compilada y configuramos el entorno para Elixir con un comando personalizado.

1. Generando la Release (compilación)

Elixir cuenta con un sistema integrado llamado mix release que reúne el runtime de Erlang, Elixir y todas tus dependencias (incluido el código compilado de Phoenix) en un único directorio independiente.

Genera la release en Linux (por ejemplo, en WSL): una release generada en Windows o macOS no funciona en el servidor. La alternativa recomendada es subir el código fuente con START=MIX_ENV=prod mix assets.deploy && MIX_ENV=prod mix phx.server. Para la release, ejecuta en tu máquina:

# 1. Instala las dependencias de producción
MIX_ENV=prod mix deps.get --only prod

# 2. Compila las dependencias y el proyecto
MIX_ENV=prod mix compile

# 3. Si tu app tiene assets (CSS/JS), compílalos (ej.: con Tailwind/Esbuild)
MIX_ENV=prod mix assets.deploy

# 4. Genera el binario de producción
MIX_ENV=prod mix release

Este proceso creará una carpeta de salida en: _build/prod/rel/NOMBRE_DE_TU_APP/. Comprime solo lo necesario, que será lo que contiene esa carpeta.

2. Variables de entorno obligatorias (ENV)

Phoenix exige algunas variables. En el Dashboard, accede a la pestaña Variables de Entorno y configura:

• SECRET_KEY_BASE: Una clave larga y segura (puedes generar una localmente ejecutando mix phx.gen.secret).
• DATABASE_URL: La string de conexión con tu base de datos (ej.: el PostgreSQL de Square Cloud).
• PHX_HOST: El dominio proporcionado por Square Cloud (ej.: tu-app⁠.squareweb⁠.app).

3. Configurando el entorno y el comando personalizado

Al crear la aplicación en el panel de Square Cloud o al rellenar tu archivo de configuración (squarecloud⁠.app / squarecloud.config), asegúrate de definir el entorno manualmente si compilaste:

• Entorno (Runtime): elixir

Comando de inicio personalizado (Start):

Para que Phoenix inicie el servidor web, usa:

PHX_SERVER=true _build/prod/rel/NOMBRE_DE_TU_APP/bin/NOMBRE_DE_TU_APP start

(Sustituye NOMBRE_DE_TU_APP por el nombre de la release definido en tu mix.exs, en minúsculas).

bin/<app> start no aplica migraciones. Para aplicarlas antes de iniciar:

_build/prod/rel/NOMBRE_DE_TU_APP/bin/NOMBRE_DE_TU_APP eval "MiApp.Release.migrate" && PHX_SERVER=true _build/prod/rel/NOMBRE_DE_TU_APP/bin/NOMBRE_DE_TU_APP start

4. ¿Qué enviar en el .zip?

Para el deploy, crea un archivo .zip que contenga solo la estructura compilada y los archivos de configuración mínimos:

• La carpeta _build/ (donde está tu release).
• La carpeta config/ (opcional, pero útil para referencias).
• Los archivos mix.exs y mix.lock.

Nota importante: No envíes las carpetas deps/, .elixir_ls/ ni la carpeta assets/node_modules/. El binario generado en la carpeta _build ya es totalmente autosuficiente.

5. Monitoreo y rendimiento

Como Phoenix se ejecuta compilado dentro de la BEAM, el uso inicial de memoria RAM puede parecer ligeramente mayor que el de un script Node.js simple, pero se mantiene extremadamente estable incluso bajo fuerte estrés. Sigue los logs en el panel de Square Cloud para garantizar que la aplicación inició con éxito.

Actualizado el: 04/10/2026