# 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
```

이 방식이 업데이트와 버전 관리에 훨씬 유리합니다.