Installation Guide
설치 가이드
Docker Compose 기반 온프레미스 설치형. 고객사 서버에 5~10분이면 구축됩니다. Linux·Windows 둘 다 지원합니다.
최소 시스템 요구사항
공통
최소 사양
권장 사양
라이선스·패키지 준비
공통
가입·결제 후 라이선스 키를 발급받고, 설치 패키지에서 OS에 맞는 번들을 다운로드합니다.
OS 선택
여기서부터 분기됩니다
Linux 설치
🐧 Ubuntu 22.04+ / Debian 11+ / RHEL 8+ / Rocky Linux / CentOS Stream
단일 .tar.gz 패키지 설치
⭐ 표준 설치인터넷 없이도 설치 가능한 단일 패키지. Docker 미설치 시 자동 설치, 시크릿 자동 생성, 컨테이너 자동 기동까지 한 번에 끝납니다.
# 1. 패키지 다운로드 (구독자 포털) — 약 1.3GB
mkdir -p ~/documind-install && cd ~/documind-install
wget https://obj.documindkorea.com/documind-downloads/documind-appliance-vX.Y.Z.tar.gz
# 2. 압축 해제 (하위 폴더 없이 현재 폴더에 바로 풀림)
tar -xzf documind-appliance-vX.Y.Z.tar.gz
# 3. 설치 (관리자 권한)
sudo ./install.shinstall.sh 가 자동 처리:
- ✓ OS 자동 감지 (Ubuntu/Debian/CentOS/Rocky)
- ✓ Docker Engine + Compose 미설치 시 자동 설치 (apt/yum)
- ✓
/opt/documind에 파일 배치 - ✓
.env자동 생성 — DB/Redis/MinIO 비밀번호 + JWT/FERNET 키 랜덤 생성 - ✓ Docker 이미지 11개 로드 (인터넷 없이 패키지 내 .tar 사용)
- ✓ 컨테이너 기동 + 헬스체크 통과까지 자동 대기
⏱ 첫 설치 5~10분 후 http://[서버IP]/ 접속 가능
설치 후 자동 처리 (v1.0.12+)
install.sh 가 모든 작업을 자동 수행 — .env 수동 편집 불필요:
- • Docker 미설치 시 자동 설치 (curl get.docker.com)
- • 시크릿 자동 생성 (postgres / redis / minio / JWT / Fernet — openssl rand)
- • 컨테이너 일괄 기동 (docker compose up -d)
- • systemd timer 자동 등록 — env-reconcile (1분) + update-watcher (1분)
- • 활성화 코드 / AI 키 / 라이선스 ID — 브라우저 활성화 화면에서 자동 박힘
끝나면 안내된 URL (http://<server-ip>/activate) 로 브라우저 접속 후 운영사가 보낸 활성화 코드를 입력하면 라이선스·관리자 계정·AI 키가 자동 구성됩니다 (아래 §7 참고).
DNS A 레코드를 서버 외부 IP 로 지정하면 Caddy 가 Let's Encrypt 인증서를 자동 발급합니다.
업데이트
새 버전 패키지를 받아 같은 방식으로 실행하면 자동으로 업데이트 모드로 전환됩니다.
tar -xzf documind-appliance-vX.Y.Z+1.tar.gz
sudo ./install.sh # 기존 설치 감지 → update.sh 자동 위임- ✓ DB 자동 백업 →
/opt/documind/backups/<timestamp>/postgres-all.sql.gz - ✓ 고객 데이터 볼륨 보존 (PostgreSQL / MinIO / Redis / Caddy 인증서)
- ✓ 새 이미지 로드 + Alembic 마이그레이션 자동 (스키마만, 데이터 보존)
- ✓
.env보존 — 새 변수가 추가됐다면.env.template.new로 안내
Linux 트러블슈팅
⚠sudo 권한이 없습니다▼
root 계정 또는 sudo 권한을 가진 사용자로 실행해야 합니다. 클라우드 인스턴스는 root SSH 로 접속.
⚠포트 80·443 이 이미 사용 중▼
sudo lsof -i :80 으로 확인. nginx·apache·기타 웹서버가 있으면 중지 (sudo systemctl stop nginx). 또는 /opt/documind/compose.yml 에서 Caddy 포트 매핑 변경.
⚠container healthcheck 실패▼
cd /opt/documind && sudo docker compose -f compose.yml logs --tail 100 으로 확인. 가장 흔한 원인: 메모리 부족 (8GB 미만). free -h 로 확인.
⚠도메인 HTTPS 인증서 발급 안 됨▼
Caddy 가 Let's Encrypt 에서 인증서 발급 중. 80/443 이 외부에서 접근 가능해야 함. 로그: sudo docker logs documind-caddy.
Linux 삭제 · 제거
- PostgreSQL DB — 사용자·권한·메타데이터·채팅 기록
- MinIO 객체 스토리지 — 업로드한 원본 문서 파일
삭제 전 전체 백업 (필수)
아래 한 줄로 DB + 업로드 문서 + 설정을 모두 백업합니다.
# 백업 폴더 생성
BACKUP_DIR="$HOME/documind-final-backup-$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"
# 1. PostgreSQL DB 백업 (메타데이터)
docker exec documind-postgres pg_dump -U documind_super documind \
| gzip > "$BACKUP_DIR/db.sql.gz"
# 2. MinIO 업로드 문서 백업 (원본 파일들) — 가장 중요!
docker run --rm \
-v documind_minio_data:/data:ro \
-v "$BACKUP_DIR":/backup \
alpine tar czf /backup/uploaded-documents.tar.gz -C /data .
# 3. 설정·환경변수 백업
cp /opt/documind/.env "$BACKUP_DIR/env.backup"
cp /opt/documind/docker-compose.yml "$BACKUP_DIR/"
# 4. 백업 검증
ls -lh "$BACKUP_DIR"
echo "✅ 백업 완료: $BACKUP_DIR"
echo "👉 이 폴더를 USB·NAS·외부 디스크에 복사하세요"db.sql.gz— 1~10GB (메타데이터·인덱스)uploaded-documents.tar.gz— 회사 규모별 10GB ~ 1TB (가장 큼)env.backup— 1KB 이하
6-1컨테이너 중지 (데이터 보존)
나중에 다시 사용할 수 있도록 데이터는 그대로 두고 멈추기.
cd /opt/documind
sudo docker compose -f compose.yml down6-2완전 삭제 (데이터 포함)
모든 컨테이너·볼륨·설치 디렉토리 영구 제거.
# 컨테이너 정지 + 볼륨 삭제 (PostgreSQL/MinIO/Redis 데이터 사라짐)
cd /opt/documind
sudo docker compose -f compose.yml down
# 데이터 볼륨 명시 제거 — 실수 방지 차원에서 별도 명령
sudo docker volume rm $(sudo docker volume ls -q | grep '^documind-dev_')
# 설치 디렉토리 삭제
sudo rm -rf /opt/documind6-3Docker 자체 제거 (선택)
다른 도커 컨테이너도 안 쓴다면 Docker Engine 자체도 제거 가능.
# Docker 중지
sudo systemctl stop docker
# Ubuntu·Debian 계열
sudo apt remove -y docker-ce docker-ce-cli containerd.io
# RHEL·CentOS·Rocky 계열
sudo dnf remove -y docker docker-compose-plugin
# Docker 데이터까지 (모든 컨테이너 데이터 사라짐!)
sudo rm -rf /var/lib/docker /var/lib/containerd일시 중지 (데이터 보존)
컨테이너만 중지 — 재실행 시 데이터 그대로 복원
완전 삭제 (복구 불가)
볼륨·디렉토리까지 영구 제거 — 사전 백업 필수
활성화 & 접속 확인
공통 — 설치 후 1회
http://[서버IP]/activate (이 PC 면 https://localhost/activate) 로 접속해 운영사(판매처)가 메일로 보내준 활성화 코드(DM-XXXX-XXXX-XXXX-XXXX 형식)를 입력하면 됩니다. 라이선스·관리자 계정·AI 키가 자동으로 구성됩니다 — .env 수동 편집 불필요.활성화 흐름
활성화 후 두 개의 화면에 접속할 수 있습니다:
채팅앱 (직원용)
http://[서버IP]/chatAI 대화·문서 검색·문서 생성·나만의 규칙·스마트 메일
관리 대시보드 (관리자용)
http://[서버IP]/문서 업로드·직원 관리·운영사 연결·설정·감사 로그
https://[회사도메인]/ (회사가 보유한 도메인) 으로도 접속 가능합니다. 이 PC 에서만 쓸 땐 https://localhost/ (대시보드) · https://localhost/chat (채팅앱).운영사 연결 · 업데이트 메뉴에서 [업데이트 시작] 버튼으로 적용합니다 (데이터 보존, 5~10분 오프라인). 설치 패키지를 다시 받아 실행하는 수동 업데이트도 가능합니다.외부 접속 설정
외근 직원이 휴대폰으로 접속하려면
대부분의 한국 기업은 고정 공인 IP 가 없습니다 (KT/SKT/LGU+ 일반 기업 회선). 외부 접속이 필요하면 다음 3가지 방식 중 선택하세요. 보안 수준과 운영 인력 상황에 따라 다릅니다.
방법 1. DDNS + 포트포워딩 (가장 간단, 무료)
- DDNS 등록 — iptime 공유기는 펌웨어에서 바로 설정 가능 (예:
mycompany.iptime.org). 다른 공유기는 NoIP 또는 DuckDNS 무료 서비스 사용. - 공유기 포트포워딩 — 외부
443포트를 사내 DocuMind 서버 IP 의443으로 전달. 공유기 관리자 페이지에서 설정. - HTTPS 인증서 자동 발급 — Caddy/Nginx 설정에 도메인을 등록하면 Let's Encrypt 인증서가 자동 발급·갱신됩니다.
- 휴대폰 접속 확인 —
https://mycompany.iptime.org으로 접속 → 직원 화면 정상 로드.
방법 2. VPN (보안 강화, 권장)
- VPN 서버 설치 —
WireGuard(가장 가벼움·빠름) 또는OpenVPN. 기업용은Fortinet·SonicWall등 하드웨어 어플라이언스도 가능.# Ubuntu 예시 (WireGuard) sudo apt install wireguard wg genkey | tee private.key | wg pubkey > public.key # /etc/wireguard/wg0.conf 작성 후 sudo wg-quick up wg0
- 외근자 휴대폰 — App Store/Play Store 에서 WireGuard 앱 설치 후 설정 파일/QR 코드 스캔.
- VPN 연결 후 사내 IP 로 접속 —
http://10.0.0.x/또는 사내 도메인. DocuMind 자체는 외부에 노출 X.
방법 3. Cloudflare Tunnel (포트포워딩 불가 시)
공유기 관리 권한이 없거나 사내 방화벽이 inbound 를 막고 있다면 Cloudflare 의 cloudflared 데몬을 사내 서버에 설치 → 사내 → Cloudflare 로 outbound-only 터널 → 외부 사용자는 https://[회사도메인] 으로 Cloudflare 를 통해 접속.
- 무료 티어 — 트래픽·도메인 1개
- HTTPS 자동, DDoS 방어 무료
- 설정 5분 —
cloudflared tunnel create documind
- 관리자 비밀번호 12자 이상 + 영문 대소문자·숫자·특수문자 혼합
- 가능하면 직접 노출 대신 VPN(방법 2) 뒤에 두기 — 네트워크 레벨 2차 인증 효과
- 로그인 실패 5회 → 자동 잠금 (DocuMind 기본 정책)
- 주기적 감사 로그 검토 (
/settings/audit페이지) - 의심스러운 접속 IP 차단 (Caddy/Nginx 레벨 또는 방화벽)
다음 단계
설치 중 오류가 발생했나요?
로그(Linux: docker compose logs, Windows: 이벤트 뷰어 또는 같은 명령) 를 첨부해서 문의 폼에 보내주세요. 영업일 1~2일 내 기술팀이 직접 답변 드립니다.