docs: Coolify DATABASE_URL 인코딩(%20/%3D) 명확화 + 7번 정리
- 12번/예시/FAQ: search_path 가 URL 인코딩(%20,%3D)된 형태임을 명시(.project-env 그대로 복사 안내) - 7번 (4): 설치만 남기고 실행/AI 안내는 8~9번으로 정리(중복 제거) - 11번: myapp 은 본인 프로젝트명으로 바꾸라는 주의 추가 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
infra
29
MANUAL.md
29
MANUAL.md
@@ -135,25 +135,12 @@ new-project myapp # sample 을 ~/projects/myapp 으로 복사 + .project-e
|
||||
> 폴더를 열면 VS Code 가 그 폴더를 "작업 공간"으로 삼습니다. 이제 왼쪽 목록에서 파일을 눌러 편집하고,
|
||||
> 터미널도 자동으로 그 폴더(`~/projects/myapp`)에서 시작됩니다.
|
||||
|
||||
**(4) 실행** — 다시 터미널(Terminal → New Terminal)에서:
|
||||
**(4) 라이브러리 설치** — 다시 터미널(Terminal → New Terminal)에서:
|
||||
```bash
|
||||
npm install # 처음 1회: 필요한 라이브러리 설치 (이걸 안 하면 실행이 실패합니다)
|
||||
npm run dev # 앱 실행 (실행·미리보기는 9번 참고)
|
||||
```
|
||||
동작 확인 엔드포인트:
|
||||
- `GET /healthz` — 살아있는지
|
||||
- `GET /db` — 내 DB(Postgres) 연결 확인
|
||||
- `GET /s3` — MinIO(파일 저장소) 연결 확인
|
||||
|
||||
**(5) AI 에이전트(Claude 등) 실행** — **반드시 본인 프로젝트 폴더 안에서** 실행해야 합니다.
|
||||
AI 도구는 "지금 있는 폴더"를 작업 대상으로 삼기 때문에, 폴더가 틀리면 엉뚱한 곳을 봅니다.
|
||||
```bash
|
||||
cd ~/projects/myapp # ← 먼저 본인 프로젝트 폴더로 이동 (이미 그 폴더면 생략)
|
||||
claude # Claude Code 실행 (또는 codex / gemini)
|
||||
```
|
||||
> 위 (3)에서 **File → Open Folder 로 그 폴더를 열어 두었다면**, 새로 연 터미널은 이미 그 폴더에서
|
||||
> 시작하므로 `cd` 없이 바로 `claude` 만 입력해도 됩니다.
|
||||
> AI 키를 아직 안 넣었으면 5번(`update-litellm-key`)을 먼저 하세요.
|
||||
여기까지 하면 프로젝트 준비 완료입니다. **이제 8번부터 본격적으로 개발**하면 됩니다(코드 편집 → AI 활용 → 실행 → 배포).
|
||||
|
||||
> **`.project-env` 가 그 프로젝트의 설정 파일입니다** (DB·S3). 값을 바꾸려면 이 파일 한 곳만 고치면 됩니다.
|
||||
> 프로젝트 폴더에 들어가면(cd) 자동으로 환경변수에 반영됩니다. (git에는 올라가지 않습니다)
|
||||
@@ -180,7 +167,7 @@ claude # Claude Code 실행 (또는 codex / gemini)
|
||||
(7번에서 **File → Open Folder 로 본인 프로젝트 폴더를 열어 둔 상태**에서)
|
||||
|
||||
- **코드 편집**: 왼쪽 파일 목록에서 파일(예: `src/server.js`)을 눌러 수정 → **Ctrl+S 로 저장**.
|
||||
- **AI 도구 활용**: 터미널에서 `claude`(또는 `codex`/`gemini`) 실행. **반드시 프로젝트 폴더 안에서** 실행해야 그 프로젝트를 봅니다(7번 (5) 참고). 키 설정은 5번.
|
||||
- **AI 도구 활용**: 터미널에서 `claude`(또는 `codex`/`gemini`) 실행. **반드시 본인 프로젝트 폴더 안에서** 실행해야 그 프로젝트를 봅니다(폴더를 Open Folder 해뒀으면 새 터미널은 이미 그 폴더에서 시작). 키 설정은 5번.
|
||||
- **내 DB 직접 접속**(필요 시):
|
||||
```bash
|
||||
cd ~/projects/<본인 프로젝트> # 프로젝트 폴더에서 (그래야 .project-env 가 로드됨)
|
||||
@@ -269,6 +256,8 @@ curl 127.0.0.1:3000/s3 # 파일저장소 연결 확인
|
||||
`new-project` 로 만든 폴더는 아직 git 저장소가 아닙니다(`.git` 없음). 아래처럼 올립니다.
|
||||
(배포(12번)는 Gitea repo 를 받아서 빌드하므로, 배포 전에 반드시 올려야 합니다.)
|
||||
|
||||
> 아래 명령의 `myapp` 은 **본인이 `new-project` 로 만든 프로젝트 이름**으로 바꿔 쓰세요.
|
||||
|
||||
**1) Gitea에 빈 저장소 만들기**
|
||||
- **https://gitea.bokdev.in** → 우측 상단 **`+` → New Repository**
|
||||
- Repository Name 입력(예: `myapp`)
|
||||
@@ -306,9 +295,11 @@ git push -u origin main
|
||||
|
||||
**2) 환경변수 입력** (앱마다 **최초 1회만**, 이후 배포엔 유지됨)
|
||||
- Coolify의 **Environment Variables** 에 입력: `DATABASE_URL`, `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `PORT`
|
||||
- **워크스페이스 `.project-env` 의 값을 그대로 복사해 넣으면 됩니다**(DB host 포함 동일):
|
||||
- **가장 쉬운 방법: 워크스페이스 `.project-env` 파일을 열어 그 안의 값을 한 줄씩 그대로 복사**해 넣으세요(DB host 포함 동일, 변형 금지).
|
||||
- 파일 보기: 터미널에서 `cat ~/projects/myapp/.project-env` (또는 VS Code 에서 그 파일 열기)
|
||||
- `DATABASE_URL` 은 아래처럼 생겼습니다. **`%20`·`%3D` 까지 그대로** 넣으세요(libpq 인코딩이라 빼면 DB 연결이 깨집니다):
|
||||
```
|
||||
DATABASE_URL=postgresql://emp_<사번>:<pw>@10.200.0.152:5432/appdb?options=-c search_path=emp_<사번>
|
||||
DATABASE_URL=postgresql://emp_<사번>:<pw>@10.200.0.152:5432/appdb?options=-c%20search_path%3Demp_<사번>
|
||||
```
|
||||
|
||||
**3) 배포 + 확인**
|
||||
@@ -336,7 +327,7 @@ git push -u origin main
|
||||
- **Q. sample 을 고쳤는데 git pull 이 안 돼요** → sample 은 참조용(읽기 전용)입니다. `new-project <이름>` 으로 복사한 폴더에서 작업하세요(7번).
|
||||
- **Q. git push가 인증을 물어봐요** → Gitea Authorize를 한 번도 안 했을 때. 6번 참고.
|
||||
- **Q. Coolify 배포가 `does not appear to be a git repository` 로 실패해요** → Repository URL 을 전체 주소(`https://gitea.bokdev.in/...git`)로 넣었는지 확인하세요(12번).
|
||||
- **Q. 배포한 앱에서 DB 연결이 안 돼요(`/db` 500)** → Coolify Env 의 `DATABASE_URL` host 가 `10.200.0.152` 인지 확인하세요. 컨테이너명/내부 DNS 는 배포 환경에선 안 됩니다(12번).
|
||||
- **Q. 배포한 앱에서 DB 연결이 안 돼요(`/db` 500)** → ① Coolify Env 의 `DATABASE_URL` host 가 `10.200.0.152` 인지, ② 끝의 `?options=-c%20search_path%3D...` 가 `%20`/`%3D` 까지 그대로인지 확인하세요. 직접 타이핑하다 인코딩을 빼면 깨집니다 — `.project-env` 값을 그대로 복사하는 게 가장 안전합니다(12번). 컨테이너명/내부 DNS 는 배포 환경에선 안 됩니다.
|
||||
- **Q. `npm run dev` 가 `Cannot find package 'express'` 로 실패해요** → 처음 1회 `npm install` 을 안 한 경우입니다. 프로젝트 폴더에서 `npm install` 후 다시 실행하세요(7번).
|
||||
- **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다.
|
||||
- **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다.
|
||||
|
||||
Reference in New Issue
Block a user