playground/sample
121
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Coolify DATABASE_URL 인코딩(%20/%3D) 명확화 + 7번 정리

Browse Source 
- 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
2026-06-15 08:57:20 +09:00
parent fde15978ab
commit 8f999a42a0
1 changed files with 10 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
MANUAL.md
View File

@@ -135,25 +135,12 @@ new-project myapp # sample 을 ~/projects/myapp 으로 복사 + .project-e
> 폴더를 열면 VS Code 가 그 폴더를 "작업 공간"으로 삼습니다. 이제 왼쪽 목록에서 파일을 눌러 편집하고, > 폴더를 열면 VS Code 가 그 폴더를 "작업 공간"으로 삼습니다. 이제 왼쪽 목록에서 파일을 눌러 편집하고,
> 터미널도 자동으로 그 폴더(`~/projects/myapp`)에서 시작됩니다. > 터미널도 자동으로 그 폴더(`~/projects/myapp`)에서 시작됩니다.
**(4) 실행** — 다시 터미널(Terminal → New Terminal)에서: **(4) 라이브러리 설치** — 다시 터미널(Terminal → New Terminal)에서:
```bash ```bash
npm install # 처음 1회: 필요한 라이브러리 설치 (이걸 안 하면 실행이 실패합니다) npm install # 처음 1회: 필요한 라이브러리 설치 (이걸 안 하면 실행이 실패합니다)
npm run dev # 앱 실행 (실행·미리보기는 9번 참고)
``` ```
동작 확인 엔드포인트:
- `GET /healthz` — 살아있는지
- `GET /db` — 내 DB(Postgres) 연결 확인
- `GET /s3` — MinIO(파일 저장소) 연결 확인
**(5) AI 에이전트(Claude 등) 실행** — **반드시 본인 프로젝트 폴더 안에서** 실행해야 합니다. 여기까지 하면 프로젝트 준비 완료입니다. **이제 8번부터 본격적으로 개발**하면 됩니다(코드 편집 → AI 활용 → 실행 → 배포).
AI 도구는 "지금 있는 폴더"를 작업 대상으로 삼기 때문에, 폴더가 틀리면 엉뚱한 곳을 봅니다.
```bash
cd ~/projects/myapp # ← 먼저 본인 프로젝트 폴더로 이동 (이미 그 폴더면 생략)
claude # Claude Code 실행 (또는 codex / gemini)
```
> 위 (3)에서 **File → Open Folder 로 그 폴더를 열어 두었다면**, 새로 연 터미널은 이미 그 폴더에서
> 시작하므로 `cd` 없이 바로 `claude` 만 입력해도 됩니다.
> AI 키를 아직 안 넣었으면 5번(`update-litellm-key`)을 먼저 하세요.
> **`.project-env` 가 그 프로젝트의 설정 파일입니다** (DB·S3). 값을 바꾸려면 이 파일 한 곳만 고치면 됩니다. > **`.project-env` 가 그 프로젝트의 설정 파일입니다** (DB·S3). 값을 바꾸려면 이 파일 한 곳만 고치면 됩니다.
> 프로젝트 폴더에 들어가면(cd) 자동으로 환경변수에 반영됩니다. (git에는 올라가지 않습니다) > 프로젝트 폴더에 들어가면(cd) 자동으로 환경변수에 반영됩니다. (git에는 올라가지 않습니다)
@@ -180,7 +167,7 @@ claude # Claude Code 실행 (또는 codex / gemini)
(7번에서 **File → Open Folder 로 본인 프로젝트 폴더를 열어 둔 상태**에서) (7번에서 **File → Open Folder 로 본인 프로젝트 폴더를 열어 둔 상태**에서)
- **코드 편집**: 왼쪽 파일 목록에서 파일(예: `src/server.js`)을 눌러 수정 → **Ctrl+S 로 저장**. - **코드 편집**: 왼쪽 파일 목록에서 파일(예: `src/server.js`)을 눌러 수정 → **Ctrl+S 로 저장**.
- **AI 도구 활용**: 터미널에서 `claude`(또는 `codex`/`gemini`) 실행. **반드시 프로젝트 폴더 안에서** 실행해야 그 프로젝트를 봅니다(7번 (5) 참고). 키 설정은 5번. - **AI 도구 활용**: 터미널에서 `claude`(또는 `codex`/`gemini`) 실행. **반드시 본인 프로젝트 폴더 안에서** 실행해야 그 프로젝트를 봅니다(폴더를 Open Folder 해뒀으면 새 터미널은 이미 그 폴더에서 시작). 키 설정은 5번.
- **내 DB 직접 접속**(필요 시): - **내 DB 직접 접속**(필요 시):
```bash ```bash
cd ~/projects/<본인 프로젝트> # 프로젝트 폴더에서 (그래야 .project-env 가 로드됨) cd ~/projects/<본인 프로젝트> # 프로젝트 폴더에서 (그래야 .project-env 가 로드됨)
@@ -269,6 +256,8 @@ curl 127.0.0.1:3000/s3 # 파일저장소 연결 확인
`new-project` 로 만든 폴더는 아직 git 저장소가 아닙니다(`.git` 없음). 아래처럼 올립니다. `new-project` 로 만든 폴더는 아직 git 저장소가 아닙니다(`.git` 없음). 아래처럼 올립니다.
(배포(12번)는 Gitea repo 를 받아서 빌드하므로, 배포 전에 반드시 올려야 합니다.) (배포(12번)는 Gitea repo 를 받아서 빌드하므로, 배포 전에 반드시 올려야 합니다.)
> 아래 명령의 `myapp` 은 **본인이 `new-project` 로 만든 프로젝트 이름**으로 바꿔 쓰세요.
**1) Gitea에 빈 저장소 만들기** **1) Gitea에 빈 저장소 만들기**
- **https://gitea.bokdev.in** → 우측 상단 **`+` → New Repository** - **https://gitea.bokdev.in** → 우측 상단 **`+` → New Repository**
- Repository Name 입력(예: `myapp`) - Repository Name 입력(예: `myapp`)
@@ -306,9 +295,11 @@ git push -u origin main
**2) 환경변수 입력** (앱마다 **최초 1회만**, 이후 배포엔 유지됨) **2) 환경변수 입력** (앱마다 **최초 1회만**, 이후 배포엔 유지됨)
- Coolify의 **Environment Variables** 에 입력: `DATABASE_URL`, `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `PORT` - 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) 배포 + 확인** **3) 배포 + 확인**
@@ -336,7 +327,7 @@ git push -u origin main
- **Q. sample 을 고쳤는데 git pull 이 안 돼요** → sample 은 참조용(읽기 전용)입니다. `new-project <이름>` 으로 복사한 폴더에서 작업하세요(7번). - **Q. sample 을 고쳤는데 git pull 이 안 돼요** → sample 은 참조용(읽기 전용)입니다. `new-project <이름>` 으로 복사한 폴더에서 작업하세요(7번).
- **Q. git push가 인증을 물어봐요** → Gitea Authorize를 한 번도 안 했을 때. 6번 참고. - **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. 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. `npm run dev` 가 `Cannot find package 'express'` 로 실패해요** → 처음 1회 `npm install` 을 안 한 경우입니다. 프로젝트 폴더에서 `npm install` 후 다시 실행하세요(7번).
- **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다. - **Q. DB가 비어있어요** → 정상입니다. 본인 전용 빈 스키마가 제공됩니다. 테이블은 직접 만들면 됩니다.
- **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다. - **Q. K8s(쿠버네티스)는 어떻게 봐요?** → 직원은 K8s에 직접 접근하지 않습니다. DB/스토리지/배포는 위 도구들로 충분합니다.