Guia do cliente

Publicando seu site Node.js

Como preparar, enviar e atualizar uma aplicação Node no seu plano de hospedagem, usando apenas o acesso FTP que você já tem.

Como funciona

Um site em PHP ou WordPress é executado sob demanda: cada visita dispara o código e ele termina. Basta enviar os arquivos e o site está no ar.

Uma aplicação Node funciona de outro jeito: o seu código é o servidor. Ele precisa estar em execução o tempo todo, esperando as visitas. Por isso, além de enviar os arquivos, existe um segundo passo — colocar essa aplicação em execução — que é feito por nós, do lado do servidor.

Na prática: você envia por FTP e nos avisa; nós publicamos. Não é preciso ter acesso a terminal nem conhecer o servidor.

Antes de enviar: três requisitos

Estes três pontos são o que costuma impedir uma aplicação de subir. Vale conferir antes do primeiro envio.

1. A aplicação precisa aceitar a porta que informamos

Cada aplicação do servidor recebe uma porta interna própria. Se o seu código fixar um número, haverá conflito com outro site. Leia a porta do ambiente:

// certo — usa a porta que o servidor informa
const porta = process.env.PORT || 3000;
const host  = process.env.HOST || '127.0.0.1';
app.listen(porta, host);

// errado — porta fixa, e aberta para fora
app.listen(3000);

O host importa tanto quanto a porta: 127.0.0.1 significa que apenas o servidor web conversa com a aplicação, e é ele quem cuida do domínio, do HTTPS e do certificado.

2. Envie a versão já compilada

Se o seu projeto usa TypeScript, um empacotador ou qualquer etapa de build, rode essa etapa no seu computador e envie o resultado. O servidor não compila código.

3. Inclua o `package-lock.json`

É esse arquivo que garante que as bibliotecas instaladas no servidor sejam exatamente as mesmas que você testou. Sem ele, as versões podem divergir e a aplicação se comportar de forma diferente da sua máquina.

O que enviar

Enviar	Não enviar
Código da aplicação (já compilado) `package.json` `package-lock.json` Migrations ou scripts de banco Arquivos do site (HTML, CSS, JS, imagens)	`node_modules` `.git` Código-fonte não compilado Testes e arquivos de desenvolvimento Arquivos `.zip` do projeto

Nunca envie a pasta node_modules

Ela costuma ter dezenas de milhares de arquivos: o envio levaria horas e provavelmente falharia no meio. Além disso, algumas bibliotecas contêm partes compiladas para o seu computador, que não funcionam no servidor.

Nós instalamos as bibliotecas no servidor a partir do package-lock.json, já na versão correta para a máquina.

Onde enviar

Ao entrar no FTP, você verá duas pastas. Cada uma tem uma finalidade, e a diferença entre elas protege seus dados.

/ ├── public_html/ ← tudo aqui é público na internet │ HTML, CSS, JS, imagens: o que o visitante baixa │ └── app/ ← nada aqui é acessível pela internet o código da aplicação, senhas e arquivos internos

Senhas e chaves só em `app/`

Qualquer arquivo dentro de public_html pode ser baixado por qualquer pessoa que saiba o endereço. Um arquivo de configuração com a senha do banco colocado ali fica acessível publicamente — é uma das causas mais comuns de vazamento de dados.

A pasta app/ existe exatamente para isso: é onde ficam o código, as chaves e tudo que não deve ser público.

Diga se a aplicação entrega as próprias páginas

Uma aplicação pode ser o site inteiro — telas, login, formulários — ou apenas uma API que responde dados para páginas enviadas ao public_html. Em disco as duas são iguais: não há como descobrir pelo código, por isso perguntamos no pedido de publicação, com duas opções numeradas.

Sem a resposta, configuramos como API — só os endereços que começam com /api vão para a aplicação. Se ela na verdade entregar as páginas, quem digitar o endereço verá o conteúdo do public_html em vez do seu sistema, e isso só aparece depois de publicado.

Mesmo quando a aplicação entrega as páginas, envie ao menos um index.html para o public_html. É a página que o visitante vê se o direcionamento ainda não estiver ativo, ou enquanto a aplicação reinicia, no lugar de uma mensagem de erro do servidor.

Configurações e senhas

Aplicações costumam precisar de senha de banco, chaves de API e outros segredos. O caminho normal é um arquivo chamado .env dentro da pasta app/, com uma configuração por linha:

DATABASE_URL=mysql://usuario:senha@localhost:3306/banco
JWT_SECRET=uma-frase-longa-e-aleatoria
API_KEY=...

Envie esse arquivo pelo FTP, não por mensagem

E-mail e aplicativos de mensagem guardam cópias em vários lugares, fora do seu controle e do nosso. O FTP entrega o arquivo direto na sua conta.

Se precisar que nós criemos o banco de dados, peça — enviamos as credenciais pelo painel, e você as coloca no .env.

O `.env` vai uma vez só

Ele pertence ao servidor: é enviado na primeira publicação e fica lá. Não o inclua nos envios de atualização — reenviar o arquivo da sua máquina sobrescreve a configuração de produção, e a aplicação passa a apontar para o banco errado, ou nem sobe.

Senha do banco: só letras e números

O painel não aceita caracteres especiais como #, $, @, % e & na senha do usuário do banco. Se a senha no .env for diferente da que ficou no painel, o banco recusa a aplicação: o site abre, mas o login e tudo que depende de dados falha.

Compense a falta de símbolos com o tamanho — 32 caracteres ou mais. Este comando gera uma senha assim no seu computador:

node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"

O mesmo cuidado vale para os outros valores do .env: um # fora de aspas corta o valor ali, porque o resto da linha passa a ser lido como comentário. Se um segredo precisar de símbolos, escreva-o entre aspas simples.

Pedindo a publicação

Depois de enviar os arquivos, nos avise. Para agilizar, mande estas informações junto — são as que precisamos para configurar:

Informações para o primeiro envio

Domínio do site.
Como a aplicação é usada — responda 1 ou 2. É a única informação que não conseguimos tirar do código, e a resposta errada faz o site abrir na página errada:
1. Entrega as próprias páginas. Quem digita o endereço vê telas geradas pela aplicação — um sistema com login, painel e formulários, por exemplo. Todo o domínio vai para ela.
2. É uma API. A aplicação só responde dados, e as páginas são arquivos que você envia para o public_html — um frontend em React ou Vue já compilado, por exemplo. Só os endereços que começam com /api vão para ela.
Arquivo que inicia a aplicação — só se for diferente do que está no start do seu package.json. Normalmente não é preciso informar: descobrimos pelo que você enviou, olhando primeiro o start, depois o main, e por fim nomes comuns como dist/server.js ou index.js.
Versão do Node que a aplicação usa. Se não souber, informe a versão do seu computador (node -v). Mantemos algumas versões instaladas e acrescentamos a que o seu projeto precisar — diga antes do envio, não depois.
Precisa de banco de dados? Se sim, qual tipo, e se você tem um arquivo de dados para importar.
Comandos especiais antes de subir, se houver — criação de tabelas, importação inicial, algo do tipo.

Com isso configuramos a aplicação, instalamos as bibliotecas, criamos o banco se necessário e colocamos tudo no ar. Avisamos quando estiver pronto.

Atualizações depois

A partir da segunda vez, é mais simples — a configuração já está feita.

Compile a nova versão no seu computador.
Envie os arquivos alterados por FTP, substituindo os antigos.
Avise que enviou.

Reiniciamos a aplicação para que a nova versão entre em uso. Só as páginas e imagens em public_html valem imediatamente — o código em app/ continua rodando a versão anterior até o reinício.

Se mudaram as bibliotecas ou o banco

Avise quando o package.json tiver bibliotecas novas ou quando houver mudanças na estrutura do banco. São passos extras da nossa parte, e sem eles a aplicação pode não subir.

Limites e boas práticas

Cada aplicação tem um limite de memória. Se ela ultrapassar, é encerrada e reiniciada automaticamente — o que aparece como instabilidade. Se acontecer, avise: revisamos juntos se é vazamento de memória ou se o limite precisa aumentar.
A aplicação reinicia sozinha se travar, e volta sozinha se o servidor for reiniciado. Não é preciso nos avisar nesses casos.
Guarde os registros de erro pela sua aplicação, ou peça os logs do servidor quando precisar investigar algo.
Teste antes de enviar. Não há ambiente de testes no plano de hospedagem: o que você envia vai para o ar.
Mantenha uma cópia local de tudo que enviar. Fazemos backup do servidor, mas a versão original do seu projeto é responsabilidade sua.

Ficou alguma dúvida sobre o seu caso específico? Escreva antes de enviar — é mais rápido ajustar o que for preciso antes da publicação do que depois.

Pronto para publicar?

Envie os arquivos pelo FTP e fale com a nossa equipe para colocarmos a sua aplicação no ar.

Falar com o suporte Painel de controle