Executar o projeto do curso de Deployment localmente

Use esta página para rodar o projeto Dream Catcher extraído no seu computador. A versão que você tem usa ou o banco SQLite incluído ou um banco PostgreSQL separado. Identifique essa versão primeiro e depois siga o setup 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 importado pelo seu projeto.

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

JunoO que você precisa primeiro Instale Node.js LTS e tenha sua chave de provedor de IA pronta antes de tudo.

Se sua versão usa PostgreSQL, crie esse banco primeiro e mantenha sua string de conexão à mão. O app não consegue iniciar sem ela.

JunoO que você precisa primeiro Node inclui npm, então uma instalação cobre as ferramentas. Apenas a versão posterior precisa de um banco separado, acessado através de uma string de conexão no formato postgresql://user:password@host:5432/database, de uma instalação local ou um serviço hospedado.

JunoO que você precisa primeiro A versão SQLite inicia a partir de seu arquivo de banco incluído. A versão PostgreSQL conecta e cria suas tabelas antes do Express escutar, então acesso à rede, credenciais e TLS precisam funcionar antes que npm start possa ter sucesso.

Identifique a versão que você extraiu

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

As dependências em package.json confirmam: pg aparece na versão PostgreSQL e o driver SQLite nativo sqlite3 aparece na anterior. O import em config/database.js mostra qual módulo de banco o servidor realmente usa.

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, imports e arquivos de servidor como referência.

JunoIdentifique a versão que você extraiu Procure por dreams.db ou um servidor que espere DATABASE_URL. Isso te diz se deve seguir as instruções SQLite ou PostgreSQL, então verifique antes de configurar qualquer coisa.

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

JunoIdentifique a versão que você extraiu Leia as dependências: pg significa PostgreSQL e sqlite3 significa a versão SQLite anterior. O import na configuração do banco mostra qual está ativo, independente do que mais vem na pasta.

Carregue um arquivo .env local

O servidor baixado lê process.env, mas seu comando de início não carrega um arquivo .env local. Abra package.json e mude:

"start": "node server.js"

para:

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

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

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

.env
node_modules/

Verifique a ortografia de ambas as linhas no arquivo baixado antes de fazer commit. O manual Git cobre por que essas entradas importam em ignorando arquivos e boas práticas.

JunoCarregue um arquivo .env local Adicione --env-file=.env ao script de início para que Node leia seu arquivo de configurações.

Depois verifique que .gitignore lista .env e node_modules/, para que suas chaves e pacotes instalados fiquem fora do Git.

JunoCarregue um arquivo .env local O servidor lê process.env, mas nada carrega seu arquivo local nele. A flag --env-file built-in do Node faz esse carregamento sem uma nova dependência, então a mudança de uma linha no script é a solução completa.

JunoCarregue um arquivo .env local Diferente de um loader que ignora silenciosamente um arquivo faltando, --env-file para o Node na inicialização, então um caminho errado falha de forma visível. Uma variável já definida no seu shell vence sobre o mesmo nome no arquivo, então um export antigo de uma sessão anterior mantém seu valor até você fazer unset.

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 ela, 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 travadas e inicie o servidor. npm ci instala exatamente as versões no arquivo lock, e o pacote SQLite nativo precisa de uma instalação limpa porque é compilado para seu sistema operacional e versão do Node:

$ npm ci
$ npm start

> [email protected] start
> node --env-file=.env server.js

Server running on http://localhost:3001

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 no seu navegador.

O arquivo de banco já vem com o projeto, então não há nada mais para configurar.

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

JunoExecute a versão SQLitesqlite3 é um módulo nativo compilado para seu sistema operacional e versão do Node, então uma instalação copiada de outra máquina falha ao carregar. npm ci de uma extração limpa no LTS recomendado o instala corretamente; corrija uma instalação que falha antes de mudar caminhos de banco ou configurações de provedor.

Execute a versão PostgreSQL

O projeto posterior substitui SQLite com PostgreSQL. Crie um banco 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, então Server running on http://localhost:3001 aparece apenas uma vez que o banco responde. Se o banco está inacessível ou rejeita suas configurações TLS, a inicialização para com Failed to initialize database: seguido pelo erro. O texto do erro aponta para a causa: ENOTFOUND significa o hostname não resolveu, password authentication failed significa as credenciais, e uma mensagem SSL ou TLS significa as configurações de criptografia. O código do curso solicita uma conexão SSL, que serve bem para um banco hospedado; se seu PostgreSQL local não tem TLS, as configurações de conexão precisam corresponder.

O endpoint /health verifica a conexão após inicialização:

http://localhost:3001/health

Um servidor saudável responde com JSON que inclui "status": "ok" e "db": "connected". Se o banco cair depois, a mesma URL retorna "db": "disconnected" com a mensagem de erro do banco.

Remova a rota temporária de desligamento

A lição Terminating Processes & Signals inclui um endpoint /shutdown apenas para testar encerramento gracioso. Siga as instruções da lição para deletar essa rota antes de compartilhar ou fazer deploy da aplicação. Deixar uma URL pública que termina seu servidor não é seguro.

JunoExecute a versão PostgreSQL Crie seu banco primeiro, coloque sua string de conexão em .env, inicie o app, depois visite /health e procure por "db": "connected".

Remova a rota temporária de desligamento antes de compartilhar o app com alguém.

JunoExecute a versão PostgreSQL Conectar e criar tabelas acontecem antes do Express escutar, então um problema de rede, credencial ou TLS para a inicialização completamente. Quando o servidor nunca imprime sua linha Server running, procure no banco primeiro, não no código da app.

JunoExecute a versão PostgreSQL Leia o erro de inicialização antes de mudar qualquer coisa: ENOTFOUND é DNS, password authentication failed são credenciais, e uma reclamação SSL é TLS. O pool solicita SSL, então um servidor local sem TLS precisa suas configurações de conexão alinhadas com isso.

Solução de problemas

OPENAI_API_KEY environment variable is missing or empty: Confirme que o script de início contém --env-file=.env, que .env está ao lado de package.json, e que o nome da variável combina com o arquivo de provedor importado.

A página abre mas criar um sonho retorna um erro de IA: Verifique a chave de provedor e 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 relata um erro de módulo nativo: Reinstale de uma extração limpa com a versão LTS do Node suportada, usando npm ci. Não copie node_modules de outro sistema operacional.

Inicialização do PostgreSQL falha: Leia o erro após Failed to initialize database:, depois verifique a DATABASE_URL completa, acesso à rede do banco, credenciais e requisitos de TLS. O código final do curso solicita uma conexão SSL.

O banco está vazio após mudar versões: Dados SQLite em dreams.db não aparecem automaticamente em PostgreSQL. Execute os passos de migração do curso ou seed o novo banco separadamente.

JunoSolução de problemas Verifique carregamento de ambiente primeiro, depois o provedor, depois o banco, nessa ordem.

Dados SQLite não se movem para PostgreSQL sozinhos, então uma lista de sonhos vazia após mudar é esperada até você migrar ou fazer seed.

JunoSolução de problemas Separe problemas de dependência, requisições de provedor, caminhos SQLite e conectividade PostgreSQL antes de mudar o projeto. Dados não se movem sozinhos entre as duas versões; migre ou faça seed do novo banco deliberadamente.

JunoSolução de problemas Debug em ordem de inicialização: carregamento de .env, depois a instalação SQLite ou a conexão e TLS do PostgreSQL, depois setup de tabelas, depois a requisição de provedor. O primeiro erro no terminal é geralmente a causa; o que o segue é frequentemente uma consequência.