설치와 첫 로그인
내 컴퓨터에 dtxWiki를 설치하거나 관리자와 함께 팀 서버를 준비해 시작합니다. 서버가 준비되면 각 사용자는 코딩을 하거나 자신의 컴퓨터에 Python을 설치할 필요 없이 브라우저로 워크스페이스를 읽고 작성할 수 있습니다.
이 0.1 계열 설명서의 설치 예시는 현재 공개된 v0.1.2 패키지를 사용합니다. 앱과 백그라운드 작업자는 같은 버전으로 실행하세요.
나에게 맞는 경로 선택
| 상황 | 시작 방법 | 설치 담당 |
|---|---|---|
| 관리자가 팀 서버를 준비함 | 웹 주소와 계정을 받아 로그인 | 서버 관리자 |
| 내 컴퓨터에서 혼자 체험하고 싶음 | 아래 로컬 설치 사용 | 나 또는 기술 지원 담당자 |
| 여러 사람이 같은 자료를 사용해야 함 | 팀 서버 설치 진행 | 서버를 관리할 수 있는 담당자 |
워크스페이스는 자체 멤버와 설정을 가진 지식 공간입니다. 계정은 로그인할 때 사용하는 사용자 정보입니다. 조직의 서버에 계정을 만들었다고 모든 워크스페이스에 자동으로 참여하지는 않습니다.
팀 서버에 참여하기
- 관리자에게 정확한 웹 주소를 받습니다. 예:
https://wiki.example.com. - 브라우저에서 주소를 열고 이메일과 비밀번호로 로그인합니다. 별도의 사용자 이름은 없습니다. 임시 비밀번호를 받았다면 계정 → 비밀번호에서 바꿉니다.
- 워크스페이스 전환기에서 사용할 공간을 선택합니다. 개인 워크스페이스와 팀의 공유 워크스페이스는 별개입니다.
- 공유 공간이 보이지 않으면 해당 소유자에게 정확한 로그인 이메일을 알려주고 추가를 요청합니다. 계정과 워크스페이스 접근을 참고하세요.
회원가입을 사용할 수 없더라도 오류가 아닐 수 있습니다. 팀 서버는 공개 가입이 기본적으로 닫혀 있습니다. 서버 관리자에게 계정을 요청하세요. AI 앱을 연결하기 전에도 라이브러리·컨텍스트·검색을 사용할 수 있습니다.
시작 준비 완료 기준: 대시보드가 열리고, 현재 워크스페이스 이름이 사용하려는 공간과 일치합니다.
내 컴퓨터에서 체험하기
1. 설치 도구 준비
Windows에서는 PowerShell, macOS/Linux에서는 터미널을 엽니다. 앱과 의존성을 받으려면 인터넷 연결이 필요하며 일상적인 작업은 브라우저에서 진행합니다.
앱은 Python 3.12 이상을 사용합니다. 설치 도구가 없다면 uv를 사용하세요. 공식 설치 안내에서 자신의 운영체제에 맞는 방법을 선택합니다. uv가 Python 3.12를 받을 수 있으므로 이 경로는 Python을 따로 설치하지 않아도 됩니다. uv 설치 후 터미널을 닫았다 다시 열고 확인합니다.
uv --version
예상 결과: uv 버전이 표시됩니다. 명령을 찾을 수 없다면 도구의 PATH 설정을 마치고 새 터미널을 여세요. Python 패키지 설치에는 Node.js가 필요하지 않습니다. 도구 준비가 낯설다면 기술 지원 담당자에게 부탁하세요.
2. 패키지 설치
같은 버전의 패키지가 PyPI에 공개되어 있습니다. 다음 uv 명령은 PowerShell과 macOS/Linux 터미널에서 모두 사용할 수 있습니다.
uv tool install --python 3.12 "dtxwiki==0.1.2"
dtxwiki --version
예상 결과: 설치가 완료되고 버전 명령이 dtxwiki 0.1.2를 표시합니다. uv가 도구 디렉터리가 PATH에 없다고 안내하면 uv tool update-shell을 실행한 뒤 터미널을 닫았다 다시 열고 버전을 확인하세요. uv 도구 안내를 참고하세요.
이미 pipx를 사용한다면 pipx로 설치
같은 명령 이름이 충돌하지 않도록 설치 방식은 하나만 선택하세요. pipx는 설치된 Python 3.12+ 실행 파일이 필요합니다. 설치와 PATH 설정은 pipx 공식 저장소를 확인하세요.
Linux/macOS에서 python3.12 명령을 사용할 수 있다면:
python3.12 --version
pipx install --python python3.12 "dtxwiki==0.1.2"
dtxwiki --version
Windows PowerShell에서 Python 3.12와 py 실행기를 설치했다면:
py -3.12 --version
pipx install --python (py -3.12 -c "import sys; print(sys.executable)") "dtxwiki==0.1.2"
dtxwiki --version
PowerShell의 괄호 안 명령은 실제 Python 3.12 실행 파일 경로를 전달합니다. 필요한 명령을 찾을 수 없다면 먼저 도구를 설치하거나 위 uv 경로를 사용하세요. pipx가 앱 디렉터리가 PATH에 없다고 안내하면 pipx ensurepath를 실행하고 터미널을 다시 엽니다.
공개 Python 패키지에는 웹 화면이 포함됩니다. 이 설치 경로에는 Node.js가 필요하지 않습니다.
3. 앱 실행과 브라우저 접속
dtxwiki
앱이 로컬 DB를 준비하고 프로그램을 실행한 뒤 **http://127.0.0.1:21080/**을 열려고 시도합니다. 브라우저가 자동으로 열리지 않으면 직접 주소를 입력하세요. 터미널을 계속 실행 상태로 둡니다. 서버로 동작하므로 중지하기 전까지 명령 입력 상태로 돌아오지 않습니다. 브라우저를 자동으로 열지 않으려면 dtxwiki serve --no-open을 사용하며, 서버는 계속 터미널에서 실행됩니다.
예상 결과: 로그인 화면이 열립니다. 기본 계정과 비밀번호는 없습니다. 프로그램 실행만으로 계정이나 서버 관리자 권한을 만들지 않습니다.
4. 내 계정 만들기
- 로그인 화면에서 가입을 선택합니다.
- 이메일, 선택 사항인 표시 이름, 8자 이상 비밀번호를 입력합니다. 이메일이 로그인 ID이고 표시 이름은 앱에서 보여주는 이름입니다.
- 계속 로그인해 둘 브라우저에서만 이 브라우저에서 로그인 유지를 선택합니다.
- 가입하기를 누르고 대시보드가 열릴 때까지 기다립니다.
예상 결과: 로그인되며 비공개 Personal Workspace의 소유자가 됩니다. SMTP는 선택 사항이므로 메일 인증 없이도 가입하고 위키를 사용할 수 있습니다. 이메일 확인, 메일 복구 또는 지원하는 이메일 알림이 필요할 때 메일 설정을 추가하세요.
5. 서버 관리자 권한 부여
로컬 설치를 운영하는 사람이 진행하는 단계입니다. 워크스페이스 소유자라는 이유만으로 서버 설정을 관리할 수는 없습니다.
앱을 실행한 상태에서 두 번째 터미널을 열고 같은 OS 사용자, 같은 DTXWIKI_* 환경설정을 사용하세요. you@example.com을 가입한 이메일로 바꿉니다.
dtxwiki admin grant --email you@example.com
dtxwiki admin list
예상 결과: 권한 부여가 성공하고 목록에 내 이메일이 나타납니다. 브라우저를 새로고침하면 설정 → 배포를 확인할 수 있습니다. 서버 관리자는 시스템 설정을 관리하며 자료 접근은 계속 워크스페이스 멤버십을 따릅니다.
사용자가 없다는 오류가 나오면 정확한 이메일과 설정한 자료·DB 경로를 확인하세요. 계정이 먼저 존재해야 합니다. 오류를 피하려고 두 번째 빈 설치를 만들지 마세요.
systemd 운영 설치는 초기 관리자 계정과 권한을 자동 구성합니다. Docker는 계정을 만들고 권한을 명시적으로 부여합니다. 일상적인 위키 작업을 하는 팀원에게 서버 관리자 권한은 필요하지 않습니다.
6. 작업자 실행
기본 DB는 OS 사용자의 .dtxwiki/data/dtxwiki.sqlite에 있습니다. Linux/macOS는 ~/.dtxwiki, Windows PowerShell은 $env:USERPROFILE\.dtxwiki입니다. 파일과 로컬 세션 키를 포함한 전체 디렉터리를 보관하세요. 로컬 주소는 현재 컴퓨터를 뜻합니다. 동료의 노트북에서 127.0.0.1을 열면 내 컴퓨터가 아닌 동료의 노트북에 접속합니다.
관리자 권한을 부여한 뒤 두 번째 터미널에서 다음을 실행해 Library 자료 추출과 다른 백그라운드 작업을 처리합니다.
dtxwiki-worker run
작업자는 중지할 때까지 계속 작업을 확인하며 유휴 상태도 정상입니다. 앱이 작업자를 자동 실행하지는 않습니다. 앱과 작업자는 같은 버전, OS 사용자, 자료 디렉터리와 DB를 사용해야 합니다. 새 터미널이 첫 터미널의 환경변수를 복사하지는 않으므로 변경한 설정은 다시 적용하세요. 임의의 .env 파일을 만드는 것만으로 로컬 명령을 설정할 수는 없습니다. 작업자가 없으면 가져오기가 대기 상태로 남을 수 있습니다. systemd와 Docker 배포는 작업자를 자동 실행합니다.
예상 결과: 앱에 계속 접속할 수 있고 작업자도 시작 오류 없이 실행 중입니다. 첫 워크스페이스에서 작은 Library 파일을 가져와 확인하세요.
종료하고 다시 사용하기
각 터미널에서 Ctrl+C를 눌러 앱과 작업자를 중지합니다. 자료는 유지됩니다. 다시 같은 두 명령을 실행하고 기존 계정으로 로그인하면 되며 재가입할 필요는 없습니다. 백업·유지보수 전에 둘 다 중지하고 중요한 작업을 보관하기 전에 백업을 준비하세요. 다른 OS 사용자나 DTXWIKI_DATA_DIR를 사용하면 다른 자료를 선택합니다.
LAN 접속, 백그라운드 실행 또는 자동 시작은 접속과 백그라운드 실행을 따르세요.
브라우저가 접속하지 못하면 문제 해결을 참고하세요.
선택 사항: npm으로 실행하기
이미 Node.js를 사용한다면 공개된 npm 실행기로 시작할 수도 있습니다. Node.js 22 이상, uv 또는 pipx가 필요합니다. pipx를 사용하면 Python 3.12 이상이 설치되어 있어야 하며, uv는 필요한 경우 Python 3.12를 받아 사용할 수 있습니다.
npx @dtxsuite/dtxwiki@0.1.2
npm 패키지는 같은 버전의 PyPI dtxwiki==0.1.2를 실행하는 도구이며 별도 애플리케이션이 아닙니다. 처음 실행하면 Python 애플리케이션과 의존성을 내려받습니다. 위에서 설명한 같은 로컬 웹 주소와 기본 ~/.dtxwiki 자료 디렉터리를 사용합니다.
필요하면 Node.js 공식 다운로드에서 설치하고 node --version이 22 이상인지 확인하세요. npm의 다운로드 확인이 나오면 동의합니다. 같은 가입 절차를 따르고 두 번째 터미널에서 관리자 권한을 부여하세요.
npx @dtxsuite/dtxwiki@0.1.2 admin grant --email you@example.com
npx @dtxsuite/dtxwiki@0.1.2 admin list
권한 부여 후 브라우저를 새로고침합니다. 다음 작업자 명령은 PowerShell과 macOS/Linux 터미널에서 모두 사용할 수 있습니다.
Library 추출과 대기 작업을 처리하려면 같은 자료·데이터베이스 설정으로 두 번째 터미널을 엽니다. Python 실행 도구에 맞는 명령을 선택하세요.
# uv 사용
uvx --python 3.12 --from "dtxwiki==0.1.2" dtxwiki-worker run
# pipx 사용
pipx run --spec "dtxwiki==0.1.2" dtxwiki-worker run
npx로 실행해도 dtxwiki-worker가 PATH에 설치되지는 않습니다. 백업·유지보수 전에는 두 터미널의 프로세스를 모두 중지하세요. 실행기 명령을 PATH에 두려면 npm install --global @dtxsuite/dtxwiki@0.1.2로 설치한 뒤 dtxwiki를 사용할 수 있습니다. Python 패키지와 전역 npm 실행기가 같은 명령 이름을 사용하므로 한 설치 방식을 선택하세요.
이미 있는 데이터베이스를 재사용한다면 유지보수 전 리비전 식별자 확인을 따르세요. 처음 설치할 때는 해당 변환이 필요하지 않습니다.
선택 사항: v0.1.2 소스로 직접 빌드하기
프로그램을 직접 빌드하려는 사용자를 위한 경로입니다. Linux 또는 WSL2의 Bash, Git, GNU Make, Node.js 22.18 이상, npm, Python 3.12, pipx가 필요합니다. 기존 디렉터리를 바꾸지 않도록 새 디렉터리에 받습니다.
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
make build-wheel
pipx install --python python3.12 dist/dtxwiki-0.1.2-py3-none-any.whl
dtxwiki
make build-wheel은 웹 화면까지 패키지에 포함합니다. 일반적인 Python 패키지 빌드 명령만 사용하면 웹 화면이 빠질 수 있습니다.
팀과 함께 사용하기
다른 컴퓨터에서 접속해야 한다면 팀 서버 설치를 사용하세요. HTTPS, 지속되는 저장소, 백그라운드 작업 처리를 준비합니다. 로컬 체험의 주소를 0.0.0.0으로 바꾸는 것만으로 이러한 구성이 갖춰지지는 않습니다.
로컬과 운영 설치는 기본 자료 위치가 다릅니다. 공유 서버를 구성할 때 로컬 계정과 파일이 자동 이전되지는 않습니다.
v0.1.2에는 데스크톱 설치 파일이나 공개된 컨테이너 이미지가 포함되지 않습니다. Docker에서는 v0.1.2 릴리스 태그로 이미지를 직접 빌드합니다.
AI 연결과 SMTP는 선택 사항입니다. 먼저 브라우저 사용에 익숙해진 뒤, 저장한 지식을 AI가 참고하도록 하고 싶을 때 AI 앱 연결을 진행하세요.