접속과 백그라운드 실행
설치와 첫 로그인이 정상 동작한 뒤 사용하는 안내입니다. 앱을 실행하는 담당자를 위한 명령이며, 다른 사용자는 서버 주소와 자신의 계정만 있으면 됩니다.
계속 실행할 방법 선택
| 방법 | 동작 | 재부팅·장애 이후 |
|---|---|---|
터미널의 dtxwiki | 로컬 앱 실행과 브라우저 열기 | 직접 다시 시작 |
dtxwiki serve --no-open | 브라우저를 열지 않고 앱 실행 | 직접 다시 시작. 여전히 터미널에서 실행 |
nohup 또는 별도 Windows 창 | 처음 터미널과 별개로 앱 실행 유지 | 부팅 자동 시작·장애 후 재시작 기능 없음 |
| 설치된 systemd·Docker 서비스 | 앱과 작업자를 지속 운영 | 구성한 서비스 재시작 정책 사용 |
다른 사람이 접속하려면 컴퓨터가 계속 켜져 있어야 합니다. 지속적인 공동 사용에는 개인 터미널 대신 공유 서버 구성을 사용하세요.
주소 이해하기
| 설정 또는 주소 | 의미 |
|---|---|
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로 중지합니다. 같은 포트의 서버를 하나 더 시작하지 마세요. - 서버 컴퓨터의 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.1.2를 사용합니다. 위 URL이 해당 IP를 자동 허용하므로 DTXWIKI_ALLOWED_HOSTS에 같은 IP를 중복 입력할 필요는 없습니다.
- 두 번째 터미널에 같은 변경 환경을 적용하고 설치 안내의 같은 버전 작업자 명령을 실행합니다.
- 다른 기기에서 **
http://192.168.1.20:21080/**을 열고 로그인합니다. 서버 방화벽에서 사용할 LAN 기기에 TCP 21080을 허용하세요. 가상 머신·WSL은 추가 포트 전달이 필요할 수 있습니다. Microsoft의 WSL 네트워크 안내를 확인하세요.
예상 결과: 두 기기가 같은 서버와 계정에 접속합니다. 공유 공간 접근은 여전히 멤버십을 따르며 호스트 허용이 자료 접근 권한을 주지는 않습니다. 기본 로컬 모드는 가입도 허용하므로 이 서버에 접속할 수 있는 사람이 계정을 만들 수 있습니다.
터미널의 환경변수는 해당 프로세스와 자식 프로세스에 적용됩니다. 새 터미널은 첫 터미널에서 변경한 값을 상속하지 않습니다. DTXWIKI_DATA_DIR, DB와 다른 설정을 앱·작업자·관리 명령에 동일하게 적용하세요. 임의의 .env 파일을 로컬 CLI가 자동으로 읽지는 않습니다.
기본 로컬 사용으로 돌아가려면 두 프로세스를 중지하고 각 터미널에서 예시 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.1.2 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는 로그 보기만 종료하며 백그라운드 앱을 종료하지 않습니다. 로그 파일은 명령을 실행한 디렉터리에 생깁니다.
작업자도 필요합니다. 두 번째 터미널에서 계속 실행하거나, uv/pipx로 설치한 패키지는 다음처럼 실행할 수 있습니다.
nohup dtxwiki-worker run > dtxwiki-worker.log 2>&1 < /dev/null &
npm/uv 실행기는 nohup uvx --python 3.12 --from 'dtxwiki==0.1.2' dtxwiki-worker run > dtxwiki-worker.log 2>&1 < /dev/null &를 사용합니다. pipx 실행기는 nohup 뒤에 pipx run --spec 'dtxwiki==0.1.2' dtxwiki-worker run과 같은 로그 리다이렉션을 사용합니다.
실제 프로세스 종료
lsof가 설치되어 있다면 앱 포트에서 수신 중인 프로세스를 확인합니다.
lsof -nP -iTCP:21080 -sTCP:LISTEN
SERVER_PID를 실제 수신 프로세스의 PID로 바꾸어 kill -TERM SERVER_PID를 실행합니다. npm 실행기의 PID만 종료하면 Python 자식 서버가 남을 수 있습니다. 작업자는 ps -ax -o pid,command에서 명령과 설치 경로로 실제 dtxwiki-worker run 프로세스를 확인하고 kill -TERM WORKER_PID를 실행합니다. 대상을 확인한 뒤 각각 중지하고 유지보수 전에는 둘 다 종료하세요.
서버 수신과 작업자가 종료되었는지 확인합니다. nohup은 부팅 시 자동 시작이나 장애 후 자동 재시작을 구성하지 않습니다.
Windows: 앱과 작업자를 별도 창에서 유지
터미널에서 정상 실행을 확인한 뒤 기존 프로세스를 중지합니다. 같은 환경의 PowerShell에서 앱 창을 엽니다.
# uv/pipx 설치
Start-Process dtxwiki -ArgumentList "serve --no-open"
npm:
Start-Process npx.cmd -ArgumentList "--yes @dtxsuite/dtxwiki@0.1.2 serve --no-open"
새 프로세스는 현재 PowerShell의 환경을 상속합니다. LAN 접속이 필요하면 대표 URL을 먼저 설정하고 ArgumentList에 수신 옵션도 넣으세요. 새 창을 보여 두어 시작 오류를 확인합니다.
작업자도 두 번째 창에서 시작합니다.
# uv/pipx 설치
Start-Process dtxwiki-worker -ArgumentList "run"
npm/uv는 Start-Process uvx -ArgumentList "--python 3.12 --from dtxwiki==0.1.2 dtxwiki-worker run"을 사용합니다. pipx는 Start-Process pipx -ArgumentList "run --spec dtxwiki==0.1.2 dtxwiki-worker run"을 사용합니다.
처음 PowerShell을 닫아도 별도 프로세스는 종료되지 않습니다. 각 창에서 Ctrl+C로 중지하세요. 이 창들은 장애 후 재시작이나 부팅 자동 시작을 제공하지 않습니다. Windows 로컬 사용과 Linux 운영 서버 구성은 다른 경로입니다.
설치된 운영 서비스 관리
먼저 공유 서버 설치를 완료해야 합니다. 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를 읽습니다. 설치된 환경 로딩 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
docker compose stop app worker로 쓰기 프로세스를 중지합니다. 저장된 볼륨은 유지하세요. 볼륨 삭제는 종료나 업데이트 절차가 아닙니다.
예상 결과: 앱과 작업자가 실행 중이고 실제 HTTPS 서버 주소의 /health/ready가 성공하며 브라우저에서 로그인해 저장한 페이지를 읽을 수 있습니다. 앱 상태 확인만으로 작업자가 실제 작업을 처리했다고 확인할 수는 없습니다. 실패하면 문제 해결, 메일 전송은 SMTP 설정을 따르세요.
구현 근거: serve 옵션·브라우저 URL, Host 정책, 환경 설정, 작업자, 운영 구성, Compose 구성.