Deployment 과정 프로젝트를 로컬에서 실행하기
이 페이지를 사용하여 추출한 Dream Catcher 프로젝트를 컴퓨터에서 실행할 수 있습니다. 기본 SQLite 데이터베이스를 사용하는 버전이거나 별도의 PostgreSQL 데이터베이스를 사용하는 버전입니다. 먼저 어느 버전인지 확인한 다음 해당 로컬 설정을 따르세요.
먼저 필요한 것
지원되는 LTS 버전의 Node.js를 설치하세요. Node 24를 권장하며 npm이 포함되어 있습니다. 프로젝트에서 가져온 제공자의 API 키와 모델 이름을 준비하세요.
PostgreSQL 버전을 사용하려면 연결할 수 있는 PostgreSQL 데이터베이스와 해당 연결 문자열인 사용자, 비밀번호, 호스트, 데이터베이스를 지정하는 postgresql:// URL이 필요합니다. 로컬에서 PostgreSQL을 실행하지 않는다면 호스팅 서비스의 무료 계정을 사용해도 됩니다. SQLite 버전은 데이터베이스 파일이 포함되어 있으며 별도의 데이터베이스 서비스가 필요하지 않습니다.
추출한 버전 확인하기
추출한 프로젝트에 dreams.db가 있으면 SQLite 지침을 사용하세요. 별도의 데이터베이스 서비스가 필요하지 않습니다. 서버가 DATABASE_URL을 기대하면 PostgreSQL 지침을 사용하고 연결할 수 있는 PostgreSQL 데이터베이스를 준비하세요.
package.json을 포함한 폴더에서 터미널을 열으세요:
$ cd path-to-your-downloaded-project번들된 README는 오래되었습니다
다운로드에 포함된 README는 코드가 Claude와 SQLite에서 OpenAI 또는 Gemini와 PostgreSQL로 변경된 후에도 Claude와 SQLite 애플리케이션을 설명합니다. 다운로드한 package.json, import, 서버 파일을 신뢰의 기준으로 삼으세요.
package.json의 의존성이 버전을 확인해줍니다. PostgreSQL 버전에는 pg가 나타나고, 초기 버전에는 기본 SQLite 드라이버가 나타나며, 서버 파일의 import가 어느 데이터베이스 모듈이 실제로 사용 중인지 보여줍니다.
dreams.db나 DATABASE_URL을 원하는 서버를 찾으세요. 10초 정도의 확인이 나중에 잘못된 지침 세트를 따르는 것을 방지합니다. 로컬 .env 파일 로드하기
다운로드한 서버는 process.env를 읽지만, 시작 명령은 로컬 .env 파일을 로드하지 않습니다. package.json을 열고 다음을 변경하세요:
"start": "node server.js"다음과 같이 변경하세요:
"start": "node --env-file=.env server.js"이는 다른 의존성을 추가하지 않고 Node의 기본 환경 파일 지원을 사용합니다. --env-file로 지정한 파일이 없으면 Node는 오류로 중지되며, 셸에 이미 설정된 변수는 파일의 값보다 우선합니다. AI 엔지니어링 입문 프로젝트도 백엔드에 같은 --env-file 변경이 필요합니다.
.gitignore에 다음 두 줄이 포함되어 있는지 확인하세요:
.env
node_modules/어떤 과정 스냅샷에는 mode_modules라는 오타가 있습니다. 프로젝트를 커밋하기 전에 node_modules/로 수정하세요. Git 핸드북의 파일 무시하기 및 좋은 습관에서 이러한 항목이 중요한 이유를 다룹니다.
--env-file=.env를 추가하여 Node가 설정 파일을 읽도록 하고, `.env와 node_modules/`를 Git에서 제외하세요. 첫 번째 누출된 키로 어떤 과정보다 빠르게 배웠습니다. SQLite 버전 실행하기
Push to GitHub 스냅샷은 기본적으로 OpenAI 구현을 가져옵니다. package.json 옆에 .env를 만드세요:
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=your-model-id
PORT=3001DATABASE_PATH는 선택 사항입니다. 없으면 서버는 프로젝트 폴더의 dreams.db를 사용합니다. 사용자 정의 경로를 설정하면 해당 디렉토리가 존재하고 쓰기 가능한지 확인하세요.
잠금된 의존성을 설치하고 서버를 시작하세요. npm ci는 lockfile의 정확한 버전을 설치하며, 기본 SQLite 패키지는 이것을 필요로 합니다. 운영 체제와 Node 버전으로 컴파일되기 때문입니다:
$ npm ci
$ npm starthttp://localhost:3001/을 열거나 .env에 입력한 포트를 열으세요. Ctrl+C로 서버를 중지하세요.
프로젝트에는 Gemini 구현도 포함되어 있지만, 라우트는 기본적으로 OpenAI 파일을 가져옵니다. 과정의 제공자 전환 코드를 따르면 대신 GEMINI_API_KEY와 선택 사항인 GEMINI_MODEL을 사용하세요.
.env를 만들고, npm ci와 npm start를 실행한 다음 브라우저에서 포트 3001을 열으세요. 데이터베이스 파일이 이미 프로젝트와 함께 제공되므로 여기서는 설정할 추가 사항이 없습니다. PostgreSQL 버전 실행하기
나중 프로젝트는 SQLite를 PostgreSQL로 대체합니다. 먼저 데이터베이스를 만든 다음 연결 문자열을 .env에 AI 구성과 함께 추가하세요:
DATABASE_URL=postgresql://user:password@host:5432/database
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=your-model-id
PORT=3001그다음 실행하세요:
$ npm ci
$ npm start최종 프로젝트는 대기하기 전에 테이블을 초기화합니다. 데이터베이스에 도달할 수 없거나 TLS 설정을 거부하면 시작이 데이터베이스 오류로 중지됩니다. 오류 텍스트는 원인을 가리킵니다. ENOTFOUND는 호스트명이 확인되지 않았다는 뜻이고, password authentication failed는 자격증명이고, SSL 또는 TLS 메시지는 암호화 설정입니다. 과정 코드는 SSL 연결을 요청하므로, TLS 없는 로컬 PostgreSQL은 연결 문자열에서 이 요구사항을 조정해야 합니다. /health 엔드포인트는 시작 후 연결을 확인합니다:
http://localhost:3001/health임시 shutdown 라우트를 제거하세요
Terminating Processes & Signals 강의에는 graceful 종료 테스트를 위해서만 /shutdown 엔드포인트가 포함됩니다. 강의 지침을 따라 애플리케이션을 공유하거나 배포하기 전에 해당 라우트를 삭제하세요. 서버를 종료하는 공개 URL을 남겨두는 것은 안전하지 않습니다.
.env에 입력하고, 앱을 시작한 다음 /health를 방문하여 연결을 확인하세요. 앱을 누구와도 공유하기 전에 임시 shutdown 라우트를 제거하세요. 나도 이 단계를 잊은 적이 있으며, 공유 앱에 남겨두고 싶지 않은 것이 하나 있다면 이것입니다. 문제 해결
OPENAI_API_KEY environment variable is missing or empty: 시작 스크립트에 --env-file=.env가 포함되어 있고, .env가 package.json 옆에 있으며, 변수 이름이 가져온 제공자 파일과 일치하는지 확인하세요.
페이지는 열리지만 꿈 생성이 AI 오류를 반환합니다: 제공자 키와 모델을 함께 확인하세요. 페이지와 기존 꿈 API가 작동하는지 확인하기 위해 실시간 AI 요청은 필요하지 않습니다.
SQLite가 기본 모듈 오류를 보고합니다: 지원되는 Node LTS 릴리스를 사용하여 깨끗한 추출에서 npm ci로 다시 설치하세요. 다른 운영 체제에서 node_modules를 복사하지 마세요.
PostgreSQL 시작이 실패합니다: 전체 DATABASE_URL, 데이터베이스 네트워크 접근, 자격증명 및 TLS 요구사항을 확인하세요. 최종 과정 코드는 SSL 연결을 요청합니다.
버전 전환 후 데이터베이스가 비어 있습니다: dreams.db의 SQLite 데이터는 자동으로 PostgreSQL에 나타나지 않습니다. 과정의 마이그레이션 단계를 실행하거나 새 데이터베이스를 별도로 seed하세요.