sori.studio/deadman-switch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
aeaa1b37c20c2096fe2007741862d8563b08f7c5
deadman-switch/docs/DEPLOY.md
zenn aeaa1b37c2 feat: rename app to Last Signal 
Rename service, UI, storage, and target-path configuration; clarify expiration cleanup behavior.
2026-09-30 11:55:58 +09:00

8.8 KiB
Raw Blame History

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 설치 확인

터미널을 열고 아래를 입력합니다.

git --version

버전이 나오면 설치되어 있는 것입니다.

4-2. 프로젝트 받기

원하는 폴더로 이동한 뒤 아래를 실행합니다.

cd ~/Desktop
git clone https://git.sori.studio/zenn/collection.sori.studio.git
cd collection.sori.studio

4-3. 패키지 설치

npm install

4-4. 실행

npm start

브라우저에서 접속:

http://localhost:40100

아래 명령으로 버전 정보가 나오면 정상입니다.

curl http://localhost:40100/api/version

4-5. 개발 중 자동 재시작

npm run dev

5. 상용 서버 설치 (NAS + Docker)

NAS에서는 보통 SSH로 접속해서 명령어를 실행합니다.

5-1. NAS에 접속

예시:

ssh zenn@NAS_IP

NAS_IP는 NAS의 실제 IP 주소로 바꿉니다.

5-2. 설치 폴더 만들기

mkdir -p /home/zenn/docker
cd /home/zenn/docker

5-3. Git으로 프로젝트 받기

git clone https://git.sori.studio/zenn/collection.sori.studio.git
cd collection.sori.studio

5-4. 삭제 대상 폴더 확인

기본 삭제 경로:

/home/zenn/Collection

이 폴더가 실제로 존재하는지 확인합니다.

ls -ld /home/zenn/Collection

5-5. 삭제 스크립트 확인

cat scripts/cleanup.sh
chmod +x scripts/*.sh

5-6. 설정 확인

기본 설정 파일:

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 파일에 넣습니다.

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 실행

docker compose up -d --build

5-8. 실행 확인

docker compose ps
docker compose logs -f last-signal

브라우저 접속:

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. 업데이트 방법

이미 설치한 서버에서 새 버전을 받을 때:

cd /home/zenn/docker/collection.sori.studio
git pull
docker compose down --remove-orphans
docker compose up -d --build

새 데이터 볼륨 이름은 last-signal-data입니다. 기존 keeper-data 볼륨은 새 설정에서 사용하지 않습니다.

개발 서버:

cd collection.sori.studio
git pull
npm install
npm start

8. 테스트 방법

8-1. 짧은 타이머 테스트

10초 후 만료를 보고 싶다면:

THRESHOLD_SECONDS=10 npm start

Docker:

THRESHOLD_SECONDS: 10

8-2. 초기화

curl -X POST http://localhost:40100/api/reset

토큰을 켠 경우:

curl -X POST http://localhost:40100/api/reset \
  -H 'Content-Type: application/json' \
  -d '{"token":"내-토큰"}'

주의:

  • 삭제 테스트 전에는 반드시 백업하세요.
  • cleanup.sh는 실제로 /home/zenn/Collection을 삭제합니다.

9. 자주 쓰는 명령어

Docker

docker compose up -d --build
docker compose ps
docker compose logs -f
docker compose restart
docker compose down

Git

git clone https://git.sori.studio/zenn/collection.sori.studio.git
git pull
git status

10. 문제 해결

포트가 이미 사용 중

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로 확인합니다.

curl http://localhost:40100/api/version

11. 폴더를 통째로 옮겨도 되나?

가능은 하지만 권장하지 않습니다.

권장 방식:

git clone https://git.sori.studio/zenn/collection.sori.studio.git

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

Reference in New Issue View Git Blame Copy Permalink