zenn
aeaa1b37c2
Rename service, UI, storage, and target-path configuration; clarify expiration cleanup behavior.
401 lines
8.8 KiB
Markdown
401 lines
8.8 KiB
Markdown
# Last Signal 설치 가이드
|
|
|
|
이 문서는 컴퓨터를 잘 모르는 분도 따라할 수 있도록 작성했습니다.
|
|
|
|
프로젝트 폴더를 USB로 통째로 옮기지 않아도 됩니다.
|
|
**Git 저장소에서 받아서 설치**하는 방식을 권장합니다.
|
|
|
|
- 저장소 주소: `https://git.sori.studio/zenn/collection.sori.studio.git`
|
|
- 현재 버전: `v1.0.0`
|
|
|
|
---
|
|
|
|
## 1. 이 프로그램이 하는 일
|
|
|
|
Last Signal은 웹페이지에 들어와서 가끔 생존 확인 버튼을 눌러주는 서비스입니다.
|
|
|
|
- 클릭하면 "아직 살아있음" 기록이 남습니다.
|
|
- 일정 기간 동안 아무도 클릭하지 않으면, 미리 준비한 스크립트가 실행됩니다.
|
|
- 확인이 설정된 기간 동안 없으면 지정된 스크립트를 실행합니다.
|
|
- 기본 스크립트는 `/home/zenn/Collection` 폴더 **안의 내용 전체를 삭제**합니다. 폴더 자체는 남습니다.
|
|
|
|
중요:
|
|
|
|
- 웹앱이 직접 폴더를 지우지 않습니다.
|
|
- 웹앱이 직접 파일을 지우지는 않습니다. 기본 `scripts/cleanup.sh`가 `TARGET_PATH`의 내용을 삭제합니다.
|
|
- `docker-compose.yml`에서 호스트 폴더를 컨테이너에 마운트하고, `TARGET_PATH`에는 컨테이너 쪽 경로를 지정합니다.
|
|
|
|
---
|
|
|
|
## 2. 준비물
|
|
|
|
### 개발 서버(맥/PC에서 먼저 테스트)
|
|
|
|
- Node.js 20 이상
|
|
- npm
|
|
- Git
|
|
|
|
### 상용 서버(NAS)
|
|
|
|
- Docker
|
|
- Docker Compose
|
|
- Git
|
|
- NAS에 `/home/zenn/Collection` 폴더
|
|
|
|
NAS 본체에는 Node.js나 npm이 없어도 됩니다. Docker 이미지 빌드 과정에서 컨테이너 안에서 필요한 패키지를 설치합니다.
|
|
|
|
---
|
|
|
|
## 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` | 클릭 인정 최소 간격 |
|
|
| `target_path` | `/home/zenn/Collection` | 만료 시 스크립트가 처리할 대상 폴더 |
|
|
| `trigger_script` | `./scripts/cleanup.sh` | 실행할 스크립트 |
|
|
| `port` | `40100` | 웹 접속 포트 |
|
|
|
|
Docker에서는 `docker-compose.yml`도 함께 확인합니다.
|
|
|
|
초기화 API 보호 토큰은 Git에 올리지 않는 `.env` 파일에 넣습니다.
|
|
|
|
```bash
|
|
cat > .env <<'EOF'
|
|
RESET_TOKEN=여기에-긴-비밀-토큰
|
|
PUBLIC_BASE_URL=https://collection.sori.studio
|
|
MAIL_ENABLED=true
|
|
MAIL_SMTP_USER=zenn.message@gmail.com
|
|
MAIL_SMTP_PASS=구글-앱-비밀번호
|
|
MAIL_TO=zenn.message@gmail.com
|
|
MAIL_CONFIRM_TOKEN=긴-랜덤-확인-토큰
|
|
EOF
|
|
```
|
|
|
|
`.env` 파일이 없거나 `RESET_TOKEN`이 없으면 Docker Compose 실행 시 오류가 납니다.
|
|
|
|
메일 알림을 켜면 마지막 확인 이후 60일, 75일, 89일에 Gmail로 안내 메일이 한 번씩 발송됩니다. 메일 버튼은 `/confirm?token=...` 링크로 바로 생존 확인을 갱신합니다.
|
|
|
|
### 5-7. Docker 실행
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
### 5-8. 실행 확인
|
|
|
|
```bash
|
|
docker compose ps
|
|
docker compose logs -f last-signal
|
|
```
|
|
|
|
브라우저 접속:
|
|
|
|
```text
|
|
http://NAS_IP:44092
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 설정 항목 전체
|
|
|
|
### 6-1. `config/default.json`
|
|
|
|
| 항목 | 기본값 | 설명 |
|
|
| --- | --- | --- |
|
|
| `threshold_days` | `90` | 생존 확인 허용 일수 |
|
|
| `threshold_seconds` | `null` | 테스트용 초 단위 타이머. 값이 있으면 일수보다 우선 |
|
|
| `cooldown_seconds` | `1` | 클릭 인정 쿨다운 |
|
|
| `check_interval_seconds` | `60` | 스크립트 검사 주기 |
|
|
| `database_path` | `./data/last-signal.sqlite` | SQLite 경로 |
|
|
| `trigger_script` | `./scripts/cleanup.sh` | 만료 시 실행 스크립트 |
|
|
| `background` | `random` | 배경 이미지 설정 |
|
|
| `target_path` | `/home/zenn/Collection` | 만료 시 스크립트가 처리할 대상 폴더 |
|
|
| `port` | `40100` | 웹 포트 |
|
|
| `recent_traces_limit` | `5` | 최근 흔적 개수 |
|
|
| `reset_token` | `""` | 초기화 API 보호 토큰 |
|
|
| `public_base_url` | `https://collection.sori.studio` | 메일 확인 링크 공개 URL |
|
|
| `mail_enabled` | `false` | Gmail 알림 메일 사용 여부 |
|
|
| `mail_smtp_user` | `""` | Gmail SMTP 계정 |
|
|
| `mail_smtp_pass` | `""` | Gmail 앱 비밀번호 |
|
|
| `mail_to` | `zenn.message@gmail.com` | 알림 수신 주소 |
|
|
| `mail_confirm_token` | `""` | 메일 확인 링크 보호 토큰 |
|
|
|
|
### 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`
|
|
- `TARGET_PATH`
|
|
- `BACKGROUND`
|
|
- `RESET_TOKEN`
|
|
- `TZ`
|
|
- `PUBLIC_BASE_URL`
|
|
- `MAIL_ENABLED`
|
|
- `MAIL_SMTP_USER`
|
|
- `MAIL_SMTP_PASS`
|
|
- `MAIL_TO`
|
|
- `MAIL_CONFIRM_TOKEN`
|
|
|
|
---
|
|
|
|
## 7. 업데이트 방법
|
|
|
|
이미 설치한 서버에서 새 버전을 받을 때:
|
|
|
|
```bash
|
|
cd /home/zenn/docker/collection.sori.studio
|
|
git pull
|
|
docker compose down --remove-orphans
|
|
docker compose up -d --build
|
|
```
|
|
|
|
새 데이터 볼륨 이름은 `last-signal-data`입니다. 기존 `keeper-data` 볼륨은 새 설정에서 사용하지 않습니다.
|
|
|
|
개발 서버:
|
|
|
|
```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
|
|
```
|
|
|
|
이 방식이 업데이트와 버전 관리에 훨씬 유리합니다.
|