서버 마련·설치

📦세파스 설치 방법

본당 소유의 서버에 세파스를 처음 설치하는 절차입니다. 초보자도 단계를 따라 설치할 수 있도록 구성되었습니다.

마지막 업데이트 2026-07-18

0 · 준비물 점검

VPS 한 대 (Ubuntu 22.04 권장, 최소 메모리 2GB)
서버 접속 정보 (IP 주소, 비밀번호 또는 SSH 키)
SSH 접속 도구
도메인 (선택사항, 8절에서 필요)

설치 방법 고르기

방법 A(Docker)는 가장 단순합니다. 운영 서버에 직접 설치할 때는 방법 B를 자동으로 수행해 주는 자동 설치 스크립트(2절 아래 안내)를 권장하며, 방법 B를 손으로 따라가는 것은 hot-reload 개발 환경이 필요할 때만 하세요.

1 · 서버 기본 준비

시스템을 최신으로 업데이트하고 기본 도구를 설치합니다.

sudo apt update
sudo apt -y upgrade
sudo apt -y install git curl ca-certificates

2 · 소스 내려받기

접근 권한 필수

세파스 코드는 도입한 본당에만 접근 권한이 열립니다.

발급받은 저장소에서 최신 배포 버전을 다운로드합니다.

cd /opt
sudo git clone <발급받은 저장소 주소> cephas
cd cephas
sudo bash deploy/exclude-docs.sh
TAG=$(curl -sf https://<배포 안내 사이트>/version.json | python3 -c "import json,sys; j=json.load(sys.stdin); print(j.get('tag') or 'v'+j['latest'])")
sudo git checkout "$TAG"

2-1 · 자동 설치 스크립트 (운영 서버 권장)

소스를 내려받았다면, 방법 B의 전 과정(DB 준비 → 백엔드 → 프론트 빌드 → 자동 실행 등록 → Nginx)을 자동으로 수행하는 스크립트를 쓸 수 있습니다. Ubuntu 22.04·24.04에서 검증되었습니다.

# 1) 먼저 계획만 확인 (아무것도 바꾸지 않음)
bash deploy/install.sh

# 2) 실제 설치 (root 권한 필요)
sudo bash deploy/install.sh --apply

다시 실행해도 안전합니다 — 이미 완료된 단계는 건너뜁니다(멱등, 재실행 안전).
설치 후 상태 점검·문제 진단은 sudo bash deploy/doctor.sh 로 언제든 할 수 있습니다.
이 스크립트를 썼다면 4절(방법 B)과 8-2·8-4절(Nginx·자동 실행)은 이미 처리된 것입니다 — 5절(첫 설정 마법사)로 바로 건너뛰고, 도메인·HTTPS(8-1·8-3절)만 이어서 하면 됩니다.

3 · 방법 A · Docker로 설치

3-0 · Docker 설치

curl -fsSL https://get.docker.com | sudo sh
sudo docker --version
sudo docker compose version

3-1 · 환경 파일(.env) 준비

sudo cp .env.example .env
sudo nano .env

필요한 시크릿 키 생성:

openssl rand -hex 32

3-2 · 컨테이너 실행

sudo docker compose up -d --build

빌드 시간

첫 빌드는 수 분 걸립니다. 완료 후 상태 확인: sudo docker compose ps

3-3 · 포트 3000 방화벽 열기

서버 방화벽:

sudo ufw allow 3000/tcp

VPS 업체 방화벽: 관리 콘솔에서 포트 3000 허용

4 · 방법 B · 직접 설치

4-1 · PostgreSQL 사용자·DB 만들기

sudo -u postgres createuser -s $USER
sudo -u postgres createdb cephas -O $USER

4-2 · 백엔드 · 프론트엔드

cd backend
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cat > .env <<'EOF'
DATABASE_URL=postgresql://USER@localhost/cephas
EOF
uvicorn main:app --reload

# 새 창에서
cd ../frontend
npm install
cat > .env.local <<'EOF'
NEXT_PUBLIC_API_URL=http://localhost:8000
BACKEND_INTERNAL_URL=http://127.0.0.1:8000
EOF
npm run dev

5 · 첫 설정 마법사

브라우저에서 http://[서버IP]:3000/setup 에 접속합니다.

1관리자 계정 생성
2본당 정보 입력 (본당명, 영문명, 사이트 URL)
3완료 후 자동으로 관리자 대시보드로 이동

6 · 동작 확인

다음 세 화면이 정상이면 설치 완료입니다.

홈 화면
로그인 화면
관리자 화면

IP만으로 운영할 경우 여기서 멈춰도 됩니다.

7 · (선택) 외부 서비스 연동

기능	효과
SMTP(이메일)	회원 이메일 인증·비밀번호 재설정
Google / Kakao 로그인	회원 소셜 로그인
AWS Bedrock	주보 PDF 자동 추출
카카오 지도	본당 위치 지도

모든 키는 /admin/settings 에서 설정합니다.

8 · 운영 배포 — 도메인·HTTPS 붙이기

8-1 · 도메인을 서버로 연결

도메인 관리 화면에서 A 레코드를 서버 IP로 지정합니다.

확인:

ping -c 2 [내도메인]

8-2 · Nginx 설치와 리버스 프록시

sudo apt -y install nginx
sudo nano /etc/nginx/sites-available/cephas

설정 파일 (포트는 환경에 맞게 조정):

server {
    listen 80;
    server_name [내도메인];

    location /api/auth/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

설정 활성화:

sudo ln -s /etc/nginx/sites-available/cephas /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

NextAuth 경로 예외 필수

/api/auth/ → 3000 블록이 없으면 로그인·소셜 로그인이 실패합니다.

8-3 · HTTPS 인증서 (Let's Encrypt)

sudo apt -y install certbot python3-certbot-nginx
sudo certbot --nginx -d [내도메인]
sudo certbot renew --dry-run

이후 https://[내도메인] 으로 접속됩니다.

필수 — AUTH_URL

공개 도메인이 생기면 프론트엔드 .env.local 에 AUTH_URL=https://[내도메인] 을 반드시 넣고 프론트를 재시작하세요. 빠뜨리면 회원가입·로그인 후 localhost:3000 으로 튕겨 로그인이 사실상 막힙니다. AUTH_TRUST_HOST=true 만으로는 리버스 프록시가 X-Forwarded-Host 를 안 보낼 때 부족합니다. (구 이름 NEXTAUTH_URL 도 같은 값으로 함께 넣으면 안전)

8-4 / 8-5 · 방법 B — 서비스 자동 실행

방법 B 사용 시 systemd 서비스로 등록하여 재부팅 후에도 자동 실행되도록 설정합니다. (방법 A는 Docker compose의 재시작 정책이 담당)

9 · 설치 후 점검 목록

https://도메인 으로 홈 화면이 뜬다
관리자 로그인이 된다
소셜 로그인이 된다 (설정 시)
주보 업로드·AI 추출이 동작한다 (AWS 키 설정 시)
서버 재부팅 후에도 사이트가 다시 뜬다

버전 업데이트

슈퍼관리자 대시보드의 업데이트 배너에서 한 번에 업데이트 가능 (자동 백업·롤백 포함)

문제 해결

증상	원인 · 해결
command not found	도구 미설치 (1절, 3-0절 참고)
:3000/setup 접속 불가	방화벽 설정 필요 (3-3절 참고)
첫 빌드가 느림	정상 (수 분 소요) — docker compose ps 로 확인
Peer authentication failed	sudo -u postgres 로 createuser 실행 (4-1절)
로그인 실패	Nginx의 /api/auth/ → 3000 경로 확인 (8-2절)
certbot 발급 실패	도메인 A 레코드 미반영 또는 포트 80 미개방 (8-1절)
setup 미표시	이미 관리자 계정 있음 — DB 초기화 필요
원인을 모를 때	sudo bash deploy/doctor.sh 로 서버 상태를 일괄 진단 (2-1절)