> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido: seu primeiro deploy

> Coloque sua primeira aplicação no ar em minutos: escreva um servidor web simples, adicione o arquivo de configuração e faça deploy pelo dashboard ou pela CLI.

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](https://squarecloud.app/pt-br/pricing) certo para você (veja [o que cada plano inclui](/pt-br/platform/plans)).

<CardGroup>
  <Card title="Cadastre-se" icon="user-plus" href="https://squarecloud.app/pt-br/signup" color="#95979b">
    Se você nunca usou a Square Cloud antes, cadastre-se para começar.
  </Card>

  <Card title="Entrar" icon="right-to-bracket" href="https://squarecloud.app/pt-br/signin" color="#95979b">
    Se você já tem uma conta, entre para começar.
  </Card>
</CardGroup>

## Crie o projeto

Crie uma pasta com estes três arquivos.

<Steps>
  <Step title="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`:

    ```javascript index.js theme={"system"}
    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}`);
      });
    ```
  </Step>

  <Step title="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.

    ```json package.json theme={"system"}
    {
      "name": "hello-square",
      "version": "1.0.0",
      "private": true,
      "main": "index.js",
      "scripts": {
        "start": "node index.js"
      }
    }
    ```
  </Step>

  <Step title="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.

    ```systemd squarecloud.app theme={"system"}
    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](/pt-br/getting-started/config-file). A [extensão para VS Code](/pt-br/vscode-extension/features#intellisense-do-arquivo-de-configuração) autocompleta e valida este arquivo enquanto você digita.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

<Tip>
  Vai fazer deploy de um bot? Deixe de fora o `SUBDOMAIN`, adicione `AUTORESTART=true` e guarde o token em uma [variável de ambiente](/pt-br/platform/environment-variables), nunca no código. O [tutorial de bot do Discord](/pt-br/tutorials/bots/discord) mostra um bot completo.
</Tip>

## Compacte o projeto

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

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Crie o zip">
    <Tabs>
      <Tab title="Windows">
        Clique com o botão direito nos arquivos selecionados e escolha **Compactar para arquivo ZIP** (Windows 11) ou **Enviar para** → **Pasta compactada**.
      </Tab>

      <Tab title="macOS">
        Clique com a tecla Control pressionada nos arquivos selecionados e escolha **Comprimir**.
      </Tab>

      <Tab title="Linux">
        Clique com o botão direito nos arquivos selecionados e escolha **Compactar**, ou execute `zip -r ../app.zip .` dentro da pasta.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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](https://help.squarecloud.app/pt-br/article/quais-arquivos-sao-excluidos-no-deploy-xvnobl/) de qualquer forma.
  </Step>
</Steps>

## Faça o deploy

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

### Via dashboard

<Steps>
  <Step title="Acesse a página de upload">
    Acesse a [página de upload](https://squarecloud.app/pt-br/dashboard/new) e envie seu arquivo zip.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/dashboard/uploading-pt-br.gif" alt="Enviando aplicação para a Square Cloud" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>

  <Step title="Confirme que seu app está no ar">
    Seu primeiro deploy geralmente leva menos de um minuto. No [dashboard](https://squarecloud.app/pt-br/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.
    <Tip>Seu app não está iniciando? Veja o [guia de solução de problemas](/pt-br/platform/troubleshooting/app-wont-start) para as causas e correções mais comuns.</Tip>
  </Step>
</Steps>

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

<Card title="Guia do arquivo de configuração" icon="link" href="/pt-br/getting-started/config-file">
  Saiba como criar o arquivo de configuração `squarecloud.app` que define o ambiente da sua aplicação.
</Card>

<Steps>
  <Step title="Instale a CLI">
    Instale a [CLI da Square Cloud](/pt-br/cli-reference/installation). Se você já a tem, execute o mesmo comando para atualizá-la:

    <CodeGroup>
      ```bash macOS, Linux e WSL theme={"system"}
      curl -fsSL https://cli.squarecloud.app/install | bash
      ```

      ```bash Windows com npm theme={"system"}
      npm install -g @squarecloud/cli@latest
      ```
    </CodeGroup>
  </Step>

  <Step title="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](/pt-br/cli-reference/authentication).

    ```bash theme={"system"}
    squarecloud auth login
    ```
  </Step>

  <Step title="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`](/pt-br/getting-started/squarecloud-ignore) lista, e faz o upload:

    ```bash theme={"system"}
    squarecloud upload
    ```

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

    ```bash theme={"system"}
    squarecloud upload --file <caminho/para/zip>
    ```
  </Step>

  <Step title="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:

    ```bash theme={"system"}
    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.
    <Tip>Seu app não está iniciando? Veja o [guia de solução de problemas](/pt-br/platform/troubleshooting/app-wont-start) para as causas e correções mais comuns.</Tip>
  </Step>
</Steps>

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

<Tip>Quer um deploy a cada push? [Integre um repositório do GitHub](https://help.squarecloud.app/pt-br/article/como-integrar-seu-repositorio-do-github-e-fazer-deploy-automatico-1nk6gr9/) ou use o [workflow do GitHub Actions](https://help.squarecloud.app/pt-br/article/workflow-github-actions-deploy-automatico-o6c7e2/).</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Arquivo de configuração" icon="gear-complex-code" href="/pt-br/getting-started/config-file">
    Todos os campos do `squarecloud.app`: memória, comando de start, subdomínio e reinício automático.
  </Card>

  <Card title="Variáveis de ambiente" icon="key" href="/pt-br/platform/environment-variables">
    Guarde tokens e strings de conexão fora do seu código.
  </Card>

  <Card title="Solução de problemas" icon="bug" href="/pt-br/platform/troubleshooting">
    Corrija erros de upload, sites que não carregam e aplicações que não iniciam.
  </Card>

  <Card title="Extensão para VS Code" icon="code" href="/pt-br/vscode-extension/installation">
    Faça upload, commit e acompanhe logs sem sair do editor.
  </Card>
</CardGroup>

### Guias para a sua linguagem

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

<CardGroup cols={3}>
  <Card title="JavaScript" icon="node-js" href="../articles/getting-started-with-nodejs" />

  <Card title="Bun" icon="bread-slice" href="../articles/getting-started-with-bun" />

  <Card title="Deno" icon="t-rex" href="../articles/getting-started-with-deno" />

  <Card title="Python" icon="python" href="../articles/getting-started-with-python" />

  <Card title="Java" icon="java" href="../articles/getting-started-with-java" />

  <Card title="Rust" icon="rust" href="../articles/getting-started-with-rust" />

  <Card title="Elixir" icon="droplet" href="../articles/getting-started-with-elixir" />

  <Card title="PHP" icon="php" href="../articles/getting-started-with-php" />

  <Card title="Go" icon="golang" href="../articles/getting-started-with-go" />

  <Card title="C#" icon="c" href="../articles/getting-started-with-csharp" />

  <Card title="Ruby" icon="gem" href="../articles/getting-started-with-ruby" />

  <Card title="HTML/CSS" icon="html5" href="../articles/getting-started-with-html" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.