Skip to main content

​
Introdução

Para desenvolver e hospedar uma instância do n8n na Square Cloud, siga a sequência de configurações e pré-requisitos abaixo. Este guia cobre todo o processo, da configuração inicial ao deploy em produção.

​
Pré-requisitos

  • Conta Square Cloud: Cadastre-se através da página de cadastro usando seu e-mail.
  • Plano ativo: Garante recursos dedicados e desempenho otimizado para seu aplicativo. Confira nossos planos disponíveis e escolha o mais adequado às suas necessidades.
O n8n roda com 3 GB de RAM (MEMORY=3072 abaixo), então precisa de um plano com pelo menos 4 GB, como o Standard: os planos menores não têm tanta RAM. Este guia usa o runtime Node.js.

​
Obtenha o projeto

O n8n roda em Node.js, então o projeto só precisa de um package.json que liste o n8n nas dependências e tenha um script para iniciá-lo:
package.json
A versão do n8n é fixada de propósito: latest pode pular para uma nova versão major com mudanças incompatíveis em qualquer reinstalação. O n8n 2.x precisa do Node.js 24 ou mais recente, que o VERSION=recommended fornece. Para atualizar depois, confira a versão mais recente com npm view n8n version, leia as notas de versão do n8n, mude a versão no package.json e envie o seu projeto de novo.
Já temos tudo pronto para deploy nas nossas releases do n8n-web. Você só precisa baixar o project.zip e enviá-lo.

​
Configure a Square Cloud

Crie um arquivo squarecloud.app na raiz do projeto:
squarecloud.app
START=npm run start roda o script start do seu package.json. Ao enviar pelo dashboard, defina o runtime manualmente como Node.js e use npm run start como comando de inicialização. O valor de MEMORY segue as regras de dimensionamento da plataforma: veja por que existem mínimos de RAM se quiser ajustá-lo.

​
Variáveis de ambiente

Defina as variáveis abaixo. Você pode colocá-las em um arquivo .env na raiz do projeto (o n8n o carrega ao iniciar) ou defini-las como variáveis de ambiente da aplicação, em Configuração avançada, no formulário de upload, ou no dashboard. Troque my-n8n-subdomain pelo seu SUBDOMAIN.
.env
  • N8N_PORT e N8N_LISTEN_ADDRESS fazem o n8n escutar na porta 80 em todas as interfaces, onde a Square Cloud entrega o tráfego do seu subdomínio. O n8n não lê a variável PORT que a Square Cloud define, então o N8N_PORT é obrigatório.
  • N8N_HOST, N8N_PROTOCOL e N8N_WEBHOOK_URL informam ao n8n o seu endereço público. Guias mais antigos chamam a última de WEBHOOK_URL, que o n8n 2.x descontinua. Veja as variáveis de endpoint do n8n para mais opções.
As variáveis definidas no dashboard têm prioridade sobre o arquivo .env.

​
O que vai no ZIP

  • package.json
  • squarecloud.app
  • .env, se você guarda nele as variáveis acima
Deixe a node_modules/ de fora: a Square Cloud instala o n8n no servidor.

​
Faça o deploy e verifique

​
Via dashboard

1

Acesse a página de upload

Acesse a página de upload e envie seu arquivo zip.
2

Configure seu ambiente

Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.
Se você estiver enviando um projeto web, certifique-se de selecionar “Publicação na Web” e definir um subdomínio para o seu projeto.
3

Faça o deploy do projeto

Por fim, clique no botão “Deploy” para hospedar seu projeto na Square Cloud. Após o deploy, você poderá monitorar o status e os registros do seu projeto no dashboard.
Enviando aplicação para a Square Cloud
4

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. No dashboard, aguarde o status da sua aplicação mudar para em execução e verifique os registros em busca de erros de inicialização.
Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

​
Via CLI

Para usar esse método, seu projeto precisa de um arquivo de configuração chamado squarecloud.app na raiz. Ele informa à Square Cloud como executar a sua aplicação.

Guia do arquivo de configuração

Saiba como criar o arquivo de configuração squarecloud.app que define o ambiente da sua aplicação.
1

Instale a CLI

Instale a CLI da Square Cloud. Se você já a tem, execute o mesmo comando para atualizá-la:
2

Faça login

Execute o comando abaixo. Ele abre o seu navegador: aprove o login lá e a CLI está pronta. Não há nenhuma chave de API para copiar. Para scripts e CI, veja autenticação da CLI.
3

Envie o seu projeto

Na pasta do seu projeto, execute o comando abaixo. A CLI compacta a pasta atual, deixando de fora o que o squarecloud.ignore lista, e faz o upload:
Para enviar um zip que você mesmo criou, passe-o com --file:
4

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. Verifique o status e os registros da sua aplicação diretamente pelo terminal:
Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

​
Primeiro acesso

Logo após o deploy, abra https://my-n8n-subdomain.squareweb.app e crie a conta de proprietário (owner). Quem abrir a página primeiro se torna o proprietário da instância, então faça isso antes de compartilhar a URL com qualquer pessoa.

​
Erros comuns

​
Domínio personalizado

Para usar um domínio personalizado (ex.: meusite.com) no lugar da URL padrão meusite.squareweb.app, você precisa do plano Standard ou superior. A URL padrão vem do campo SUBDOMAIN no arquivo de configuração. Para conectar o seu domínio, veja como configurar seu próprio domínio.

​
Requisitos mínimos de RAM

Mínimo: 512MB de RAM para sites e APIs, o suficiente para um build estático no runtime estático. Para aplicações que renderizam páginas no servidor (Next.js, Nuxt, Angular SSR e similares), recomendamos pelo menos 1GB de RAM. Para aplicações maiores, aloque mais RAM para evitar que a aplicação fique sem memória e trave.

​
Não foi possível encontrar esse site.

Verifique se o subdomínio/domínio corresponde ao configurado no campo SUBDOMAIN ou nas configurações de domínio personalizado. Se você acabou de enviar o site, aguarde até 60 segundos para a Square liberar o primeiro acesso.

​
Site demorou demais para responder…

O seu servidor precisa escutar na porta 80 e no host 0.0.0.0. A Square Cloud define as variáveis de ambiente PORT (80) e HOST (0.0.0.0) na sua aplicação: leia essas variáveis no código em vez de fixar outros valores. Um servidor que escuta apenas em localhost ou 127.0.0.1 nunca recebe requisições.

​
O n8n não responde no seu subdomínio

O n8n ignora as variáveis PORT e HOST. Confira se N8N_PORT=80 e N8N_LISTEN_ADDRESS=0.0.0.0 estão definidas e reinicie a aplicação.

​
As URLs de webhook apontam para a porta interna

Sem N8N_WEBHOOK_URL, as URLs de webhook que o n8n mostra nos seus workflows apontam para a porta interna e serviços externos não conseguem acessá-las. Defina N8N_WEBHOOK_URL com o seu endereço público, por exemplo https://my-n8n-subdomain.squareweb.app/, e reinicie a aplicação.

​
Próximos passos

Variáveis de ambiente

Gerencie as configurações e os segredos do n8n pelo dashboard ou pela CLI.

Domínio personalizado

Sirva o n8n no seu próprio domínio e depois atualize N8N_HOST e N8N_WEBHOOK_URL.

Uptime Kuma

Monitore o n8n e os seus outros serviços.
Para saber mais sobre o n8n, consulte a documentação oficial do n8n.

​
Contate-nos

Se você continuar enfrentando dificuldades técnicas, nossa equipe de suporte especializada está disponível para auxiliá-lo. Entre em contato conosco e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com 4,9/5 em 402 avaliações no Google e Trustpilot.