Início rápido: seu primeiro deploy

Este guia faz o deploy de um pequeno servidor web em Node.js para você ver o fluxo completo de ponta a ponta: três arquivos, um zip e um upload. Os passos são os mesmos para um bot ou para outra linguagem.

Antes de começar

A Square Cloud é uma plataforma paga: um plano ativo é necessário para fazer deploy, então seu projeto roda em infraestrutura de nível de produção desde o primeiro dia. Crie sua conta e selecione o plano certo para você (veja o que cada plano inclui).

Cadastre-se

Se você nunca usou a Square Cloud antes, cadastre-se para começar.

Entrar

Se você já tem uma conta, entre para começar.

Crie o projeto

Crie uma pasta com estes três arquivos.

Escreva a aplicação

O index.js responde a toda requisição com uma mensagem curta. Ele lê a porta e o host das variáveis de ambiente PORT e HOST, que a Square Cloud define como 80 e 0.0.0.0:

index.js

const http = require("node:http");

const port = process.env.PORT || 3000;
const host = process.env.HOST || "0.0.0.0";

http
  .createServer((req, res) => {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("Hello from Square Cloud!");
  })
  .listen(port, host, () => {
    console.log(`Listening on http://${host}:${port}`);
  });

Liste as dependências

Todo projeto Node.js precisa de um package.json: a Square Cloud instala os pacotes listados nele antes de iniciar a sua aplicação. Este exemplo não tem nenhum, mas o arquivo precisa existir e não pode estar vazio.

package.json

{
  "name": "hello-square",
  "version": "1.0.0",
  "private": true,
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

Adicione o arquivo de configuração

O squarecloud.app diz à Square Cloud qual arquivo executar, quanta memória reservar e qual versão do runtime usar. O SUBDOMAIN publica a aplicação como um site em https://<subdomain>.squareweb.app, então escolha um nome que ninguém usou ainda.

squarecloud.app

MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=Hello Square
SUBDOMAIN=hello-square-yourname

Cada campo está explicado na referência do arquivo de configuração. A extensão para VS Code autocompleta e valida este arquivo enquanto você digita.

Um site precisa escutar na porta 80 e no host 0.0.0.0. Um servidor preso a localhost, 127.0.0.1 ou a outra porta (como 3000 ou 8080) fica inacessível, e o site mostra uma página de timeout. Ler PORT e HOST, como o index.js faz, resolve isso na Square Cloud e ainda roda na porta 3000 na sua máquina.

Vai fazer deploy de um bot? Deixe de fora o SUBDOMAIN, adicione AUTORESTART=true e guarde o token em uma variável de ambiente, nunca no código. O tutorial de bot do Discord mostra um bot completo.

Compacte o projeto

Vai fazer deploy pela CLI? Pule esta seção: o squarecloud upload compacta a pasta para você.

Selecione os arquivos, não a pasta

Abra a pasta do projeto e selecione tudo o que está dentro dela. O squarecloud.app precisa ficar no nível mais alto do zip: se você compactar a própria pasta, os arquivos vão parar dentro de uma subpasta e o deploy falha com MISSING_CONFIG.

Crie o zip

Windows
macOS
Linux

Clique com o botão direito nos arquivos selecionados e escolha Compactar para arquivo ZIP (Windows 11) ou Enviar para → Pasta compactada.

Clique com o botão direito nos arquivos selecionados e escolha Compactar, ou execute zip -r ../app.zip . dentro da pasta.

Confira o tamanho

O zip pode ter até 100 MB. Deixe de fora a node_modules, os ambientes virtuais e os caches de build: as dependências são instaladas no servidor, e essas pastas são excluídas no deploy de qualquer forma.

Faça o deploy

Envie o zip pelo dashboard ou faça deploy com um único comando pela CLI.

Via dashboard

Acesse a página de upload

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

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.

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.

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.

Instale a CLI

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

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

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.

squarecloud auth login

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:

squarecloud upload

Para enviar um zip que você mesmo criou, passe-o com --file:

squarecloud upload --file <caminho/para/zip>

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:

squarecloud app status
squarecloud app logs

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.

Assim que a aplicação estiver rodando, https://hello-square-yourname.squareweb.app (com o seu subdomínio) responde Hello from Square Cloud!.

Quer um deploy a cada push? Integre um repositório do GitHub ou use o workflow do GitHub Actions.

Próximos passos

Arquivo de configuração

Todos os campos do squarecloud.app: memória, comando de start, subdomínio e reinício automático.

Variáveis de ambiente

Guarde tokens e strings de conexão fora do seu código.

Solução de problemas

Corrija erros de upload, sites que não carregam e aplicações que não iniciam.

Extensão para VS Code

Faça upload, commit e acompanhe logs sem sair do editor.

Guias para a sua linguagem

Cada guia explica o arquivo de dependências, o comando de start e os problemas comuns do seu runtime.

Serviços

Solução de problemas

Runtimes

Plataforma

Changelog

Início rápido: seu primeiro deploy

Antes de começar

Cadastre-se

Entrar

Crie o projeto

Compacte o projeto

Faça o deploy

Via dashboard

Via CLI

Guia do arquivo de configuração

Próximos passos

Arquivo de configuração

Variáveis de ambiente

Solução de problemas

Extensão para VS Code

Guias para a sua linguagem

JavaScript

Bun

Deno

Python

Java

Rust

Elixir

PHP

Go

C#

Ruby

HTML/CSS

​Antes de começar

Cadastre-se

Entrar

​Crie o projeto

​Compacte o projeto

​Faça o deploy

​Via dashboard

​Via CLI

Guia do arquivo de configuração

​Próximos passos

Arquivo de configuração

Variáveis de ambiente

Solução de problemas

Extensão para VS Code

​Guias para a sua linguagem

JavaScript

Bun

Deno

Python

Java

Rust

Elixir

PHP

Go

C#

Ruby

HTML/CSS

Antes de começar

Crie o projeto

Compacte o projeto

Faça o deploy

Via dashboard

Via CLI

Próximos passos

Guias para a sua linguagem