팀 서버 설치

이 페이지는 서버 운영 담당자를 위한 안내입니다. 팀원은 웹 주소와 계정만 받으면 됩니다. 서버는 모두가 같은 지식에 접속할 수 있도록 계속 실행해 두는 컴퓨터입니다.

설치 전 준비

정식 운영 구성은 서버 한 대의 SQLite, 앱 프로세스 하나와 작업자 하나입니다. 작업자는 백그라운드 작업을 처리합니다. 별도 데이터베이스 서버는 필요하지 않습니다. 데이터베이스를 NFS에 두거나 앱·작업자를 여러 개로 늘리지 마세요. 워크스페이스별 접근 제어는 같은 데이터베이스 안에서 이루어지며 물리적으로 독립된 데이터베이스를 제공하지는 않습니다.

현재 설명서의 설치 예시는 v0.1.2입니다. 설치 스크립트, 앱 패키지, 작업자를 같은 릴리스로 고정하세요. 운영 설치는 별도 자료 위치를 사용하며 개인 로컬 설치의 계정과 파일을 자동으로 옮기지 않습니다.

다음을 준비합니다.

systemd 경로는 root 권한이 있는 Ubuntu 22.04+ 서버. Docker 경로는 64-bit Linux, Docker Engine, Compose v2, Git.
서버를 가리키는 DNS가 설정된 도메인. 예: wiki.example.com. 공개 HTTPS에는 외부에서 접근 가능한 80·443 포트가 필요합니다.
의존성 설치와 인증서 발급에 필요한 외부 통신.
앱 소스 디렉터리와 별개인 보호된 백업 저장소. 백업과 유지보수를 참고하세요.

예시 도메인과 이메일은 실제 값으로 바꾸세요. 설치 도구는 서비스 계정을 만들고 패키지를 설치하며 HTTPS 프록시인 Caddy를 구성합니다. 새 서버를 사용하거나 기존 서비스와의 충돌을 먼저 확인하세요.

방법 A: Ubuntu의 systemd

1. 공개 패키지와 설치 스크립트 준비

Linux/WSL2 준비 컴퓨터에서 Git과 pip를 사용하는 Python 3.12로 공개 PyPI wheel을 받습니다. 이 경로에는 Node.js나 프런트엔드 빌드가 필요하지 않습니다. 설치 스크립트와 wheel은 동일한 릴리스 태그에서 가져옵니다.

python3.12 --version
git clone --branch v0.1.2 https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.1.2
cd dtxWiki-0.1.2
python3.12 -m pip download --no-deps --only-binary=:all: --dest wheelhouse "dtxwiki==0.1.2"
sha256sum wheelhouse/dtxwiki-0.1.2-py3-none-any.whl infra/prod/install.sh
scp wheelhouse/dtxwiki-0.1.2-py3-none-any.whl operator@wiki.example.com:/tmp/
scp infra/prod/install.sh operator@wiki.example.com:/tmp/install.sh

새 checkout 디렉터리를 사용하고 SSH 계정과 서버 호스트명을 자신의 값으로 바꾸세요. SHA-256 결과를 기록하고 서버 전송 후 비교합니다. --no-deps는 dtxWiki wheel만 받으며 Python 의존성은 이후 설치 도구가 받습니다.

선택 사항: wheel을 직접 빌드

깨끗한 checkout에서 Linux/WSL2, Python 3.12, Node.js 22.18+, npm, Git, GNU Make를 사용합니다.

git clone https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.1.2
cd dtxWiki-0.1.2
git checkout --detach v0.1.2
make install PYTHON=python3.12
npm run playwright:install
make test-packaged
.venv/bin/python scripts/verify_wheel_artifact.py dist
sha256sum dist/dtxwiki-0.1.2-py3-none-any.whl infra/prod/install.sh
scp dist/dtxwiki-0.1.2-py3-none-any.whl operator@wiki.example.com:/tmp/
scp infra/prod/install.sh operator@wiki.example.com:/tmp/install.sh

make test-packaged는 wheel을 만들고 설치된 웹 화면과 API를 검사합니다. dist에 이번 빌드만 남도록 깨끗한 checkout을 사용하세요. SHA-256 결과를 기록하고, 전송 후 값이 같은지 확인합니다.

설명서의 예시 버전을 설치하려면 버전을 지정하지 않은 “최신 패키지” 설치를 피하세요.

2. 서버에 설치하기

ssh operator@wiki.example.com
sha256sum /tmp/dtxwiki-0.1.2-py3-none-any.whl /tmp/install.sh
chmod 0644 /tmp/dtxwiki-0.1.2-py3-none-any.whl
sudo bash /tmp/install.sh \
  --domain wiki.example.com \
  --email admin@example.com \
  --tls acme \
  --wheel /tmp/dtxwiki-0.1.2-py3-none-any.whl

설치 도구는 Python, Caddy, 서비스 계정, 설정, 데이터베이스, 서비스, 초기 소유자 계정을 준비하고 초기 계정에 서버 관리자 권한도 자동 부여합니다. wheel은 dtxWiki 버전을 고정하지만 Python 의존성은 설정된 패키지 저장소에서 설치합니다.

초기 임시 비밀번호는 한 번 표시됩니다. 보관한 뒤 내 컴퓨터에서 https://wiki.example.com/을 열고 --email로 지정한 이메일과 해당 비밀번호로 로그인합니다. 서버에서 브라우저를 실행할 필요는 없습니다. 계정 → 비밀번호에서 변경하세요. 놓쳤다면 서버의 대화형 터미널에서 일회용 재설정 링크를 발급합니다.

sudo dtxwiki users issue-password-reset admin@example.com --delivery link

계정 소유자에게 안전하게 전달하세요. 수신자가 직접 새 비밀번호를 정합니다. 링크를 공동 로그에 남기지 마세요.

3. 정상 동작 확인

sudo systemctl --no-pager --full status dtxwiki dtxwiki-worker caddy
curl -fsS https://wiki.example.com/health/live
curl -fsS https://wiki.example.com/health/ready
curl -i https://wiki.example.com/mcp

두 health 요청은 성공해야 합니다. 인증 정보 없이 요청한 /mcp는 인증 안내를 포함한 401을 반환하는 것이 정상입니다. 앱과 작업자가 모두 활성 상태여야 합니다. 브라우저에서 로그인해 Personal Workspace와 설정 → 배포를 확인하고 연습용 Context 페이지를 만든 뒤 서비스 재시작 후에도 유지되는지 확인하세요. 시작·로그·종료는 서비스 운영을 따르세요.

systemd 운영 명령은 sudo dtxwiki ...로 실행합니다. 설치된 래퍼가 /etc/dtxwiki/dtxwiki.env를 읽어 운영 데이터베이스를 사용합니다. root에서 /opt/dtxwiki/.venv의 실행 파일을 환경 설정 없이 직접 실행하면 다른 데이터베이스를 가리킬 수 있습니다.

방법 B: Docker Compose

공개된 v0.1.2 컨테이너 이미지는 없습니다. Compose가 소스로 이미지를 빌드합니다.

git clone https://github.com/dtxSuite/dtxWiki.git dtxWiki-0.1.2
cd dtxWiki-0.1.2
git checkout --detach v0.1.2
cd infra/prod
cp .env.docker.example .env

.env를 열고 DTXWIKI_DOMAIN=wiki.example.com, DTXWIKI_ADMIN_EMAIL=admin@example.com을 설정합니다. 이메일은 인증서 알림용이며 dtxWiki 계정을 생성하지 않습니다. 나중에 메일 자격 증명을 추가할 수 있으므로 .env는 비공개로 보관하세요.

docker compose up -d --build
docker compose ps
docker compose exec app dtxwiki users add admin@example.com
docker compose exec app dtxwiki admin grant --email admin@example.com
curl -fsS https://wiki.example.com/health/ready

users add는 8자 이상 비밀번호를 두 번 숨김 입력으로 받고 해당 계정의 Personal Workspace를 만듭니다. admin grant는 기존 계정에 서버 관리자 권한을 부여합니다. HTTPS 서버 주소에서 해당 이메일·비밀번호로 로그인하고 설정 → 배포를 확인하세요. 초기 init 서비스는 앱·작업자 시작 전에 키와 DB를 준비합니다. 데이터와 키, 세션 비밀값은 data volume에 보관됩니다.

이후 업데이트에서도 같은 checkout 위치와 Compose 프로젝트 이름을 유지하세요. 볼륨을 지우거나 다른 프로젝트를 만들면 빈 데이터베이스가 보일 수 있습니다. docker compose down -v를 업데이트 절차로 사용하지 마세요.

내부망과 기존 프록시

네트워크	systemd 설치의 TLS 모드	추가 준비
공개 도메인	`--tls acme`	올바른 DNS와 80·443 접근
내부 호스트명 또는 IP	`--tls internal`	각 브라우저·MCP 클라이언트에 Caddy root CA를 배포하고 신뢰 설정
보유한 인증서	`--tls custom`	`--tls-cert`, `--tls-key` 지정
기존 HTTPS 프록시	`--tls external`	신뢰할 프록시 IP를 `--forwarded-ip`로 지정. 다른 서버의 프록시라면 `--bind-host`를 지정하고 앱 포트를 해당 프록시만 접근하도록 제한

평문 HTTP(--tls none --insecure-eval)는 평가용이며 표준 OAuth 연결을 지원하지 않습니다. 인증서 신뢰와 Docker 내부 CA 설정은 운영 안내를 따르세요.

팀원 추가와 유지 관리

팀·원격 모드는 공개 회원가입이 기본적으로 닫혀 있습니다. sudo dtxwiki users add person@example.com으로 계정을 만든 뒤 워크스페이스 소유자가 멤버십을 부여합니다. 계정과 접근을 참고하세요.

설정 → 배포는 서버 관리자에게 운영 상태를 보여줍니다. 서버 설정은 CLI에서 변경하며 웹 앱이 시스템 설정 파일에 쓰지는 않습니다. 데이터·키·설정을 한 세트로 백업하고, 버전 변경 전에는 백업과 유지보수를 따르세요.

선택 사항: 이메일 전송

계정 생성·로그인·일상적인 위키 사용에는 SMTP가 필요하지 않습니다. 이메일 확인, 메일 복구 또는 지원하는 알림이 필요할 때 추가하세요. Gmail 예시를 포함한 이메일과 SMTP를 따르고 앱·작업자에 같은 메일 환경을 적용합니다. 사용자가 메일로 직접 복구하려면 HTTPS와 확인된 계정 이메일이 필요합니다.

버전 근거: 운영 안내, 운영 Compose 구성.

설치 전 준비​

방법 A: Ubuntu의 systemd​

1. 공개 패키지와 설치 스크립트 준비​

2. 서버에 설치하기​

3. 정상 동작 확인​

방법 B: Docker Compose​

내부망과 기존 프록시​

팀원 추가와 유지 관리​

선택 사항: 이메일 전송​