> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How to host a Phoenix application (Elixir)

# 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:

```bash
# 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:

```bash
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.