선택 사항: 이메일 발송(SMTP)
SMTP 설정은 선택 사항입니다. 기본 로컬 설치에서는 메일 서버 없이도 회원가입·로그인·문서 작성·정리·검색을 할 수 있습니다. 기본값은 DTXWIKI_MAIL_PROVIDER=none입니다. http://127.0.0.1:21080/을 사용하는 로컬 이용에는 Gmail이나 앱 비밀번호가 필요하지 않습니다. 공유 서버의 회원가입 정책은 별도 설정입니다.
계정 이메일 확인과 이메일 비밀번호 복구가 필요할 때 SMTP를 설정합니다. 이 안내는 dtxWiki의 실행 설정을 관리하는 서버 운영자를 위한 것입니다. 워크스페이스 소유자 역할만으로는 이 설정을 바꿀 수 없습니다.
메일을 활성화하면 달라지는 점
| 설정 | 계정 동작 |
|---|---|
| 메일 미설정, 기본 로컬 HTTP | 이메일 확인과 이메일 비밀번호 복구를 사용할 수 없습니다. 멤버와 접근 권한의 계정·운영자 절차를 따릅니다. |
| 메일 미설정, 공식 HTTPS 공개 URL 설정 | 운영자가 관리자 지원 방식의 일회용 복구 링크를 제공할 수 있습니다. SMTP는 계속 선택 사항입니다. |
| SMTP와 공식 HTTPS 공개 URL 설정 | 로그인한 사용자가 이메일 확인을 요청할 수 있습니다. 확인된 주소를 가진 대상 활성 계정은 비밀번호 재설정 메일을 요청할 수 있습니다. |
워크스페이스 멤버 추가는 별도 동작이며 초대 메일 발송을 보장하지 않습니다. SMTP를 켜도 Google 로그인이나 AI 앱의 MCP 연결이 활성화되지는 않습니다.
계정 메일 요청은 outbox, 즉 발송 대기열에 저장됩니다. 작업자가 설정된 SMTP 제공업체로 보냅니다. Gmail에는 받는 사람 주소와 일회용 계정 링크를 포함한 메시지가 전달됩니다. 개인정보와 안전한 공유를 함께 확인하세요.
서버를 먼저 준비하기
- 서버의 실제 HTTPS 주소에 이미 접속할 수 있는지 확인합니다.
DTXWIKI_PUBLIC_BASE_URL에는https://wiki.example.com과 같은 실제 주소를 지정합니다. 이 값만 바꾼다고 도메인·인증서·리버스 프록시가 만들어지지는 않습니다. 먼저 서버 배포를 진행하세요. - 앱과 작업자가 같은 설치·데이터베이스·데이터 디렉터리·세션 비밀값을 사용해야 대기 중인 메일을 읽을 수 있습니다. 다른 설치의 작업자가 대신 처리할 수는 없습니다.
- 직접 관리하는 발송 계정과 받은편지함을 확인할 수 있는 계정을 정합니다. 아래 예시 주소는 실제 주소로 바꾸세요.
설정 → 배포 → 계정 및 복구에서는 제공업체·발신자·공식 URL·비밀번호를 숨긴 자격 증명 상태·대기열 개수·마지막 관측 발송을 확인합니다. 운영자용 명령어를 보여주는 화면이며 SMTP 비밀번호 편집기나 테스트 메일 버튼은 아닙니다. 프로세스 환경 변수나 운영 설정을 바꾼 뒤 앱과 작업자를 모두 다시 시작하면 적용됩니다.
Gmail 예제
기본 예제는 smtp.gmail.com의 587 포트와 STARTTLS를 사용합니다. 다른 선택은 465 포트와 SSL/TLS입니다. dtxWiki에서는 두 보안 연결 방식 중 정확히 하나만 켜야 합니다. 호스트와 포트는 Google의 SMTP 프로토콜 안내를 참고하세요.
| 설정 | 값 |
|---|---|
DTXWIKI_MAIL_PROVIDER | smtp |
DTXWIKI_MAIL_FROM_ADDRESS | your-gmail-address@gmail.com과 같은 전체 Gmail 주소 |
DTXWIKI_SMTP_HOST | smtp.gmail.com |
DTXWIKI_SMTP_USERNAME | 발신자와 같은 전체 Gmail 주소 |
DTXWIKI_SMTP_PASSWORD | 이 앱에서 사용할 Google 앱 비밀번호 |
DTXWIKI_PUBLIC_BASE_URL | 이미 접속 가능한 dtxWiki HTTPS 주소 |
| 보안 연결 | 포트 | DTXWIKI_SMTP_STARTTLS | DTXWIKI_SMTP_USE_SSL |
|---|---|---|---|
| STARTTLS | 587 | true | false |
| 연결 시작부터 SSL/TLS | 465 | false | true |
앱 비밀번호 만들기
- 메일을 보낼 Google 계정에 로그인하고 2단계 인증을 켭니다.
- Google 계정 → 앱 비밀번호를 엽니다. 앱 이름을
dtxWiki SMTP로 지정하고 비밀번호를 만듭니다. - 승인된 비밀정보 저장소에 보관합니다. SMTP에는 Google 일반 계정 비밀번호 대신 이 값을 사용합니다.
직장·학교 계정, 보안 키만 사용하는 2단계 인증, 고급 보호 프로그램 등에서는 앱 비밀번호를 사용할 수 없을 수 있습니다. 정책을 확인하거나 다른 허용된 SMTP 서비스를 선택하고 계정 보호 기능은 끄지 마세요. dtxWiki는 Gmail OAuth가 아닌 사용자 이름·비밀번호 SMTP 인증을 사용합니다. Google 일반 비밀번호를 바꾸면 기존 앱 비밀번호가 폐기되므로 비밀값을 교체하고 두 프로세스를 다시 시작합니다. 사용하지 않는 앱 비밀번호도 폐기하세요. Google 앱 비밀번호 안내, 고급 보호 프로그램의 제한.
systemd: 운영 설정 영구 저장
다음 명령어는 기존 운영 설치의 접근이 제한된 /etc/dtxwiki/dtxwiki.env를 사용합니다. 서버의 Bash에서 실행하세요. HTTPS 주소와 발송 주소를 먼저 바꿉니다. 보안 연결 설정을 바꾸는 동안 제공업체를 none으로 두고 마지막에 smtp를 선택하여 중간 설정도 유효하게 유지합니다.
sudo dtxwiki config set DTXWIKI_MAIL_PROVIDER=none
sudo dtxwiki config set DTXWIKI_PUBLIC_BASE_URL=https://wiki.example.com
sudo dtxwiki config set DTXWIKI_MAIL_FROM_ADDRESS=your-gmail-address@gmail.com
sudo dtxwiki config set DTXWIKI_SMTP_HOST=smtp.gmail.com
sudo dtxwiki config set DTXWIKI_SMTP_PORT=587
sudo dtxwiki config set DTXWIKI_SMTP_STARTTLS=true
sudo dtxwiki config set DTXWIKI_SMTP_USE_SSL=false
sudo dtxwiki config set DTXWIKI_SMTP_USERNAME=your-gmail-address@gmail.com
IFS= read -r -s -p 'Gmail app password: ' gmail_app_password
printf '\n'
sudo dtxwiki config set "DTXWIKI_SMTP_PASSWORD=$gmail_app_password" --i-understand
unset gmail_app_password
sudo dtxwiki config set DTXWIKI_MAIL_PROVIDER=smtp
sudo systemctl restart dtxwiki dtxwiki-worker
숨겨진 입력으로 비밀번호 원문을 셸 명령 기록에 남기지 않습니다. 기존 CLI는 입력값을 잠시 프로세스 인자로 전달하므로 운영자가 관리하는 터미널에서 명령 추적을 끈 상태로 사용하세요. 비밀값을 공유 예제·이슈·스크린샷에 붙여넣지 않습니다. 비밀번호 변경에는 --i-understand가 필요하며 config show는 저장된 값을 숨깁니다.
설정 파일에 쓰는 것만으로 실행 중인 프로세스가 바뀌지는 않습니다. 둘 다 다시 시작한 후 다음을 확인합니다.
sudo dtxwiki config show
sudo systemctl status dtxwiki dtxwiki-worker --no-pager
계정 및 복구를 다시 엽니다. 설정 완료 상태는 구성값을 확인한 것이며 Gmail이 메시지를 받았거나 수신자가 메일을 받았음을 뜻하지 않습니다. 아래 수신 확인까지 진행하세요.
465 포트를 사용하려면 제공업체가 none일 때 DTXWIKI_SMTP_PORT=465, DTXWIKI_SMTP_STARTTLS=false, DTXWIKI_SMTP_USE_SSL=true를 설정합니다. 이후 smtp를 선택하고 두 서비스를 모두 다시 시작합니다.
직접 실행: 터미널 환경 변수
이미 동작하는 HTTPS 접속 경로가 있을 때만 이 예제를 사용하세요. 현재 터미널에 적용되며 운영 설정 파일에 영구 저장하지는 않습니다. 기존 앱과 작업자를 중지한 뒤 새 설정으로 시작합니다. 기존 데이터 디렉터리와 세션 비밀값 설정을 유지하세요.
설치 방식에 맞는 명령을 고릅니다. 아래 환경 변수 예제의 마지막 줄은 Python 도구 설치용 앱 명령입니다. npm만 사용하는 경우 해당 행의 앱 명령으로 바꾸고 두 번째 터미널에서도 같은 행의 작업자 명령을 사용하세요. 서버를 계속 실행하기를 함께 확인합니다.
| 설치 방식 | 앱 명령 | 두 번째 터미널의 작업자 명령 |
|---|---|---|
| pipx 또는 uv로 Python 도구 설치 | dtxwiki --no-open | dtxwiki-worker run |
| npm/npx와 uv | npx @dtxsuite/dtxwiki@0.1.2 serve --no-open | uvx --python 3.12 --from dtxwiki==0.1.2 dtxwiki-worker run |
| npm/npx와 pipx | npx @dtxsuite/dtxwiki@0.1.2 serve --no-open | pipx run --spec dtxwiki==0.1.2 dtxwiki-worker run |
Linux 또는 macOS의 Bash
export DTXWIKI_PUBLIC_BASE_URL=https://wiki.example.com
export DTXWIKI_MAIL_PROVIDER=smtp
export DTXWIKI_MAIL_FROM_ADDRESS=your-gmail-address@gmail.com
export DTXWIKI_SMTP_HOST=smtp.gmail.com
export DTXWIKI_SMTP_PORT=587
export DTXWIKI_SMTP_STARTTLS=true
export DTXWIKI_SMTP_USE_SSL=false
export DTXWIKI_SMTP_USERNAME=your-gmail-address@gmail.com
IFS= read -r -s -p 'Gmail app password: ' gmail_app_password
printf '\n'
export DTXWIKI_SMTP_PASSWORD="$gmail_app_password"
unset gmail_app_password
dtxwiki --no-open
HTTPS 주소로 서버에 접속합니다. 두 번째 터미널에서 같은 환경 변수와 숨겨진 비밀번호 입력을 반복하고 데이터 디렉터리·세션 비밀값도 같게 설정합니다. 앱이 준비되면 마지막 dtxwiki --no-open 줄 대신 다음을 실행하세요.
dtxwiki-worker run
새 터미널은 첫 터미널의 export를 이어받지 않습니다. 각 터미널에서 Ctrl+C로 두 프로세스를 중지합니다. 사용 후 unset DTXWIKI_SMTP_PASSWORD로 비밀값을 지우세요. 변수를 지워도 이미 실행 중인 프로세스의 설정은 바뀌지 않습니다.
Windows에서 직접 실행할 때 사용하는 PowerShell
$env:DTXWIKI_PUBLIC_BASE_URL = "https://wiki.example.com"
$env:DTXWIKI_MAIL_PROVIDER = "smtp"
$env:DTXWIKI_MAIL_FROM_ADDRESS = "your-gmail-address@gmail.com"
$env:DTXWIKI_SMTP_HOST = "smtp.gmail.com"
$env:DTXWIKI_SMTP_PORT = "587"
$env:DTXWIKI_SMTP_STARTTLS = "true"
$env:DTXWIKI_SMTP_USE_SSL = "false"
$env:DTXWIKI_SMTP_USERNAME = "your-gmail-address@gmail.com"
$gmailAppPassword = Read-Host "Gmail app password" -AsSecureString
$env:DTXWIKI_SMTP_PASSWORD = [System.Net.NetworkCredential]::new("", $gmailAppPassword).Password
Remove-Variable gmailAppPassword
dtxwiki --no-open
작업자는 두 번째 PowerShell 창에서 같은 환경 변수와 비밀번호 입력을 준비하고 마지막 줄 대신 dtxwiki-worker run을 실행합니다. 기존 데이터 디렉터리와 세션 비밀값도 같아야 합니다. 직접 실행 예제이며 공식 운영 호스팅 대상은 Linux입니다. 두 프로세스를 중지한 뒤 Remove-Item Env:DTXWIKI_SMTP_PASSWORD로 비밀값을 지웁니다.
Docker Compose
기존 운영 Compose 설치에서는 Gmail 설정 표의 값을 비공개 infra/prod/.env에 넣습니다. 비밀번호는 접근이 제한된 편집기나 승인된 비밀정보 관리 절차에서 설정하세요. DTXWIKI_DOMAIN에는 동작 중인 HTTPS 도메인을 유지합니다. Compose는 이 값에서 공개 URL을 만들며 배포된 파일은 앱과 작업자 모두에게 메일 설정을 전달합니다.
같은 Compose 디렉터리에서 변경한 환경 변수를 적용합니다.
docker compose up -d --force-recreate app worker
단순한 컨테이너 재시작으로는 Compose 환경 변수 변경이 적용되지 않습니다. .env를 공유하거나 docker compose config 출력을 공개 문제 보고에 첨부하지 마세요. 해석된 비밀값이 포함될 수 있습니다.
실제 수신 확인
직접 관리하는 서버와 본인의 계정으로 확인하세요. 설정 예제는 해당 설치에서 외부 Gmail 발송이 검증되었다는 뜻이 아닙니다.
- 받은편지함을 확인할 수 있는 활성 계정으로 로그인합니다. 계정을 열고 주소가 확인되지 않았다면 이메일 확인을 선택합니다.
- 받은편지함과 스팸함에서 최신 확인 메일을 엽니다. 링크가 실제 dtxWiki HTTPS 도메인으로 연결되는지 확인하고 절차를 마칩니다. 계정 화면에 이메일 확인됨이 표시되는지 확인하세요.
- 서버 관리자로 계정 및 복구의 마지막 관측 발송과 대기·실패 개수를 확인합니다. 제공업체 수락 상태뿐 아니라 받은편지함 도착도 확인해야 합니다.
- 비밀번호 복구도 확인한다면 확인된 계정으로 **비밀번호를 잊으셨나요?**를 사용하고 최신 링크의 절차를 마칩니다. 실제 계정이 바뀌는 작업입니다. 공개 셀프서비스 복구는 브라우저 세션과 API·MCP·OAuth 자격 증명을 폐기하므로 해당 계정의 도구를 다시 연결하세요.
공개 재설정 응답은 주소의 등록 여부나 대상 여부를 드러내지 않습니다. 접수 메시지만으로 발송을 확인할 수는 없습니다. 운영자 지원 복구와 전달 방식은 멤버와 접근 권한을 확인하세요.
문제 해결
| 보이는 현상 | 다음 확인 |
|---|---|
| 이메일 확인 동작이 없음 | SMTP와 공식 HTTPS URL을 설정해야 합니다. 이미 확인된 주소는 요청이 필요하지 않습니다. |
| Google에 앱 비밀번호 옵션이 없음 | 2단계 인증·계정 제한을 확인하고 필요하면 다른 허용된 제공업체를 선택합니다. |
| Gmail 인증이 거부됨 | 전체 발신 주소와 앱 비밀번호를 사용합니다. Google 일반 비밀번호 변경 시 이전 앱 비밀번호가 폐기됩니다. |
| SMTP 보안 연결 오류 | 587 / STARTTLS true / SSL false, 또는 465 / STARTTLS false / SSL true를 고릅니다. |
| 메일이 계속 대기 상태임 | 앱과 같은 데이터베이스·데이터 디렉터리·비밀값·SMTP 환경 변수로 작업자를 실행합니다. 설정 변경 후 둘 다 다시 시작합니다. |
| 링크가 다른 사이트나 HTTP로 연결됨 | DTXWIKI_PUBLIC_BASE_URL을 수정하고 두 프로세스를 다시 시작한 뒤 새 메일을 요청합니다. |
| 발송 실패 또는 받은편지함에 메일이 없음 | 외부 SMTP 포트 연결, 자격 증명, 제공업체 제한, 수신 주소, 스팸 분류를 확인합니다. 원인을 바로잡은 뒤 최신 메시지를 사용합니다. |
| 재설정 요청은 접수됐지만 메일이 없음 | 대상 활성 계정의 주소가 확인되어야 합니다. 운영자에게 복구 상태 확인을 요청합니다. |
메일을 끄려면 두 프로세스의 시작 설정에 DTXWIKI_MAIL_PROVIDER=none을 지정하고 둘 다 다시 시작합니다. 사용하지 않는 Google 앱 비밀번호도 폐기하세요. 메일 없이도 사용할 수 있으며, 관리자 지원 링크에는 공식 HTTPS URL이 계속 필요합니다.
버전 근거: 메일 설정, SMTP와 발송 대기열, 계정 복구, 설정 CLI, 작업자, Compose 환경 변수.