접속과 백그라운드 실행

설치와 첫 로그인이 정상 동작한 뒤 사용하는 안내입니다. 앱을 실행하는 담당자를 위한 명령이며, 다른 사용자는 서버 주소와 자신의 계정만 있으면 됩니다.

계속 실행할 방법 선택

방법	동작	재부팅·장애 이후
터미널의 `dtxwiki`	로컬 앱과 백그라운드 작업자 실행, 브라우저 열기	직접 다시 시작
`dtxwiki serve --no-open`	브라우저를 열지 않고 앱과 백그라운드 작업자 실행	직접 다시 시작. 여전히 터미널에서 실행
`nohup` 또는 별도 Windows 창	처음 터미널과 별개로 앱과 백그라운드 작업자 실행 유지	부팅 자동 시작·장애 후 재시작 기능 없음
설치된 systemd·Docker 서비스	앱과 별도 작업자 서비스를 지속 운영	구성한 서비스 재시작 정책 사용

로컬 dtxWiki는 백그라운드 작업자를 직접 시작하고, 앱을 중지하면 작업자도 함께 중지합니다. 작업자는 Library 자료 추출, 대기 중인 계정 메일 발송, 첨부 파일 정리 같은 작업을 처리합니다. 따라서 위의 로컬 실행 방법은 모두 명령 하나로 시작하고 한 번에 중지하며, 별도 작업자 명령은 필요하지 않습니다. v0.1.2에서 쓰던 스크립트나 바로 가기가 작업자도 시작한다면 그 부분을 지우세요. 같은 자료에 두 번째 작업자를 실행하면 거부됩니다.

자동 시작을 직접 구성한다면(예: 운영체제의 시작 프로그램 도구나 프로세스 관리자) 같은 OS 사용자와 설정으로 dtxwiki serve --no-open만 실행하게 하세요. 프로세스 관리자가 작업자를 별도 프로세스로 실행해야 한다면 external 모드를 사용합니다.

실행 중인 앱을 확인하려면 같은 컴퓨터에서 http://127.0.0.1:21080/health/ready를 엽니다. "status":"ready"와 "worker":"ok"가 보이면 앱과 백그라운드 작업자가 준비된 상태입니다. 서버 관리자는 설정 → 배포에서도 확인할 수 있습니다. 상태에 준비됨이 표시되고, 준비되지 않았다면 비정상과 함께 백그라운드 처리를 포함한 구성 요소 목록이 나타납니다.

다른 사람이 접속하려면 컴퓨터가 계속 켜져 있어야 합니다. 지속적인 공동 사용에는 개인 터미널 대신 공유 서버 구성을 사용하세요.

주소 이해하기

설정 또는 주소	의미
`http://127.0.0.1:21080/`	이 주소를 여는 컴퓨터의 기본 로컬 앱
`serve --host 0.0.0.0`	모든 IPv4 인터페이스에서 연결 받기. `0.0.0.0`은 수신 설정이며 사용자에게 줄 접속 URL이 아님
`DTXWIKI_PUBLIC_BASE_URL`	실제 대표 접속 URL. 서버 링크·공개 메타데이터에 사용하며 해당 호스트는 자동 허용
`DTXWIKI_ALLOWED_HOSTS`	추가 허용 호스트명·IP를 쉼표로 구분. 예: `wiki.lan,192.168.1.20`
HTTPS 역방향 프록시	운영 배포의 HTTPS 제공. URL만 설정해도 인증서가 설치되는 것은 아님

앱은 루프백 이름(localhost, 127.0.0.1, ::1), 대표 URL의 호스트, 추가 허용 호스트를 받습니다. IP 접속에도 허용된 IP가 필요합니다. 검사를 유지하고 실제 사용할 호스트를 지정하세요. DTXWIKI_ALLOWED_HOSTS=*는 모든 호스트명과 IP의 검사를 끕니다.

번들 UI는 자신의 서버 API를 사용하므로 같은 주소로 접속할 때 별도 CORS 설정은 필요하지 않습니다. Host 오류가 표시되면 앱까지는 접속한 상태입니다. 요청한 호스트명·IP와 허용 설정을 먼저 비교하세요.

신뢰하는 LAN의 다른 기기에서 시험하기

HTTP 평가용 예시입니다. HTTP는 비밀번호와 세션 쿠키를 암호화하지 않습니다. 지속적인 팀 사용, 인터넷 접속 또는 메일 복구에는 HTTPS 배포를 구성하세요. 내부망도 해당 안내의 TLS 방식을 사용할 수 있습니다.

먼저 로컬에서 로그인되는지 확인합니다.
기존 앱을 Ctrl+C로 중지합니다. 백그라운드 작업자도 함께 중지됩니다. 같은 자료를 쓰는 dtxWiki를 하나 더 시작하면 포트가 달라도 거부됩니다.
서버 컴퓨터의 LAN IP를 확인하고 아래 192.168.1.20을 그 IP로 바꿉니다.
URL을 적용하고 앱을 다시 시작합니다.

Linux/macOS:

export DTXWIKI_PUBLIC_BASE_URL=http://192.168.1.20:21080
dtxwiki serve --host 0.0.0.0 --port 21080 --no-open

Windows PowerShell:

$env:DTXWIKI_PUBLIC_BASE_URL = "http://192.168.1.20:21080"
dtxwiki serve --host 0.0.0.0 --port 21080 --no-open

npm에서는 dtxwiki 대신 npx @dtxsuite/dtxwiki@0.2.1을 사용합니다. 위 URL이 해당 IP를 자동 허용하므로 DTXWIKI_ALLOWED_HOSTS에 같은 IP를 중복 입력할 필요는 없습니다. 백그라운드 작업자도 이 URL을 포함해 앱과 같은 설정을 사용합니다.

다른 기기에서 http://192.168.1.20:21080/을 열고 로그인합니다. 서버 방화벽에서 사용할 LAN 기기에 TCP 21080을 허용하세요. 가상 머신·WSL은 추가 포트 전달이 필요할 수 있습니다. Microsoft의 WSL 네트워크 안내를 확인하세요.

예상 결과: 두 기기가 같은 서버와 계정에 접속합니다. 공유 공간 접근은 여전히 멤버십을 따르며 호스트 허용이 자료 접근 권한을 주지는 않습니다. 기본 로컬 모드는 가입도 허용하므로 이 서버에 접속할 수 있는 사람이 계정을 만들 수 있습니다.

이 LAN에서 AI 앱을 연결하려면 액세스 키를 사용합니다. 대표 URL을 서버의 사설 IP 주소로 설정하면 설정 → MCP 접근의 액세스 키 설정에서 http://192.168.1.20:21080/mcp용 설정 명령을 표시할 수 있습니다. 평문 HTTP에서는 wiki.lan 같은 호스트명을 받지 않으며, OAuth에는 HTTPS가 필요합니다. 키가 암호화되지 않은 채 전달되므로 신뢰하는 네트워크에서만 사용하고 평가가 끝나면 해지하세요. AI 앱 연결을 참고하세요.

터미널의 환경변수는 해당 프로세스와, 앱의 백그라운드 작업자를 포함한 자식 프로세스에 적용됩니다. 새 터미널은 첫 터미널에서 변경한 값을 상속하지 않습니다. DTXWIKI_DATA_DIR, DB와 다른 설정을 앱과 관리 명령에 동일하게 적용하세요. 임의의 .env 파일을 로컬 CLI가 자동으로 읽지는 않습니다.

기본 로컬 사용으로 돌아가려면 Ctrl+C로 앱을 중지하고 해당 터미널에서 예시 URL을 제거한 뒤 다시 시작합니다.

# Linux/macOS
unset DTXWIKI_PUBLIC_BASE_URL

# Windows PowerShell
Remove-Item Env:DTXWIKI_PUBLIC_BASE_URL -ErrorAction SilentlyContinue

--host 0.0.0.0 없이 일반 로컬 실행 명령을 사용하세요. 평가용 방화벽 규칙을 추가했다면 더 이상 필요하지 않을 때 제거합니다.

Linux/macOS: 로컬 앱을 백그라운드에서 실행

먼저 터미널에서 정상 실행되는지 확인한 뒤 기존 앱을 중지합니다. OS 사용자와 환경을 그대로 사용하세요. 바꾸면 다른 자료를 선택할 수 있습니다.

uv/pipx 설치:

nohup dtxwiki serve --no-open > dtxwiki.log 2>&1 < /dev/null &

npm:

nohup npx --yes @dtxsuite/dtxwiki@0.2.1 serve --no-open > dtxwiki.log 2>&1 < /dev/null &

LAN 접속을 의도하고 대표 URL도 설정했을 때만 --host 0.0.0.0 --port 21080을 추가하세요. --yes는 npm 패키지 다운로드 확인에 동의하므로 첫 대화형 실행을 확인한 뒤 사용합니다.

백그라운드 앱은 자체 작업자를 시작합니다. tail -f dtxwiki.log로 로그를 보면 작업자가 처리한 작업과 오류도 함께 확인할 수 있습니다. Ctrl+C는 로그 보기만 종료하며 백그라운드 앱을 종료하지 않습니다. 로그 파일은 명령을 실행한 디렉터리에 생깁니다.

실제 프로세스 종료

lsof가 설치되어 있다면 앱 포트에서 수신 중인 프로세스를 확인합니다.

lsof -nP -iTCP:21080 -sTCP:LISTEN

SERVER_PID를 실제 수신 프로세스의 PID로 바꾸어 kill -TERM SERVER_PID를 실행합니다. dtxWiki는 웹 서버를 중지한 다음 백그라운드 작업자를 중지하며, 작업자는 진행 중인 단계를 마치는 데 최대 10초를 사용할 수 있습니다. npm을 사용한다면 실행기 자체의 PID가 아니라 수신 프로세스의 PID를 사용하세요. 대상을 확인한 뒤 중지하고, 유지보수 전에는 반드시 종료하세요.

포트에서 더 이상 수신하지 않고 작업자도 남아 있지 않은지 확인합니다. ps -ax -o pid,ppid,command에서 작업자는 앱의 자식 프로세스로 표시되며 명령에 backend.worker.managed가 포함됩니다. 앱이 중지되지 않으면 kill -KILL SERVER_PID로 종료할 수 있습니다. 이때 작업자는 약 10초 안에 스스로 종료하며, 그 전에 dtxWiki를 다시 시작하면 dtxWiki is already running or storage is still active로 거부됩니다. nohup은 부팅 시 자동 시작이나 장애 후 자동 재시작을 구성하지 않습니다.

Windows: 앱을 별도 창에서 유지

터미널에서 정상 실행을 확인한 뒤 기존 앱을 중지합니다. 같은 환경의 PowerShell에서 앱 창을 엽니다.

# uv/pipx 설치
Start-Process dtxwiki -ArgumentList "serve --no-open"

npm:

Start-Process npx.cmd -ArgumentList "--yes @dtxsuite/dtxwiki@0.2.1 serve --no-open"

새 프로세스는 현재 PowerShell의 환경을 상속하고 자체 백그라운드 작업자를 시작합니다. LAN 접속이 필요하면 대표 URL을 먼저 설정하고 ArgumentList에 수신 옵션도 넣으세요. 새 창을 보여 두어 시작 오류를 확인합니다.

처음 PowerShell을 닫아도 이 별도 창은 종료되지 않습니다. 해당 창에서 Ctrl+C를 누르면 dtxWiki와 백그라운드 작업자가 함께 중지됩니다. 이 창은 장애 후 재시작이나 부팅 자동 시작을 제공하지 않습니다. Windows 로컬 사용과 Linux 운영 서버 구성은 다른 경로입니다.

관리 명령 실행

dtxwiki admin …, dtxwiki users …, dtxwiki bootstrap 같은 로컬 관리 명령은 앱을 중지한 상태에서 실행합니다. 앱이 실행 중이면 stop dtxWiki (server and worker) first가 포함된 오류와 함께 중단되며 아무것도 바꾸지 않습니다.

앱을 실행 중인 터미널에서 Ctrl+C를 누릅니다. 백그라운드 앱은 위에서 설명한 방법으로 중지합니다.
같은 OS 사용자와 설정으로 명령을 실행합니다. npm 사용자는 npx @dtxsuite/dtxwiki@0.2.1 … 형태로 실행합니다.
앱을 다시 시작합니다.

dtxwiki inputs audit은 데이터베이스를 읽기만 하므로 앱이 실행 중일 때도 사용할 수 있습니다.

관리자는 실행 중인 앱이 데이터베이스 준비를 마친 뒤라면 관리·계정 명령을 앱과 함께 실행할 수 있습니다. 해당 명령에만 DTXWIKI_AUTO_BOOTSTRAP=false를 지정하면 명령이 데이터베이스를 준비하지 않고 상태만 확인합니다.

DTXWIKI_AUTO_BOOTSTRAP=false dtxwiki admin list

$env:DTXWIKI_AUTO_BOOTSTRAP = "false"
dtxwiki admin list
Remove-Item Env:DTXWIKI_AUTO_BOOTSTRAP

dtxwiki를 시작하는 터미널에는 이 설정을 남겨 두지 마세요. 설정이 남아 있으면 업그레이드 후 앱이 데이터베이스를 업그레이드하지 않고 시작을 거부합니다. dtxwiki bootstrap과 입력값 복구 명령(dtxwiki users set-display-name, dtxwiki users set-email, dtxwiki inputs repair-metadata)은 항상 dtxWiki를 중지한 상태에서 실행해야 합니다.

설치된 서비스는 이미 이 방식으로 동작합니다. sudo dtxwiki users …와 docker compose exec app dtxwiki …는 서비스가 실행 중일 때도 사용할 수 있지만, sudo dtxwiki bootstrap과 입력값 복구 명령은 서비스를 중지한 뒤 실행해야 합니다.

작업자를 직접 실행하기(external 모드)

자체 프로세스 관리자에서 백그라운드 작업자를 별도 프로세스로 시작해야 하는 운영자를 위한 고급 방식입니다. 설정한 데이터베이스가 일반 로컬 SQLite 파일이 아닐 때도 이 방식이 필요합니다. 일반 로컬 사용과 설치된 systemd·Docker 서비스에는 이 절차가 필요하지 않습니다. Python 패키지의 dtxwiki-worker 명령을 사용합니다.

이 자료를 사용하는 dtxWiki 프로세스를 모두 중지합니다.
아래의 모든 명령에 같은 설정을 적용합니다. DTXWIKI_DATA_DIR, 데이터베이스, 비밀값, 메일 설정과 함께 DTXWIKI_WORKER_MODE=external, DTXWIKI_AUTO_BOOTSTRAP=false를 지정합니다. 앱에는 환경 변수 대신 --worker-mode external 옵션을 사용할 수도 있습니다.
데이터베이스를 한 번 준비합니다.

export DTXWIKI_WORKER_MODE=external
export DTXWIKI_AUTO_BOOTSTRAP=false
dtxwiki bootstrap

프로세스 관리자가 앱(dtxwiki serve --no-open)과 작업자 하나(dtxwiki-worker run)를 시작하게 합니다. 시작 순서는 상관없습니다.

같은 데이터베이스에 두 번째 작업자를 실행하면 거부됩니다. 새 버전을 설치한 뒤에는 둘 다 중지하고 dtxwiki bootstrap을 다시 실행한 다음 둘 다 시작합니다. 이 모드에서는 앱이 작업자를 감시하지 않으므로 /health/ready가 "worker":"n/a"를 표시합니다. 작업자 프로세스는 직접 확인하세요.

설치된 운영 서비스 관리

먼저 공유 서버 설치를 완료해야 합니다. pipx/uv 설치만으로 아래 서비스가 생성되지는 않습니다.

Ubuntu systemd 서비스를 설치했다면:

sudo systemctl enable --now dtxwiki dtxwiki-worker
sudo systemctl --no-pager --full status dtxwiki dtxwiki-worker
sudo journalctl -u dtxwiki -u dtxwiki-worker -f

첫 명령은 부팅 자동 시작을 켜고 두 서비스를 실행합니다. 모두 활성 상태인지 확인하세요. Ctrl+C는 로그 보기만 종료합니다. 실제 서비스를 중지하려면:

sudo systemctl stop dtxwiki dtxwiki-worker

두 서비스는 /etc/dtxwiki/dtxwiki.env를 읽습니다. 설치 과정과 sudo dtxwiki update가 이 파일에 DTXWIKI_WORKER_MODE=external을 기록하므로 dtxwiki 서비스는 dtxwiki-worker 옆에서 두 번째 작업자를 시작하지 않습니다. dtxwiki-worker.service를 사용하는 동안에는 이 줄을 유지하세요. 설치된 환경 로딩 wrapper를 통해 sudo dtxwiki ...로 관리하세요. 운영 자료의 기본 위치는 /var/lib/dtxwiki이며 로컬 사용자의 .dtxwiki를 자동 복사하지 않습니다.

Docker를 이미 설치했다면 같은 infra/prod 디렉터리와 Compose 프로젝트에서 실행합니다.

docker compose up -d
docker compose ps
docker compose logs --tail=50 app worker

이미지의 앱은 자체 작업자를 실행하지 않으며 Compose의 worker 서비스가 작업을 처리합니다. Compose 설정에 DTXWIKI_WORKER_MODE를 추가하지 마세요. docker compose stop app worker로 쓰기 프로세스를 중지합니다. 저장된 볼륨은 유지하세요. 볼륨 삭제는 종료나 업데이트 절차가 아닙니다.

예상 결과: 앱과 작업자가 실행 중이고 실제 HTTPS 서버 주소의 /health/ready가 성공하며 브라우저에서 로그인해 저장한 페이지를 읽을 수 있습니다. 이 서비스 구성의 /health/ready는 별도 작업자를 검사하지 않고 "worker":"n/a"를 표시하므로 dtxwiki-worker 서비스나 worker 컨테이너가 실행 중인지도 확인하세요. 실패하면 문제 해결, 메일 전송은 SMTP 설정을 따르세요.

구현 근거: serve 옵션·브라우저 URL, 작업자 관리·종료, 저장소 보호 잠금, 실행 중 명령 거부, 준비 상태 확인, Host 정책, 환경 설정, 작업자, 운영 구성, Compose 구성.

계속 실행할 방법 선택​

주소 이해하기​

신뢰하는 LAN의 다른 기기에서 시험하기​

Linux/macOS: 로컬 앱을 백그라운드에서 실행​

실제 프로세스 종료​

Windows: 앱을 별도 창에서 유지​

관리 명령 실행​

작업자를 직접 실행하기(external 모드)​

설치된 운영 서비스 관리​