웹 설치 절차
바이너리 배포, Docker Compose 배포, Kubernetes 배포로 Sayrud를 시작한 뒤 http://server-address:2830/setup에 접속합니다. 설치 전에는 홈페이지에서도 이 페이지로 이동합니다.
설치는 본인 확인, 데이터베이스, 관리자, 완료의 네 단계로 구성됩니다. 페이지 오른쪽 위에서 언어를 바꿀 수 있습니다.
본인 확인
설치 토큰을 지정하지 않으면 시작 로그에 Setup token:과 토큰이 포함된 설치 링크가 표시됩니다. 토큰을 페이지에 입력하고 ‘확인’을 누르세요. 원격 배포에서는 로그 링크의 localhost를 실제 접속 주소로 바꿔야 합니다.
| 배포 방식 | 로그 확인 위치 |
|---|---|
| 포그라운드 실행 | 현재 터미널 |
| systemd | sudo journalctl -u sayrud -n 100 --no-pager |
| Docker Compose | docker compose logs --tail=100 sayrud |
| Kubernetes | kubectl -n sayrud logs deployment/sayrud --tail=100 |
SAYRUD_SETUP_TOKEN을 설정했다면 해당 환경 변수의 값을 입력합니다. K8s 배포는 이 방식을 사용하며 토큰은 Secret을 만들 때 사용한 로컬 파일에 저장되어 있습니다.
사용자 지정 토큰은 공백과 하이픈을 제외하고 최소 16자여야 합니다. openssl rand -hex 24로 생성할 수 있습니다. 토큰 검증 시 대소문자, 공백, 하이픈은 구분하지 않습니다.
고정 토큰을 설정하지 않았다면 설치 도중 프로세스를 재시작할 때 새 토큰이 생성됩니다. 최신 로그에서 다시 확인하세요. 토큰과 토큰이 담긴 링크는 설치 담당자에게만 공유하세요. 관리자를 만들면 설치 API는 닫힙니다.
데이터베이스 설정
새로 설치할 때는 다음 정보를 입력합니다.
| 서비스 | 입력 항목 |
|---|---|
| PostgreSQL | 호스트, 포트, 데이터베이스 이름, 사용자 이름, 비밀번호, SSL 모드 |
| Redis | 호스트:포트 형식의 주소와 선택 사항인 사용자 이름 및 비밀번호 |
연결은 브라우저를 실행하는 컴퓨터가 아니라 Sayrud 프로세스에서 이루어집니다. Docker Compose 설정에서는 postgres와 redis:6379를 사용하며 K8s에서는 클러스터 내부 Service 이름이나 접근 가능한 외부 도메인을 사용합니다.
PostgreSQL SSL 모드에는 ‘암호화 안 함’, ‘암호화’, ‘암호화 및 CA 검증’, ‘암호화 및 CA·호스트 이름 검증’이 있습니다. 데이터베이스 서비스 요구 사항에 맞춰 선택하세요. 인증서를 검증하려면 실행 환경에서도 해당 CA를 신뢰해야 합니다.
‘연결 테스트’를 눌러 PostgreSQL과 Redis가 모두 연결되는지 확인한 다음 ‘저장 후 계속’을 누릅니다.
관리자 만들기
이메일, 사용자 이름, 비밀번호, 비밀번호 확인을 입력하고 ‘설치 완료’를 누릅니다.
첫 번째 시스템 관리자가 생성되며 자동으로 로그인됩니다. ‘시작하기’를 누르면 애플리케이션으로 이동합니다.
설치 후 프로젝트 생성, 레코드 편집, 첨부 파일 업로드가 가능한지 확인하고 배포 방식에 따라 설정과 업로드 파일이 영구 저장되는지 확인하세요. 사이트 설정, 가입 허용 여부, 로그인 방식, AI 모델 등은 관리자 화면에서 변경할 수 있습니다.
설정 파일 미리 제공
설정 관리 시스템에서 연결 정보를 제공한다면 sayrud.yaml을 미리 준비할 수 있습니다. 다음은 로컬 스토리지 설정입니다. 연결 비밀번호와 auth.secret_key를 먼저 바꾸세요.
postgres:
dsn: "postgres://sayrud:[email protected]:5432/sayrud?sslmode=disable"
redis:
address: "127.0.0.1:6379"
username: ""
password: ""
auth:
secret_key: "REPLACE_WITH_BASE64_KEY"
storage:
type: local
local:
path: ./data/storage다음 명령으로 auth.secret_key를 생성하고 전체 출력값을 설정에 입력합니다.
openssl rand -base64 32PostgreSQL URL을 직접 작성할 때는 비밀번호의 @, :, / 같은 특수 문자를 URL 인코딩해야 합니다. 설치 마법사에 입력하면 프로그램이 인코딩을 처리합니다.
시작 인수에 지정한 경로에 파일을 놓습니다. 전체 옵션은 설정 예제를 참고하세요. 설정을 변경하면 프로그램을 재시작해야 합니다.
문제 해결
설치 페이지가 나타나지 않음
로그에 정상 시작이 표시되고 데이터베이스에 이미 사용자가 있다면 애플리케이션 페이지가 바로 열립니다. 기존 계정으로 로그인하세요.
설치 토큰이 유효하지 않음
설치 도중 프로세스가 재시작되었는지 확인하세요. SAYRUD_SETUP_TOKEN을 설정하지 않았다면 최신 로그의 토큰을 사용하세요. K8s에서는 Pod가 의도한 Secret을 사용하는지 확인하고 최초 설치 중에는 복제본을 하나로 유지하세요. 토큰을 연속으로 잘못 입력하면 요청 제한이 적용되므로 토큰을 확인한 뒤 다시 시도하세요.
데이터베이스 연결 테스트 실패
데이터베이스가 만들어졌는지, 계정 정보가 맞는지, 애플리케이션 호스트 또는 Pod에서 대상 주소로 접근할 수 있는지 확인하세요. 컨테이너의 127.0.0.1은 해당 컨테이너 자체를 가리킵니다. 연결은 성공하지만 저장이 실패한다면 스키마 마이그레이션 권한도 확인하세요.
새 설치 마법사는 이미 사용자가 있는 데이터베이스를 인계받지 않습니다. 기존 인스턴스를 복원할 때는 원래 설정, 키, 업로드 파일을 복원하고 정상 시작 절차로 원래 데이터베이스에 연결하세요. 데이터베이스 설정 단계를 다시 진행하지 마세요.
설정 저장 중 권한 오류 발생
설치 마법사는 설정 디렉터리에 임시 파일을 쓴 뒤 sayrud.yaml로 확정하므로 디렉터리 자체에 쓰기 권한이 있어야 합니다. 읽기 전용 마운트, ConfigMap, Secret 또는 UID/GID와 볼륨 소유자의 불일치를 확인하세요. Docker와 K8s 이미지는 10001:10001을 사용합니다.
설정은 저장됐지만 재시작이 필요함
서비스 로그에서 이후 서비스 초기화가 실패한 원인을 해결하고 같은 설정 경로로 재시작하세요. 저장된 설정을 다시 읽으므로 파일을 삭제하고 재설치할 필요가 없습니다.
컨테이너 재생성 후 설치 페이지가 다시 나타남
설정 디렉터리가 /home/app/config에 마운트되었는지, 원래 PostgreSQL 데이터베이스를 사용하는지, Compose 프로젝트 이름이나 K8s PVC가 바뀌었는지 확인하세요. 새 설치를 진행하기 전에 기존 설정과 데이터를 먼저 복구하세요.