O que é deploy (e o que acontece quando você faz um)

Escrever código que funciona no seu computador é uma coisa. Fazer esse código funcionar para outras pessoas, o tempo todo, em outra máquina, é outra. A ponte entre as duas é o deploy.

A palavra vem do inglês deployment, que em português se traduz como "implantação". Em desenvolvimento, ela virou o nome de uma rotina que você repete dezenas de vezes: mudou o código, fez deploy, a mudança chegou ao ar. Entender o que acontece dentro dessa rotina ajuda a achar erros mais rápido e a escolher ferramentas melhores.

O que é deploy?#

Deploy é o conjunto de passos que leva uma versão específica do seu código até um ambiente onde ela roda e pode ser acessada. O ambiente costuma ser um servidor, uma VPS, um container ou uma plataforma de hospedagem.

Um deploy tem começo e fim claros: parte de um commit (ou de uma pasta de arquivos) e termina com o processo da aplicação em execução e verificado. Se o resultado é uma aplicação que responde, o deploy deu certo. Se o processo cai ao iniciar, ele falhou, mesmo que todos os arquivos tenham chegado.

Não confunda com hospedagem. Hospedagem é o lugar; deploy é a ação de colocar algo lá. Para entender o lugar, veja VPS vs plataforma de nuvem.

Que ambientes existem?#

Quase todo projeto sério tem mais de um ambiente, e o deploy acontece em cada um:

• Desenvolvimento: a sua máquina. Aqui você roda e quebra coisas à vontade.
• Staging (homologação): uma cópia o mais parecida possível com a produção, usada para testar antes de liberar.
• Produção: o que os usuários reais usam. É onde um erro custa caro.

Projetos pequenos, como um bot pessoal, muitas vezes têm só desenvolvimento e produção. Isso funciona, desde que você teste localmente com cuidado e saiba voltar atrás (mais abaixo).

O que acontece quando você faz um deploy?#

A metodologia Twelve-Factor App divide o processo em três estágios, um bom modelo mental:

1. Build: transforma o código de um commit em algo executável. Busca dependências e compila o que precisa ser compilado.
2. Release: junta o build com a configuração do ambiente (variáveis, chaves, endereços de banco). O resultado está pronto para executar.
3. Run: inicia os processos da aplicação usando uma release escolhida.

Na prática, os passos que você vê são estes:

1. O código chega ao servidor (upload, git pull, imagem de container).
2. As dependências são instaladas (npm ci, pip install -r requirements.txt).
3. Se a linguagem exige, o código é compilado (TypeScript, Go, Rust, Java).
4. A configuração é aplicada.
5. O processo antigo é parado e o novo é iniciado.
6. Você verifica se está funcionando, olhando os logs e testando uma rota ou um comando.

Cada passo falha por um motivo diferente. Dependência que não instala é problema de build. Variável faltando é problema de release. Processo que sai logo após iniciar é problema de run. Saber em qual estágio o erro está já corta metade do diagnóstico.

Por isso build e configuração ficam separados. O que muda entre ambientes (token, URL do banco) não fica dentro do código: entra por variáveis de ambiente, e o mesmo código roda em staging e produção sem alteração.

Quais são as formas de fazer deploy?#

Manual#

Você copia os arquivos para o servidor (SFTP, scp, painel de upload) e reinicia o processo. É simples e serve para aprender. O custo é que o resultado depende da memória de quem fez: um arquivo esquecido, um passo fora de ordem.

Por Git#

Você faz git push e o servidor puxa o código novo e roda os passos. O histórico do Git vira o registro de versões, e cada deploy corresponde a um commit identificável.

Com CI/CD#

CI (integração contínua) roda testes a cada mudança. CD (entrega ou implantação contínua) leva o resultado aprovado até o ambiente. Ferramentas como o GitHub Actions executam esse pipeline a cada push. O ganho é que o caminho é sempre o mesmo, e um commit com teste quebrado nem chega à produção.

Este pipeline do GitHub Actions roda os testes de um projeto Node.js a cada push na main:

name: ci
on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
      - run: npm ci
      - run: npm test

O passo de publicar viria depois do npm test e só rodaria se os testes passassem. Como publicar depende do seu provedor; o passo a passo completo está em deploy automático com GitHub Actions.

Com containers#

Você empacota a aplicação e suas dependências numa imagem, e o deploy passa a ser "rodar essa imagem". Isso reduz o clássico "na minha máquina funciona". Veja o que é Docker.

O que fazer quando um deploy dá errado?#

Ninguém acerta sempre. O que separa um incidente pequeno de um grande é a rapidez para voltar.

• Rollback: voltar à versão anterior. O Twelve-Factor App cita a capacidade de voltar para uma release anterior como recurso típico de ferramentas de deploy. Com Git, a versão anterior é o commit anterior: faça o deploy dele de novo.
• Leia os logs primeiro. A mensagem de erro costuma indicar o estágio (build, configuração ou run).
• Mude uma coisa por vez. Um deploy com cinco alterações é difícil de depurar.
• Faça backup dos dados antes de mudanças arriscadas, principalmente migrações de banco. Código se recupera pelo Git; dados, não.

Erros comuns: esquecer uma variável de ambiente em produção, usar uma versão de runtime diferente da local, depender de um arquivo que está no .gitignore e nunca chega ao servidor, ou fixar uma porta em vez de ler a que a plataforma fornece.

Que termos andam junto com deploy?#

• Pipeline: a sequência automatizada de etapas (testar, construir, publicar).
• Artefato: o resultado do build (um pacote, uma imagem).
• Downtime: tempo em que a aplicação fica fora do ar. Se o processo antigo para antes de o novo iniciar, há uma janela curta de indisponibilidade. Estratégias como blue-green e rolling update existem para reduzi-la, mas exigem infraestrutura que as comporte.
• Ambiente efêmero: um ambiente criado para uma tarefa e descartado depois.
• Hotfix: correção urgente enviada direto para produção.

Como fazer isso na Square Cloud#

Na Square Cloud, as etapas deste guia ficam à vista e sob o seu controle. O código chega por upload de ZIP no painel, pela CLI, pelo GitHub (um push faz o deploy, via GitHub Action oficial ou webhook) ou pela extensão do VS Code. A plataforma não tem etapa de build: ao iniciar, ela instala as dependências (npm install no Node.js quando não existe node_modules, pip install -r requirements.txt no Python), e a saída da instalação aparece nos logs da aplicação. Se o projeto precisa compilar, rode o build no CI e envie o resultado, ou coloque o build no comando de início.

A configuração entra por variáveis de ambiente, definidas por aplicação, e uma mudança vale no próximo restart, sem reenviar o código. O arquivo squarecloud.app (nome, arquivo principal, memória, versão) é opcional: o painel o gera no deploy, ou você o escreve na raiz do projeto. Entre diversos runtimes, como Node.js, Python, Go e Java, há também TypeScript sem etapa de build; veja os runtimes disponíveis hoje em Runtimes.

Para ter um caminho de volta, crie um snapshot manual antes de uma mudança arriscada: ele existe em todo plano e restaura a aplicação inteira. Veja as formas de deploy em recursos e como funcionam os snapshots.