AriWeb-Suite/modules/webmaker/docs/FIRST-INSTALL.md

처음 설치하기 — 설치는 짧게, 설정은 웹에서 (v1.5.11)

AI Webmaker v1.5.11 · 2026-10-14 · 대상: 설치 담당자·운영자

1.5.11 부터 새 서버 설치는 "스크립트 한 번 → 웹에서 나머지" 로 끝난다. 설치 중에 사람이 넣을 값은 없다(FQDN 조차 몰라도 된다). 설치가 끝나면 http://<서버 IP>:8795/?token=… 가 기본 접속 위치이고, 서비스 첫 화면(http://<서버 IP>/, https://<도메인>/)도 설치 점검표가 끝나기 전에는 같은 설정 페이지(/setup)로 넘어간다.

1. 설치 (이 PC 에서 한 줄)

# 도메인을 아직 모를 때 — 서버 IP 로 설치 (처음 설치 모드: DB 를 복사하지 않음. v1.6.31: 관리자 admin 은 1회용 무작위 비밀번호로 만들어 설치 출력에 한 번 보인다)
deploy/remote-install.sh <ssh-host>

# 도메인이 정해져 있을 때 (처음 설치 모드로 하려면 FRESH=1)
FRESH=1 deploy/remote-install.sh <ssh-host> webmaker.example.com

• 전제: <ssh-host> 에 비밀번호 없는 SSH 와 sudo -n 이 된다(Ubuntu 22.04/24.04). node 22, claude/codex CLI, nginx 사이트 블록, systemd 유닛 webmaker·webmaker-setup, sudoers 규칙, Gitea 컨테이너(docker 가 있으면)를 스크립트가 설치한다.
• FQDN 을 생략하면 서버의 대표 IP(공인 IP 가 있으면 그것)로 공개 주소 http://<IP> 와 nginx server_name <IP> 를 만든다. 나중에 도메인이 정해지면 설정 페이지에서 공개 주소를 바꾸고 nginx 의 server_name 을 고친 뒤 certbot --nginx -d <도메인> 을 실행한다.
• 끝나면 이렇게 알려 준다:

== 완료. 설치 중 더 입력할 것은 없습니다 — 나머지는 웹에서 이어집니다:
  0) 초기 설정 페이지(설치 점검표: 관리자 비밀번호 · AI 엔진 인증 · 공개 주소 → 연동 정보)에서 설정하고 서비스를 재시작:
       http://203.0.113.10:8795/?token=xxxxxxxx
     서비스 첫 화면 http://203.0.113.10/ 도 점검표가 끝나기 전에는 같은 설정 페이지(/setup)로 넘어갑니다. 최초 관리자는 설정 페이지에서 만든다(고정 비밀번호 없음)

2. 웹에서 끝내기 — 설치 점검표

설정 페이지(별도 포트 8795 또는 서비스의 /setup)는 접속 토큰(설치 스크립트가 알려 준 주소에 포함, 서버의 data/setup.token) 또는 관리자 계정으로 들어간다. 맨 위 설치 점검표 카드에 필수 세 항목과 해결 방법이 보인다. 셋이 모두 "완료" 가 되면 서비스 첫 화면은 더 이상 설정 페이지로 넘어오지 않는다.

항목	완료 조건	하는 법
관리자 계정	비밀번호를 정한(변경 강제가 아닌) 관리자가 있다	설정 페이지 "관리자 계정" 카드에서 최초 관리자를 만들거나, 설치 출력의 1회용 비밀번호로 로그인해 비밀번호를 바꾼다
AI 엔진 인증	Claude Code(서버 로그인·OAuth 토큰·API 키 중 하나) 또는 OpenAI(API 키·codex 로그인)가 쓸 수 있다	"AI 엔진 인증" 카드. 서버 로그인은 서비스 실행 계정으로 서버에서 claude 를 한 번 실행해 브라우저 로그인; 서버에 들어가기 어려우면 다른 PC 에서 claude setup-token 으로 만든 OAuth 토큰이나 API 키를 넣는다
서비스 공개 주소	설치값(http://192.168.20.66)이 아닌 이 서버의 주소	설치 스크립트가 넣어 둔다. 도메인이 생기면 "서비스" 묶음에서 https://<도메인> 으로 바꾸고 서비스 재시작

참고 항목(운영은 되지만 안내): 메일 발송 키(Resend), 소스 보관(Gitea) 원격, 메일 서버(Arimail). 각 항목의 설치 명령은 같은 화면 아래 "연동 서비스 설치·등록 명령" 에 있다.

3. 최초 관리자 (v1.6.31)

• 고정 비밀번호 admin / admin 은 더 이상 만들지 않는다. 처음 설치(FRESH)는 node scripts/admin.js bootstrap 이 관리자 admin 을 1회용 무작위 비밀번호로 만들어 설치 출력에 한 번 보인다(첫 로그인 뒤 변경 강제). 다른 절차로 설치해 사용자가 없는 서버는 설정 페이지(접속 토큰) › 관리자 계정 › "새 관리자 만들기" 로 아이디·비밀번호를 정한다.
• 접속 토큰은 최초 설정 전용이다. 비밀번호를 바꾼 관리자가 생기면(설치 점검표 완료) 토큰 로그인은 403 으로 거절되고 관리자 로그인만 받는다 — 누군가 나중에 토큰 주소를 알아내도 쓸 수 없다. 토큰 로그인·관리자 로그인은 IP 당 15분 20회, 계정당 15분 10회 실패로 제한된다.
• IP·포트(8795)로 시작하는 설정은 그대로 가능하지만, 공인망 서버는 설치 직후 바로 최초 관리자를 만들어 점검표를 끝내는 것이 안전하다(끝나면 토큰이 무효).

4. 포트·방화벽·포워딩

• 설정 페이지 포트: 설정 service.setupPort(기본 8795), 바인드 service.setupBind(기본 0.0.0.0; 사설망만 열려면 lan). 포트가 겹치면 webmaker-setup 이 8796, 8797 … 을 차례로 잡고 설정 파일에 기록한다. 접속 주소는 언제든 node scripts/config.js setup-url.
• 방화벽(ufw)이 켜져 있으면 설치·갱신 스크립트가 그 포트를 허용한다. 접속은 토큰·관리자 로그인·시도 제한(IP 당 15분 10회)으로 보호되지만 관리 화면이므로, 점검이 끝난 뒤에는 sudo ufw delete allow 8795/tcp 로 닫거나 바인드를 lan 으로 바꿔도 된다(서비스 안 /setup 과 관리자 콘솔 탭은 그대로 쓸 수 있다).
• 첫 화면 포워딩: 점검표 미완 동안 /·/login → /setup. 끄려면 service.setupRedirect=off(node scripts/config.js set service.setupRedirect off), 점검 전에 로그인 화면을 열려면 /login?direct=1.
• 회원가입: service.allowSignup(기본 켬). 끄면 로그인 화면의 회원가입 탭이 사라지고 API 는 403 + "회원가입이 닫혀 있습니다". 웹서버(nginx) 규칙으로 /api/auth/signup 을 막으면 이유 없는 403 이 되므로 이 설정을 쓴다.

5. 이미 설치된 서버에 1.5.11 올리기

deploy/remote-update.sh <ssh-host> [app-dir] [service] — 코드 갱신과 함께: 설정 페이지 유닛에 본 서비스의 DATA_ROOT 를 맞추고, 포트를 8795 로(설정 파일에 service.setupPort 가 없으면 기본값이 바뀌므로 자동), ufw 의 3081 규칙을 지우고 8795 를 허용한다. 운영 중인 서버는 사용자가 있으므로 기본 관리자가 만들어지지 않고, 점검표도 보통 완료 상태라 포워딩이 생기지 않는다(관리자 콘솔 › 시스템 설정 탭에서 점검표를 볼 수 있다).