초기 버전 v1.0.0 구현
개인 NAS용 생존 확인 웹앱의 기본 기능, Docker 배포 설정, 설치 문서를 추가합니다.
This commit is contained in:
363
docs/DEPLOY.md
Normal file
363
docs/DEPLOY.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# Collection Keeper 설치 가이드
|
||||
|
||||
이 문서는 컴퓨터를 잘 모르는 분도 따라할 수 있도록 작성했습니다.
|
||||
|
||||
프로젝트 폴더를 USB로 통째로 옮기지 않아도 됩니다.
|
||||
**Git 저장소에서 받아서 설치**하는 방식을 권장합니다.
|
||||
|
||||
- 저장소 주소: `https://git.sori.studio/zenn/collection.sori.studio.git`
|
||||
- 현재 버전: `v1.0.0`
|
||||
|
||||
---
|
||||
|
||||
## 1. 이 프로그램이 하는 일
|
||||
|
||||
Collection Keeper는 웹페이지에 들어와서 가끔 클릭해 주는 작은 서비스입니다.
|
||||
|
||||
- 클릭하면 "아직 살아있음" 기록이 남습니다.
|
||||
- 일정 기간 동안 아무도 클릭하지 않으면, 미리 준비한 스크립트가 실행됩니다.
|
||||
- NAS에서는 `/home/zenn/Collection` 폴더를 삭제하도록 설정되어 있습니다.
|
||||
|
||||
중요:
|
||||
|
||||
- 웹앱이 직접 폴더를 지우지 않습니다.
|
||||
- 실제 삭제는 `scripts/cleanup.sh`가 담당합니다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 준비물
|
||||
|
||||
### 개발 서버(맥/PC에서 먼저 테스트)
|
||||
|
||||
- Node.js 20 이상
|
||||
- npm
|
||||
- Git
|
||||
|
||||
### 상용 서버(NAS)
|
||||
|
||||
- Docker
|
||||
- Docker Compose
|
||||
- Git
|
||||
- NAS에 `/home/zenn/Collection` 폴더
|
||||
|
||||
---
|
||||
|
||||
## 3. Git이란?
|
||||
|
||||
Git은 프로그램 소스를 인터넷 저장소에 올려두고, 서버에서 내려받는 도구입니다.
|
||||
|
||||
폴더를 직접 복사하는 것보다 좋은 점:
|
||||
|
||||
- 나중에 업데이트가 쉽습니다.
|
||||
- 어떤 버전을 썼는지 관리할 수 있습니다.
|
||||
- 여러 서버에 같은 방식으로 설치할 수 있습니다.
|
||||
|
||||
---
|
||||
|
||||
## 4. 개발 서버 설치 (맥/PC)
|
||||
|
||||
### 4-1. Git 설치 확인
|
||||
|
||||
터미널을 열고 아래를 입력합니다.
|
||||
|
||||
```bash
|
||||
git --version
|
||||
```
|
||||
|
||||
버전이 나오면 설치되어 있는 것입니다.
|
||||
|
||||
### 4-2. 프로젝트 받기
|
||||
|
||||
원하는 폴더로 이동한 뒤 아래를 실행합니다.
|
||||
|
||||
```bash
|
||||
cd ~/Desktop
|
||||
git clone https://git.sori.studio/zenn/collection.sori.studio.git
|
||||
cd collection.sori.studio
|
||||
```
|
||||
|
||||
### 4-3. 패키지 설치
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 4-4. 실행
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
브라우저에서 접속:
|
||||
|
||||
```text
|
||||
http://localhost:40100
|
||||
```
|
||||
|
||||
아래 명령으로 버전 정보가 나오면 정상입니다.
|
||||
|
||||
```bash
|
||||
curl http://localhost:40100/api/version
|
||||
```
|
||||
|
||||
### 4-5. 개발 중 자동 재시작
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 상용 서버 설치 (NAS + Docker)
|
||||
|
||||
NAS에서는 보통 SSH로 접속해서 명령어를 실행합니다.
|
||||
|
||||
### 5-1. NAS에 접속
|
||||
|
||||
예시:
|
||||
|
||||
```bash
|
||||
ssh zenn@NAS_IP
|
||||
```
|
||||
|
||||
`NAS_IP`는 NAS의 실제 IP 주소로 바꿉니다.
|
||||
|
||||
### 5-2. 설치 폴더 만들기
|
||||
|
||||
```bash
|
||||
mkdir -p /home/zenn/docker
|
||||
cd /home/zenn/docker
|
||||
```
|
||||
|
||||
### 5-3. Git으로 프로젝트 받기
|
||||
|
||||
```bash
|
||||
git clone https://git.sori.studio/zenn/collection.sori.studio.git
|
||||
cd collection.sori.studio
|
||||
```
|
||||
|
||||
### 5-4. 삭제 대상 폴더 확인
|
||||
|
||||
기본 삭제 경로:
|
||||
|
||||
```text
|
||||
/home/zenn/Collection
|
||||
```
|
||||
|
||||
이 폴더가 실제로 존재하는지 확인합니다.
|
||||
|
||||
```bash
|
||||
ls -ld /home/zenn/Collection
|
||||
```
|
||||
|
||||
### 5-5. 삭제 스크립트 확인
|
||||
|
||||
```bash
|
||||
cat scripts/cleanup.sh
|
||||
chmod +x scripts/*.sh
|
||||
```
|
||||
|
||||
### 5-6. 설정 확인
|
||||
|
||||
기본 설정 파일:
|
||||
|
||||
```text
|
||||
config/default.json
|
||||
```
|
||||
|
||||
자주 바꾸는 값:
|
||||
|
||||
| 설정 | 기본값 | 설명 |
|
||||
| --- | --- | --- |
|
||||
| `threshold_days` | `90` | 며칠 동안 클릭이 없으면 스크립트 실행 |
|
||||
| `cooldown_seconds` | `1` | 클릭 인정 최소 간격 |
|
||||
| `collection_path` | `/home/zenn/Collection` | 삭제 대상 폴더 |
|
||||
| `trigger_script` | `./scripts/cleanup.sh` | 실행할 스크립트 |
|
||||
| `port` | `40100` | 웹 접속 포트 |
|
||||
|
||||
Docker에서는 `docker-compose.yml`도 함께 확인합니다.
|
||||
|
||||
### 5-7. Docker 실행
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### 5-8. 실행 확인
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs -f collection-keeper
|
||||
```
|
||||
|
||||
브라우저 접속:
|
||||
|
||||
```text
|
||||
http://NAS_IP:40100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 설정 항목 전체
|
||||
|
||||
### 6-1. `config/default.json`
|
||||
|
||||
| 항목 | 기본값 | 설명 |
|
||||
| --- | --- | --- |
|
||||
| `threshold_days` | `90` | 생존 확인 허용 일수 |
|
||||
| `threshold_seconds` | `null` | 테스트용 초 단위 타이머. 값이 있으면 일수보다 우선 |
|
||||
| `cooldown_seconds` | `1` | 클릭 인정 쿨다운 |
|
||||
| `check_interval_seconds` | `60` | 스크립트 검사 주기 |
|
||||
| `database_path` | `./data/keeper.sqlite` | SQLite 경로 |
|
||||
| `trigger_script` | `./scripts/cleanup.sh` | 만료 시 실행 스크립트 |
|
||||
| `background` | `random` | 배경 이미지 설정 |
|
||||
| `collection_path` | `/home/zenn/Collection` | Collection 폴더 |
|
||||
| `port` | `40100` | 웹 포트 |
|
||||
| `recent_traces_limit` | `5` | 최근 흔적 개수 |
|
||||
| `reset_token` | `""` | 초기화 API 보호 토큰 |
|
||||
|
||||
### 6-2. 화면 문구 (`public/custom.js`)
|
||||
|
||||
| 항목 | 설명 |
|
||||
| --- | --- |
|
||||
| `keeperTextLines` | 오른쪽 아래 안내 문구 |
|
||||
| `farewellTextLines` | 만료 후 중앙 작별 문구 |
|
||||
| `emojis` | 클릭 이모지 목록 |
|
||||
| `clickMessages` | 클릭 시 나오는 문장 목록 |
|
||||
|
||||
코드를 몰라도 이 파일의 따옴표 안 문장만 바꾸면 됩니다.
|
||||
|
||||
### 6-3. Docker 환경 변수
|
||||
|
||||
`docker-compose.yml`에서 바꿀 수 있습니다.
|
||||
|
||||
- `THRESHOLD_DAYS`
|
||||
- `THRESHOLD_SECONDS`
|
||||
- `COOLDOWN_SECONDS`
|
||||
- `CHECK_INTERVAL_SECONDS`
|
||||
- `PORT`
|
||||
- `DATABASE_PATH`
|
||||
- `TRIGGER_SCRIPT`
|
||||
- `COLLECTION_PATH`
|
||||
- `BACKGROUND`
|
||||
- `RESET_TOKEN`
|
||||
|
||||
---
|
||||
|
||||
## 7. 업데이트 방법
|
||||
|
||||
이미 설치한 서버에서 새 버전을 받을 때:
|
||||
|
||||
```bash
|
||||
cd /home/zenn/docker/collection.sori.studio
|
||||
git pull
|
||||
docker compose down
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
개발 서버:
|
||||
|
||||
```bash
|
||||
cd collection.sori.studio
|
||||
git pull
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 테스트 방법
|
||||
|
||||
### 8-1. 짧은 타이머 테스트
|
||||
|
||||
10초 후 만료를 보고 싶다면:
|
||||
|
||||
```bash
|
||||
THRESHOLD_SECONDS=10 npm start
|
||||
```
|
||||
|
||||
Docker:
|
||||
|
||||
```yaml
|
||||
THRESHOLD_SECONDS: 10
|
||||
```
|
||||
|
||||
### 8-2. 초기화
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:40100/api/reset
|
||||
```
|
||||
|
||||
토큰을 켠 경우:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:40100/api/reset \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"token":"내-토큰"}'
|
||||
```
|
||||
|
||||
주의:
|
||||
|
||||
- 삭제 테스트 전에는 반드시 백업하세요.
|
||||
- `cleanup.sh`는 실제로 `/home/zenn/Collection`을 삭제합니다.
|
||||
|
||||
---
|
||||
|
||||
## 9. 자주 쓰는 명령어
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
docker compose ps
|
||||
docker compose logs -f
|
||||
docker compose restart
|
||||
docker compose down
|
||||
```
|
||||
|
||||
### Git
|
||||
|
||||
```bash
|
||||
git clone https://git.sori.studio/zenn/collection.sori.studio.git
|
||||
git pull
|
||||
git status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 문제 해결
|
||||
|
||||
### 포트가 이미 사용 중
|
||||
|
||||
```bash
|
||||
lsof -nP -iTCP:40100 -sTCP:LISTEN
|
||||
```
|
||||
|
||||
### 화면은 뜨는데 삭제가 안 됨
|
||||
|
||||
1. `threshold_days` 또는 `threshold_seconds` 확인
|
||||
2. `docker compose logs -f`에서 `[keeper] Threshold exceeded` 확인
|
||||
3. `scripts/cleanup.sh` 실행 권한 확인
|
||||
4. `/home/zenn/Collection` 볼륨 마운트 확인
|
||||
|
||||
### 버전 확인
|
||||
|
||||
API로 확인합니다.
|
||||
|
||||
```bash
|
||||
curl http://localhost:40100/api/version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 폴더를 통째로 옮겨도 되나?
|
||||
|
||||
가능은 하지만 권장하지 않습니다.
|
||||
|
||||
권장 방식:
|
||||
|
||||
```bash
|
||||
git clone https://git.sori.studio/zenn/collection.sori.studio.git
|
||||
```
|
||||
|
||||
이 방식이 업데이트와 버전 관리에 훨씬 유리합니다.
|
||||
Reference in New Issue
Block a user