Um projeto conecta um repositório a um servidor. É a partir dele que você configura variáveis, dispara deploys e acompanha o app no ar.
Criando o projeto, passo a passo
1
Abra "Projetos" e clique em "Novo projeto"
Na navegação principal do painel. Você precisa ter pelo menos um servidor provisionado antes.
2
Escolha o repositório
Conecte sua conta do GitHub e escolha o repositório numa lista — funciona inclusive com privados, sem configurar chave nenhuma. Prefere colar a URL do Git manualmente? Também funciona.
3
Escolha o servidor e a branch
O servidor é a VPS onde o app vai rodar. A branch é de onde o código vem — quase sempre "main".
4
Informe a porta do app
A porta que o SEU código escuta. Veja a explicação detalhada logo abaixo se tiver dúvida.
5
Domínio (opcional)
Se você já tem um domínio apontando pra VPS, informe aqui pra ganhar HTTPS automático. Sem domínio, o app fica acessível pelo IP — dá pra adicionar o domínio depois.
6
Salve
O projeto é criado, mas nada sobe ainda — o primeiro deploy só acontece quando você clicar em Deploy.
Que porta eu coloco?
É a porta que o seu processo escuta quando roda. Procure no seu código onde o servidor é iniciado — por exemplo, um app Express com app.listen(3000) escuta a porta 3000; um projeto Next.js roda na 3000 por padrão; Django na 8000; Flask na 5000. Se o seu app lê a porta de uma variável de ambiente (process.env.PORT), coloque aqui o mesmo valor que você configurar na variável PORT do projeto.
Nota
Não confunda com a porta 80/443 do site — essa parte é do proxy reverso, que o Zé Preguiça configura sozinho. Você só informa a porta interna do seu processo.
Resumo dos campos
ServidorQual VPS provisionada vai hospedar o projeto
RepositórioEscolhido na lista do GitHub conectado, ou URL colada manualmente
BranchGeralmente main ou production
DomínioOpcional — precisa apontar (registro A) para o IP da VPS
Modo de buildDocker (Nixpacks/Dockerfile) ou Docker Compose — na dúvida, Docker
Porta do containerA porta que o processo escuta (ex: 3000 pra Express/Next)
Diretório raizOpcional — pra monorepos: o subdiretório do repositório onde o app vive. Vazio, usa a raiz
Comando de startOpcional — vazio, o Nixpacks detecta o comando sozinho. Preencha só se quiser sobrescrever
Nota
Nenhum desses campos é definitivo — domínio, branch, porta e variáveis podem ser editados a qualquer momento pela aba de configurações do projeto, sem precisar recriá-lo.
Antes do primeiro deploy
Configure as variáveis de ambiente que o seu app precisa antes de clicar em Deploy pela primeira vez — assim o container já sobe com tudo que precisa, sem precisar de um segundo deploy só para aplicar uma credencial esquecida.
Próximo passo
Entenda a diferença entre os modos de build antes do primeiro deploy — ela define como sua imagem é gerada.