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 에서 한 줄)

```bash
# 도메인을 아직 모를 때 — 서버 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 를 허용한다.
운영 중인 서버는 사용자가 있으므로 기본 관리자가 만들어지지 않고, 점검표도 보통 완료 상태라 포워딩이 생기지 않는다(관리자 콘솔 › 시스템 설정 탭에서 점검표를 볼 수 있다).