서버 마련·설치
📦세파스 설치 방법
본당 소유의 서버에 세파스를 처음 설치하는 절차입니다. 초보자도 단계를 따라 설치할 수 있도록 구성되었습니다.
마지막 업데이트 2026-08-01
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-certificates2 · 소스 내려받기
접근 권한 필수
세파스 코드는 도입한 본당에만 접근 권한이 열립니다.
발급받은 저장소에서 최신 배포 버전을 다운로드합니다.
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 version3-1 · 환경 파일(.env) 준비
소스 안의 예시 파일을 복사해 값을 채웁니다. 파일 이름은 반드시 .env 여야 합니다 — docker compose 는 이 이름만 자동으로 읽습니다.
sudo cp .env.docker.example .env
sudo nano .env필요한 시크릿 키 생성 (한 줄씩 만들어 붙여 넣습니다):
openssl rand -hex 32반드시 채워야 하는 값:
| 항목 | 무엇을 넣나 |
|---|---|
| POSTGRES_PASSWORD | 데이터베이스 비밀번호 — 직접 정한 강한 문자열 |
| SECRET_KEY | openssl 로 만든 32자 이상 문자열 |
| INTERNAL_API_SECRET | openssl 로 만든 32자 이상 문자열(앞의 것과 다른 값) |
| CORS_ORIGINS · SITE_URL | 도메인이 정해졌으면 https://내도메인, 아직이면 http://서버IP:3000 |
CHANGE_ME 가 남아 있으면 뜨지 않습니다
예시 파일의 값은 자리표시자(CHANGE_ME_…)입니다. 그대로 두면 컨테이너가 뜨다가 멈추거나 로그인이 동작하지 않습니다. 시크릿은 사람이 직접 채워야 하며 스크립트가 만들어 주지 않습니다.
3-2 · 컨테이너 실행
sudo docker compose up -d --build빌드 시간
첫 빌드는 수 분 걸립니다. 완료 후 상태 확인: sudo docker compose ps
3-3 · 포트 3000 방화벽 열기
⚠ 방화벽을 처음 켤 때는 SSH 부터 열어야 합니다
ufw 를 켜기 전에 반드시 22번(SSH)을 먼저 허용하세요. 순서를 바꾸면 켜는 순간 원격 접속이 끊겨 서버에 다시 들어갈 수 없게 됩니다(VPS 콘솔로만 복구 가능). 이미 켜 둔 서버라면 sudo ufw status 로 22/tcp 가 ALLOW 인지 먼저 확인하세요.
서버 방화벽 — 순서대로:
sudo ufw allow OpenSSH # 먼저! (또는 sudo ufw allow 22/tcp)
sudo ufw allow 3000/tcp
sudo ufw enable
sudo ufw status나중에 도메인·HTTPS 를 붙이면(8절) 80·443 도 열어야 합니다 — sudo ufw allow 'Nginx Full'. 그때는 3000 을 다시 닫아도 됩니다(신자는 80·443 으로만 들어옵니다).
VPS 업체 방화벽: 관리 콘솔에서도 같은 포트를 허용해야 합니다(서버 방화벽과 별개입니다).
4 · 방법 B · 직접 설치
4-1 · PostgreSQL 사용자·DB 만들기
역할(사용자)을 만들 때 비밀번호를 함께 정합니다. <비밀번호> 자리는 직접 정한 값으로 바꾸세요.
sudo -u postgres psql -c "CREATE ROLE cephas LOGIN PASSWORD '<비밀번호>'"
sudo -u postgres createdb cephas -O cephas비밀번호를 빠뜨리면 백엔드가 DB 에 붙지 못합니다
Ubuntu 의 기본 설정은 앱이 쓰는 연결 방식(127.0.0.1 TCP)에 비밀번호를 요구합니다. 비밀번호 없이 역할만 만들면 psql 로는 들어가지지만 백엔드는 인증에 실패합니다. 그래서 backend/.env 의 주소도 비밀번호를 포함한 형태여야 합니다.
DATABASE_URL=postgresql://cephas:<비밀번호>@localhost/cephas4-2 · 백엔드 · 프론트엔드
데이터베이스 주소에 비밀번호를 넣으세요
우분투 기본 설정에서는 앱이 데이터베이스에 붙을 때 비밀번호를 요구합니다. 비밀번호 없이 적으면 백엔드가 접속하지 못합니다 — 앞서 만든 사용자의 비밀번호를 넣으십시오(v2.15.0 이상 안내 파일도 이 형태로 고쳤습니다).
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 dev5 · 첫 설정 마법사
브라우저에서 http://[서버IP]:3000/setup 에 접속합니다.
- 1관리자 계정 생성
- 2본당 정보 입력 (본당명, 영문명, 사이트 URL)
- 3완료 후 자동으로 관리자 대시보드로 이동
6 · 동작 확인
다음 세 화면이 정상이면 설치 완료입니다.
- 홈 화면
- 로그인 화면
- 관리자 화면
IP만으로 운영할 경우 여기서 멈춰도 됩니다.
7 · (선택) 외부 서비스 연동
| 기능 | 효과 |
|---|---|
| SMTP(이메일) | 회원 이메일 인증·비밀번호 재설정 |
| Google / Kakao 로그인 | 회원 소셜 로그인 |
| Anthropic API 키 (또는 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 nginxNextAuth 경로 예외 필수
/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 추출이 동작한다 (AI 키 설정 시)
- 서버 재부팅 후에도 사이트가 다시 뜬다
버전 업데이트
슈퍼관리자 대시보드의 업데이트 배너에서 한 번에 업데이트 가능 (자동 백업·롤백 포함)
문제 해결
| 증상 | 원인 · 해결 |
|---|---|
| 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절) |