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 creates the release at _build/prod/rel/YOUR_APP_NAME/. Keep mix.exs and mix.lock in the ZIP (Square Cloud runs mix deps.get before START) and start the release by its full path (see below).

Important: a release built on Windows or macOS does not run on Square Cloud (Linux). Build it on Linux (e.g. WSL), or skip the release and upload the source code (see the alternative below).

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, enable Web Publication on the first upload (or set SUBDOMAIN= in your config file), using the same name as PHX_HOST. If you write the config file yourself, define:

• Environment (Runtime): elixir

Custom Startup Command (Start):

Start the release by its full path with PHX_SERVER=true, which makes the release start the web server:

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

(Replace YOUR_APP_NAME with the release name, the same app: from your mix.exs. To run migrations, run a release task before starting, e.g. _build/prod/rel/YOUR_APP_NAME/bin/YOUR_APP_NAME eval "MyApp.Release.migrate" && ..., generated by mix phx.gen.release.)

Alternative without a release: upload the source (without _build/ and deps/) and use MIX_ENV=prod mix assets.deploy && MIX_ENV=prod mix phx.server as the start command.

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 and mix.lock files (required: Square Cloud runs mix deps.get before START).

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: 10/04/2026