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 na sua máquina local para preparar o ambiente de produção:

# 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/. Compacte apenas o necessário que será o que contém nessa pasta.

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, acese 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 ou preencher o seu arquivo de configuração (squarecloud.app / squarecloud.config), certifique-se de definir o ambiente manualmente caso tenha compilado:

• Ambiente (Runtime): elixir

Comando de Inicialização Personalizado (Start):

Para que o Phoenix inicie o servidor web e aplique as migrações do banco de dados (se houver), use o seguinte comando combinado:

bin/NOME_DO_SEU_APP start

(Substitua NOME_DO_SEU_APP pelo nome do seu projeto em letras minúsculas e SenhaDoApp pelo módulo de release definido no seu código, se aplicável).

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).
• O arquivo mix.exs.

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: 18/05/2026