Como hospedar aplicações Phoenix na Square Cloud

O Phoenix Framework oferece uma performance espetacular graças à máquina virtual do Erlang (BEAM). Para extrair o máximo dessa arquitetura na Square Cloud, nós não rodamos o código fonte bruto em produção; em vez disso, geramos uma Release compilada e configuramos o ambiente para Elixir com um comando personalizado.

1. Gerando a Release (Compilação)

O Elixir possui um sistema embutido chamado mix release que reúne o runtime do Erlang, o Elixir e todas as suas dependências (incluindo o código compilado do Phoenix) em um único diretório independente.

Antes de enviar, execute os seguintes comandos para preparar o ambiente de produção. A Square Cloud roda em Linux: gere a release num Linux (WSL, por exemplo), porque uma release compilada no Windows ou no macOS não roda lá. Outra opção é enviar o código-fonte e deixar a Square Cloud compilar, já que ela roda mix deps.get antes do START.

# 1. Instale as dependências de produção
MIX_ENV=prod mix deps.get --only prod

# 2. Compile as dependências e o projeto
MIX_ENV=prod mix compile

# 3. Se o seu app tiver assets (CSS/JS), compile-os (ex: usando Tailwind/Esbuild)
MIX_ENV=prod mix assets.deploy

# 4. Gere o binário de produção
MIX_ENV=prod mix release

Esse processo criará uma pasta de saída em: _build/prod/rel/NOME_DO_SEU_APP/. O zip leva essa pasta (dentro de _build/) e os arquivos mix.exs e mix.lock na raiz.

2. Variáveis de Ambiente Obrigatórias (ENV)

O Phoenix exige algumas configurações de segurança rigorosas para rodar em produção. No Dashboard da Square Cloud, acesse a aba Variáveis de Ambiente e configure:

• SECRET_KEY_BASE: Uma chave longa e segura (você pode gerar uma localmente rodando mix phx.gen.secret).
• DATABASE_URL: A string de conexão com o seu banco de dados (ex: o PostgreSQL da Square Cloud).
• PHX_HOST: O domínio fornecido pela Square Cloud (ex: seu-app⁠.squareweb.app).

3. Configurando o Ambiente e o Comando Personalizado

Ao criar a aplicação no painel da Square Cloud, marque Publicação na Web no envio (ela não pode ser ligada depois), ou use SUBDOMAIN= no arquivo de configuração (squarecloud⁠.app / squarecloud.config), com o mesmo nome usado no PHX_HOST. Certifique-se também de definir o ambiente manualmente caso tenha compilado:

• Ambiente (Runtime): elixir

Comando de Inicialização Personalizado (Start):

Sem PHX_SERVER=true o servidor HTTP não sobe. Use:

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

(Substitua NOME_DO_SEU_APP pelo nome da release, o mesmo app: do seu mix.exs.)

Para aplicar as migrações, rode antes bin/NOME_DO_SEU_APP eval "MyApp.Release.migrate" (módulo gerado por mix phx.gen.release). Se preferir enviar o código-fonte, use START=MIX_ENV=prod mix assets.deploy && MIX_ENV=prod mix phx.server.

4. O que incluir no arquivo .zip?

Para um upload rápido e eficiente, crie um arquivo .zip contendo apenas a estrutura compilada e os arquivos de configuração mínimos:

• A pasta _build/ (Onde está sua release).
• A pasta config/ (Opcional, mas útil para referências).
• Os arquivos mix.exs e mix.lock (obrigatórios na raiz).

Nota importante: Não envie as pastas deps/, .elixir_ls/ ou a pasta assets/node_modules/. O binário gerado na pasta _build já é totalmente autossuficiente.

5. Monitoramento e Performance

Como o Phoenix roda compilado dentro da BEAM, o uso inicial de memória RAM pode parecer ligeiramente maior do que o de um script Node.js simples, mas ele se mantém extremamente estável mesmo sob forte estresse. Acompanhe os logs no painel da Square Cloud para garantir que a aplicação iniciou com sucesso.

Atualizado em: 04/10/2026