Executando o projeto do curso de Deployment localmente

Use esta página para executar o projeto Dream Catcher extraído no seu computador. A versão que você tem usa ou o banco de dados SQLite incluído ou um banco de dados PostgreSQL separado. Identifique essa versão primeiro, depois siga a configuração local correspondente.

O que você precisa primeiro

Instale uma versão LTS suportada do Node.js. Node 24 é recomendado e inclui npm. Prepare uma chave e um nome de modelo para o provedor que seu projeto importa.

A versão PostgreSQL também precisa de um banco de dados PostgreSQL acessível e sua string de conexão, a URL postgresql:// que identifica seu usuário, senha, host e banco de dados. O nível gratuito de um serviço hospedado funciona se você não executar PostgreSQL localmente. A versão SQLite inclui seu arquivo de banco de dados e não precisa de um serviço de banco de dados separado.

JunoO que você precisa primeiro Instale o Node.js LTS e tenha sua chave do provedor de IA pronta antes de qualquer outra coisa. Se sua versão usa PostgreSQL, crie esse banco de dados primeiro; já cometi o erro de iniciar o app antes do banco de dados existir, e ele falhou na inicialização todas as vezes!

JunoO que você precisa primeiro O Node inclui npm, então uma instalação cobre todas as ferramentas. Apenas a versão posterior precisa de um banco de dados separado: uma string de conexão da forma postgresql://user:password@host:5432/database, de uma instalação local ou do nível gratuito de um serviço hospedado.

JunoO que você precisa primeiro A versão SQLite inicia a partir de seu arquivo de banco de dados incluído; a do PostgreSQL nem mesmo ouvirá até seu banco de dados estar acessível. Configure o acesso de rede, credenciais e TLS antes de npm start, não depois do primeiro stack trace.

Identifique a versão que você extraiu

Se o projeto extraído inclui dreams.db, use as instruções de SQLite. Não precisa de um serviço de banco de dados separado. Se seu servidor espera DATABASE_URL, use as instruções de PostgreSQL e prepare um banco de dados PostgreSQL acessível.

Abra um terminal na pasta que contém package.json:

$ cd path-to-your-downloaded-project

O README incluído está desatualizado

O README nos downloads descreve uma aplicação Claude e SQLite mesmo depois que o código migrou para OpenAI ou Gemini e PostgreSQL. Use o package.json baixado, as importações e os arquivos do servidor como fonte da verdade.

As dependências em package.json confirmam a versão: pg aparece na versão PostgreSQL, um driver SQLite nativo aparece na anterior, e a importação do arquivo de servidor mostra qual módulo de banco de dados está ativo.

JunoIdentifique a versão que você extraiu Procure por dreams.db ou um servidor que quer DATABASE_URL; isso diz qual conjunto de instruções seguir. Dez segundos de verificação agora economizam seu tempo de seguir o conjunto errado de instruções depois.

JunoIdentifique a versão que você extraiu A migração muda tanto o banco de dados quanto os valores de ambiente necessários, então identifique antes de configurar. Confie no código extraído e em package.json em vez do README, que descreve um snapshot mais antigo.

JunoIdentifique a versão que você extraiu Leia as dependências em package.json: pg significa a versão PostgreSQL, e um driver SQLite nativo significa a anterior. A importação do arquivo de servidor mostra qual está realmente ativa, não importa o que mais esteja na pasta. Confio em importações em vez de READMEs, e este download é um bom exemplo do porquê.

Carregue um arquivo .env local

O servidor baixado lê process.env, mas seu comando de inicialização não carrega um arquivo .env local. Abra package.json e altere:

"start": "node server.js"

para:

"start": "node --env-file=.env server.js"

Isso usa o suporte de arquivo de ambiente integrado do Node sem adicionar outra dependência. Node para com um erro se o arquivo nomeado por --env-file estiver faltando, e variáveis já definidas em seu shell têm precedência sobre os valores do arquivo. O projeto Intro to AI Engineering precisa da mesma mudança --env-file em seu backend.

Certifique-se de que .gitignore contém ambas as linhas:

.env
node_modules/

Um snapshot do curso contém o typo mode_modules; corrija para node_modules/ antes de fazer commit do seu projeto. O manual Git explica por que essas entradas importam em ignoring files and good habits.

JunoCarregue um arquivo .env local Adicione --env-file=.env ao script de inicialização para que Node leia seu arquivo de configurações, e mantenha .env e node_modules/ fora do Git. Minha primeira chave vazada me ensinou essa lição mais rápido do que qualquer curso poderia.

JunoCarregue um arquivo .env local O servidor lê process.env, mas nada carrega seu arquivo local nele. A flag --env-file integrada do Node faz esse carregamento sem adicionar uma dependência, então faça a mudança de script de uma linha e continue.

JunoCarregue um arquivo .env local O pacote dotenv continua silenciosamente quando seu arquivo está faltando, enquanto --env-file para o Node com um erro, que transforma uma má configuração silenciosa em uma falha imediata na inicialização. Uma variável já definida em seu shell sempre tem precedência sobre o mesmo nome no arquivo, então um export antigo de uma sessão anterior continua vencendo até você limpá-lo. Já perdi tempo real com um desses exports antigos.

Execute a versão SQLite

O snapshot Push to GitHub importa a implementação OpenAI por padrão. Crie .env ao lado de package.json:

OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=your-model-id
PORT=3001

DATABASE_PATH é opcional. Sem ele, o servidor usa dreams.db na pasta do projeto. Se você definir um caminho customizado, certifique-se de que seu diretório existe e é gravável.

Instale as dependências bloqueadas e inicie o servidor. npm ci instala exatamente as versões no lockfile, e o pacote SQLite nativo precisa disso, porque é compilado para seu sistema operacional e versão do Node:

$ npm ci
$ npm start

Abra http://localhost:3001/, ou a porta que você colocou em .env. Pare o servidor com Ctrl+C.

O projeto também contém uma implementação Gemini, mas a rota importa o arquivo OpenAI por padrão. Se você seguir o código de alternância de provedor do curso, use GEMINI_API_KEY e opcionalmente GEMINI_MODEL em vez disso.

JunoExecute a versão SQLite Crie .env, execute npm ci e npm start, depois abra a porta 3001 em seu navegador. O arquivo de banco de dados já vem com o projeto, então não há nada extra para você configurar aqui.

JunoExecute a versão SQLite O arquivo do provedor importado decide quais variáveis de IA você precisa, então combine os nomes com a importação. Uma página funcionando e uma lista de sonhos provam que o banco de dados funciona. Não provam nada sobre a requisição de IA, então crie um novo sonho para confirmar o provedor também.

JunoExecute a versão SQLite O driver SQLite é um módulo nativo, compilado para seu exato sistema operacional e versão principal do Node, então uma instalação levada de outra máquina falha ao carregar. npm ci na LTS recomendada de uma extração limpa o reconstrói corretamente. Quando a instalação falha, corrija isso antes de alterar caminhos de banco de dados ou configurações de provedor.

Execute a versão PostgreSQL

O projeto posterior substitui SQLite por PostgreSQL. Crie um banco de dados primeiro, depois adicione sua string de conexão a .env junto com a configuração de IA:

DATABASE_URL=postgresql://user:password@host:5432/database
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=your-model-id
PORT=3001

Depois execute:

$ npm ci
$ npm start

O projeto final inicializa suas tabelas antes de escutar. Se o banco de dados estiver inacessível ou rejeitar suas configurações de TLS, a inicialização para com um erro de banco de dados. O texto do erro aponta para a causa: ENOTFOUND significa o nome do host não foi resolvido, password authentication failed significa as credenciais, e uma mensagem de SSL ou TLS significa as configurações de criptografia. O código do curso solicita uma conexão SSL, então um PostgreSQL local sem TLS precisa ter esse requisito ajustado na string de conexão. O endpoint /health verifica a conexão após a inicialização:

http://localhost:3001/health

Remova a rota de desligamento temporária

A lição Terminating Processes & Signals inclui um endpoint /shutdown apenas para testar encerramento gracioso. Siga a instrução da lição para deletar essa rota antes de compartilhar ou implantar a aplicação. Deixar uma URL pública que encerra seu servidor é inseguro.

JunoExecute a versão PostgreSQL Crie seu banco de dados primeiro, coloque sua string de conexão em .env, inicie o app, depois visite /health para confirmar a conexão. Remova a rota de desligamento temporária antes de compartilhar o app com qualquer pessoa; já esqueci dessa etapa eu mesmo, e não é uma que você quer deixar em um app compartilhado.

JunoExecute a versão PostgreSQL Conexão de banco de dados e inicialização de tabelas acontecem antes do Express escutar, então problemas de rede, credenciais ou TLS param a inicialização completamente. Quando o servidor nunca imprime sua linha de escuta, procure no banco de dados primeiro, não no código da app.

JunoExecute a versão PostgreSQL Leia o erro de inicialização antes de alterar qualquer coisa: ENOTFOUND é DNS, password authentication failed é credenciais, e uma reclamação de SSL é TLS. O código do curso solicita SSL, então um PostgreSQL local sem TLS precisa que a string de conexão seja ajustada. Já escolhi a errada desses três causes mais de uma vez.

Solução de problemas

OPENAI_API_KEY environment variable is missing or empty: Confirme que o script de inicialização contém --env-file=.env, que .env fica ao lado de package.json, e que o nome da variável corresponde ao arquivo do provedor importado.

A página abre mas criar um sonho retorna um erro de IA: Verifique a chave do provedor e o modelo juntos. Nenhuma requisição de IA ao vivo é necessária para verificar que a página e a API de sonho existente funcionam.

SQLite reporta um erro de módulo nativo: Reinstale de uma extração limpa com a versão LTS suportada do Node, usando npm ci. Não copie node_modules de outro sistema operacional.

A inicialização do PostgreSQL falha: Verifique a DATABASE_URL completa, acesso de rede ao banco de dados, credenciais e requisitos de TLS. O código final do curso solicita uma conexão SSL.

O banco de dados está vazio após alternar versões: Os dados de SQLite em dreams.db não aparecem automaticamente no PostgreSQL. Execute as etapas de migração do curso ou semeie o novo banco de dados separadamente.

JunoSolução de problemas Verifique o carregamento de ambiente primeiro, depois o provedor, depois o banco de dados, nessa ordem. E lembre-se de que dados SQLite não se movem para PostgreSQL automaticamente; já fiquei olhando para uma lista de sonhos vazia por muito tempo antes de entender isso.

JunoSolução de problemas Separe problemas de dependência, requisições de provedor, caminhos de SQLite e conectividade de PostgreSQL antes de alterar o projeto. Os dados não se movem sozinhos entre as versões SQLite e PostgreSQL; migre ou semeie o novo banco de dados deliberadamente.

JunoSolução de problemas Depure em ordem de inicialização: carregamento de .env, depois a instalação de SQLite ou a conexão e TLS de PostgreSQL, depois configuração de tabelas, depois a requisição do provedor. O primeiro erro no terminal é o real; tudo impresso depois dele geralmente é uma consequência daquele primeiro erro.