How to Host Phoenix Applications on Square Cloud

The Phoenix Framework delivers spectacular performance thanks to the Erlang virtual machine (BEAM). To extract the most out of this architecture on Square Cloud, we do not run the raw source code in production; instead, we generate a compiled Release and configure the environment for Elixir using a custom command.

1. Generating the Release (Compilation)

Elixir has a built-in system called mix release that bundles the Erlang runtime, Elixir, and all its dependencies (including the compiled Phoenix code) into a single, independent directory.

Before deploying, run the following commands on your local machine to prepare the production environment:

# 1. Install production dependencies
MIX_ENV=prod mix deps.get --only prod

# 2. Compile dependencies and the project
MIX_ENV=prod mix compile

# 3. If your app has assets (CSS/JS), compile them (e.g., using Tailwind/Esbuild)
MIX_ENV=prod mix assets.deploy

# 4. Generate the production binary
MIX_ENV=prod mix release

This process will create an output folder at: _build/prod/rel/YOUR_APP_NAME/. Compress only what is necessary, which is the content within this folder.

2. Mandatory Environment Variables (ENV)

Phoenix requires strict security configurations to run in production. In the Square Cloud Dashboard, go to the Environment Variables tab and configure:

• SECRET_KEY_BASE: A long, secure key (you can generate one locally by running mix phx.gen.secret).
• DATABASE_URL: The connection string for your database (e.g., Square Cloud's PostgreSQL).
• PHX_HOST: The domain provided by Square Cloud (e.g., your-app.squareweb.app).

3. Configuring the Environment and Custom Command

When creating the application in the Square Cloud panel or filling out your configuration file (squarecloud.app / squarecloud.config), make sure to define the environment manually if you have compiled it:

• Environment (Runtime): elixir

Custom Startup Command (Start):

To make Phoenix start the web server and apply database migrations (if any), use the following combined command:

bin/YOUR_APP_NAME start

(Replace YOUR_APP_NAME with your project's name in lowercase and AppSecret with the release module defined in your code, if applicable).

4. What to Include in the .zip File?

For a fast and efficient upload, create a .zip file containing only the compiled structure and minimum configuration files:

• The _build/ folder (Where your release is located).
• The config/ folder (Optional, but useful for reference).
• The mix.exs file.

Important Note: Do not upload the deps/, .elixir_ls/, or assets/node_modules/ folders. The binary generated in the _build folder is already completely self-sufficient.

5. Monitoring and Performance

Since Phoenix runs compiled within the BEAM, initial RAM usage may appear slightly higher than that of a simple Node.js script, but it remains extremely stable even under heavy stress. Follow the logs in the Square Cloud panel to ensure the application started successfully.

Updated on: 05/25/2026