도움말:S3 연구 메모리/설치와 검증 - 편집 역사

S3Admin: S3 연구 메모리 저장소 문서 동기화

2026-07-16T14:32:08Z

S3 연구 메모리 저장소 문서 동기화

← 이전 판		2026년 7월 16일 (목) 23:32 판
168번째 줄:		168번째 줄:
	\| <code><nowiki>COMPOSE_PROFILES</nowiki></code> \|\| 아니요 \|\| <code><nowiki>domain</nowiki></code>을 넣으면 Caddy를 실행. 도메인 스크립트가 추가		\| <code><nowiki>COMPOSE_PROFILES</nowiki></code> \|\| 아니요 \|\| <code><nowiki>domain</nowiki></code>을 넣으면 Caddy를 실행. 도메인 스크립트가 추가
	\|-		\|-
	\| <code><nowiki>S3RM_MAX_OUTPUT_BYTES</nowiki></code> \|\| 아니요 \|\| <code><nowiki>32768</nowiki></code>; 도구 결과 제한 2048~65536바이트. 전체 JSON-RPC 응답은 별도 ~~147456바이트~~ 제한		\| <code><nowiki>S3RM_MAX_OUTPUT_BYTES</nowiki></code> \|\| 아니요 \|\| <code><nowiki>32768</nowiki></code>; 도구 결과 제한 2048~65536바이트. 전체 JSON-RPC 응답은 별도 212992바이트 제한
	\|-		\|-
	\| <code><nowiki>S3RM_SEARCH_SCAN_LIMIT</nowiki></code> \|\| 아니요 \|\| <code><nowiki>200</nowiki></code>; 후보 스캔 제한 20~1000페이지		\| <code><nowiki>S3RM_SEARCH_SCAN_LIMIT</nowiki></code> \|\| 아니요 \|\| <code><nowiki>200</nowiki></code>; 후보 스캔 제한 20~1000페이지

S3Admin: S3 연구 메모리 저장소 문서 동기화

2026-07-16T13:12:14Z

S3 연구 메모리 저장소 문서 동기화

@@ 30번째 줄: / 30번째 줄: @@
 <code><nowiki>docker version</nowiki></code>이 클라이언트 버전만 출력하지 않고 Docker 데몬에도 연결되어야 합니다. 이 확인 전에 도메인 설정 스크립트를 실행하지 마세요. 첫 빌드에서는 이미지와 고정된 PHP·Python 의존성을 내려받으므로 인터넷 연결이 필요합니다.
-일반 운영 경로는 위 HTTPS 도메인 하나입니다. 읽기와 검색은 공개됩니다. <code><nowiki>S3RM_MCP_WRITE_AUTH_MODE=token</nowiki></code>이면 세 변경 도구에 공용 Bearer 토큰이 필요하고, <code><nowiki>open</nowiki></code>이면 인증 없이 사용할 수 있습니다. Caddy는 TLS를 종료하고 <code><nowiki>/mcp</nowiki></code>를 좁은 MCP 서비스로 보냅니다. 나머지 경로는 MediaWiki로 보냅니다. 직접 포트 8080과 8765는 서버 진단용이며 별도 클라이언트 주소가 아닙니다.
+일반 운영 경로는 위 HTTPS 도메인 하나입니다. 읽기와 검색은 공개됩니다. <code><nowiki>S3RM_MCP_WRITE_AUTH_MODE=token</nowiki></code>이면 세 변경 도구에 공용 Bearer 토큰이 필요하고, <code><nowiki>open</nowiki></code>이면 인증 없이 사용할 수 있습니다. <code><nowiki>github</nowiki></code>는 GitHub 로그인을 거쳐 MCP용 access·refresh token을 발급하며 이 모드에서는 MCP 연결 전체가 OAuth 인증 대상입니다. Caddy는 TLS를 종료하고 <code><nowiki>/mcp</nowiki></code>와 OAuth 경로를 MCP 서비스로 보냅니다. 나머지 경로는 MediaWiki로 보냅니다.
 기본값은 <code><nowiki>token</nowiki></code>입니다. 짧은 공개 시험에서만 <code><nowiki>.env</nowiki></code>에 다음 값을 넣고 <code><nowiki>mcp-http</nowiki></code>를 다시 만드세요.
@@ 39번째 줄: / 39번째 줄: @@
 다시 잠그려면 값을 <code><nowiki>token</nowiki></code>으로 바꿉니다. 기존 <code><nowiki>S3RM_MCP_TOKEN_SHA256</nowiki></code>은 지우지 않아도 되며 <code><nowiki>open</nowiki></code> 모드에서는 사용하지 않습니다. 사용자 연결은 [[Help:S3 연구 메모리/Linux 연결|Linux]], [[Help:S3 연구 메모리/macOS 연결|macOS]], [[Help:S3 연구 메모리/Windows 연결|Windows]] 문서에 있고 제품별 제약은 [[Help:S3 연구 메모리/MCP 클라이언트|S3RM3]]에 있습니다.
 === 환경 설정 ===
@@ 113번째 줄: / 136번째 줄: @@
 | <code><nowiki>S3RM_MCP_PUBLIC_URL</nowiki></code> || 예 || 클라이언트 주소 <code><nowiki>https://s3wiki.yonsei.ac.kr/mcp</nowiki></code>
 |-
-| <code><nowiki>S3RM_MCP_TOKEN_SHA256</nowiki></code> || 예 || 쓰기 토큰의 64자리 16진수 SHA-256 해시. 원문은 저장하지 않음
+| <code><nowiki>S3RM_MCP_WRITE_AUTH_MODE</nowiki></code> || 아니요 || <code><nowiki>token</nowiki></code>; <code><nowiki>open</nowiki></code>, <code><nowiki>token</nowiki></code>, <code><nowiki>github</nowiki></code> 중 하나
 |-
 | <code><nowiki>S3RM_MCP_BIND_ADDRESS</nowiki></code> || 아니요 || 도메인 프로필에서는 <code><nowiki>127.0.0.1</nowiki></code>. 공개 진입점은 Caddy

S3Admin: S3 연구 메모리 저장소 문서 게시

2026-07-16T13:03:05Z

S3 연구 메모리 저장소 문서 게시

새 문서

''이 페이지는 저장소 문서에서 자동으로 동기화됩니다. 위키에서 직접 편집하지 마세요.''

한 대의 서버에서 위키와 공용 MCP를 함께 실행합니다. 브라우저는 [https://s3wiki.yonsei.ac.kr/]에 접속하고, 모든 에이전트는 [https://s3wiki.yonsei.ac.kr/mcp]에 연결합니다. 두 주소는 하나의 Semantic MediaWiki를 사용합니다. 클라이언트 PC에는 이 저장소, Docker 권한, MediaWiki 에이전트 비밀번호가 필요하지 않습니다.

데이터베이스, 생성된 위키 설정, 업로드 파일은 Docker 볼륨에 저장합니다. 저장소에는 데이터, 자격 증명, 생성된 <code><nowiki>LocalSettings.php</nowiki></code>를 넣지 않습니다.

=== 준비 사항 ===

* Docker Engine 24 이상과 Docker Compose v2 플러그인 또는 최신 Docker Desktop
* Python 3.11 이상과 <code><nowiki>uv</nowiki></code>
* 메모리 4 GiB 이상, 디스크 여유 공간 8 GiB 이상
* Bash, <code><nowiki>make</nowiki></code>, <code><nowiki>openssl</nowiki></code>
* 백업·복원용 GNU/Linux 호스트: Bash 4 이상, GNU coreutils(<code><nowiki>stat</nowiki></code>, <code><nowiki>sha256sum</nowiki></code>), GNU tar, gzip, 일반 파일 권한 지원
* <code><nowiki>s3wiki.yonsei.ac.kr</nowiki></code>이 서버의 <code><nowiki>165.132.118.220</nowiki></code>으로 연결된 DNS
* 서버까지 들어오는 TCP 80, 443
macOS와 Windows의 Docker Desktop은 화면 확인에 사용할 수 있습니다. 백업·복원 스크립트는 이 Compose 프로젝트를 실행하는 Linux VM이나 Linux Docker 호스트에서 실행하세요. <code><nowiki>uv</nowiki></code>가 없다면 [https://docs.astral.sh/uv/getting-started/installation/ 공식 설치 안내]를 따릅니다.

필수 명령을 확인합니다.

<pre><nowiki>
docker version
docker compose version
make --version
bash --version
sha256sum --version
uv --version
</nowiki></pre>

<code><nowiki>docker version</nowiki></code>이 클라이언트 버전만 출력하지 않고 Docker 데몬에도 연결되어야 합니다. 이 확인 전에 도메인 설정 스크립트를 실행하지 마세요. 첫 빌드에서는 이미지와 고정된 PHP·Python 의존성을 내려받으므로 인터넷 연결이 필요합니다.

일반 운영 경로는 위 HTTPS 도메인 하나입니다. 읽기와 검색은 공개됩니다. <code><nowiki>S3RM_MCP_WRITE_AUTH_MODE=token</nowiki></code>이면 세 변경 도구에 공용 Bearer 토큰이 필요하고, <code><nowiki>open</nowiki></code>이면 인증 없이 사용할 수 있습니다. Caddy는 TLS를 종료하고 <code><nowiki>/mcp</nowiki></code>를 좁은 MCP 서비스로 보냅니다. 나머지 경로는 MediaWiki로 보냅니다. 직접 포트 8080과 8765는 서버 진단용이며 별도 클라이언트 주소가 아닙니다.

기본값은 <code><nowiki>token</nowiki></code>입니다. 짧은 공개 시험에서만 <code><nowiki>.env</nowiki></code>에 다음 값을 넣고 <code><nowiki>mcp-http</nowiki></code>를 다시 만드세요.

<pre><nowiki>
S3RM_MCP_WRITE_AUTH_MODE=open
</nowiki></pre>

다시 잠그려면 값을 <code><nowiki>token</nowiki></code>으로 바꿉니다. 기존 <code><nowiki>S3RM_MCP_TOKEN_SHA256</nowiki></code>은 지우지 않아도 되며 <code><nowiki>open</nowiki></code> 모드에서는 사용하지 않습니다. 사용자 연결은 [[Help:S3 연구 메모리/Linux 연결|Linux]], [[Help:S3 연구 메모리/macOS 연결|macOS]], [[Help:S3 연구 메모리/Windows 연결|Windows]] 문서에 있고 제품별 제약은 [[Help:S3 연구 메모리/MCP 클라이언트|S3RM3]]에 있습니다.

=== 환경 설정 ===

저장소 루트에서 실행합니다.

<pre><nowiki>
cp .env.example .env
chmod 600 .env
</nowiki></pre>

비밀번호의 <code><nowiki>change-me</nowiki></code> 값을 모두 바꿉니다. <code><nowiki>S3RM_MCP_TOKEN_SHA256=change-me-...</nowiki></code>는 다음 단계의 토큰 스크립트가 바꾸므로 그대로 둡니다. 비밀번호마다 새 값을 만드세요.

<pre><nowiki>
openssl rand -base64 36
</nowiki></pre>

==== 공용 MCP 설정 ====

<code><nowiki>.env</nowiki></code>의 비밀번호를 바꾼 뒤 등록된 도메인을 설정합니다.

<pre><nowiki>
./scripts/configure-public-domain.sh s3wiki.yonsei.ac.kr \
--expected-ip 165.132.118.220
</nowiki></pre>

스크립트는 DNS를 확인하고 위키 URL, MCP URL, loopback 바인딩, HTTPS 설정, Compose <code><nowiki>domain</nowiki></code> 프로필을 맞춥니다. 공용 쓰기 토큰은 화면에 출력하지 않습니다. 서버의 mode <code><nowiki>0600</nowiki></code> <code><nowiki>.env</nowiki></code>에는 SHA-256 해시만 저장하고, 원문 토큰과 <code><nowiki>S3RM_MCP_URL</nowiki></code>은 mode <code><nowiki>0600</nowiki></code> <code><nowiki>~/.config/s3-research-memory/client.env</nowiki></code>에 저장합니다. 두 파일의 값이 이미 일치하면 토큰을 바꾸지 않습니다.

모든 클라이언트에 같은 MCP URL을 설정합니다. 검색만 할 때는 토큰이 필요하지 않습니다. 메모를 쓰거나 관계·근거를 추가할 에이전트에만 공용 토큰을 전달합니다. 이 토큰으로는 페이지 삭제나 위키 관리를 할 수 없습니다. 위키 관리자·DB 비밀번호를 토큰으로 재사용하지 마세요.

서버에서 쓰기 연결을 시험할 때는 값을 출력하지 않고 불러옵니다.

<pre><nowiki>
set -a
source "$HOME/.config/s3-research-memory/client.env"
set +a
</nowiki></pre>

원문 토큰은 필요한 사람에게 비공개 채널로 전달합니다. Git, 공개 이슈, 프롬프트, 스크린샷에는 넣지 마세요. 이 파일럿은 토큰 해시 하나만 받으므로 토큰을 바꾸면 모든 쓰기 클라이언트를 함께 갱신해야 합니다. 공개 조회에는 영향이 없습니다.

Compose는 현재 프로젝트 디렉터리 또는 <code><nowiki>--project-directory</nowiki></code>가 가리키는 곳의 <code><nowiki>.env</nowiki></code>를 읽습니다. 자세한 동작은 Docker의 [https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/ 환경 변수 보간 안내]를 참고하세요. <code><nowiki>.env</nowiki></code>는 추적하지 않습니다. <code><nowiki>docker compose config</nowiki></code>는 비밀번호와 토큰 해시를 출력하므로 일반 확인에는 <code><nowiki>docker compose config --quiet</nowiki></code>를 사용합니다.

==== 환경 변수 ====

{| class="wikitable"
! 변수 !! 필수 !! 기본값·용도
|-
| <code><nowiki>MARIADB_DATABASE</nowiki></code> || 아니요 || <code><nowiki>s3_research_memory</nowiki></code>; 위키 데이터베이스 이름
|-
| <code><nowiki>MARIADB_USER</nowiki></code> || 아니요 || <code><nowiki>s3wiki</nowiki></code>; MediaWiki DB 계정
|-
| <code><nowiki>MARIADB_PASSWORD</nowiki></code> || 예 || 제한된 MediaWiki DB 계정 비밀번호
|-
| <code><nowiki>MARIADB_ROOT_PASSWORD</nowiki></code> || 예 || 초기화·복구 때만 쓰는 MariaDB 관리자 비밀번호
|-
| <code><nowiki>MW_SITE_NAME</nowiki></code> || 아니요 || <code><nowiki>S3 연구 메모리</nowiki></code>; 브라우저에 표시할 이름
|-
| <code><nowiki>MW_SERVER_URL</nowiki></code> || 아니요 || <code><nowiki>https://s3wiki.yonsei.ac.kr</nowiki></code>; 끝에 <code><nowiki>/</nowiki></code>가 없는 외부 주소
|-
| <code><nowiki>MW_ADMIN_USERNAME</nowiki></code> || 아니요 || <code><nowiki>S3Admin</nowiki></code>; 처음 만드는 관리자 계정 이름
|-
| <code><nowiki>MW_ADMIN_PASSWORD</nowiki></code> || 예 || 처음 만드는 관리자 비밀번호
|-
| <code><nowiki>S3RM_WIKI_USERNAME</nowiki></code> || 아니요 || <code><nowiki>S3ResearchAgent</nowiki></code>; MCP 전용 최소 권한 위키 계정
|-
| <code><nowiki>S3RM_WIKI_PASSWORD</nowiki></code> || 예 || MCP 어댑터만 쓰는 위키 비밀번호
|-
| <code><nowiki>S3RM_HTTP_PORT</nowiki></code> || 아니요 || <code><nowiki>8080</nowiki></code>; MediaWiki 80번 포트에 연결한 호스트 진단 포트
|-
| <code><nowiki>S3RM_WIKI_BIND_ADDRESS</nowiki></code> || 아니요 || <code><nowiki>127.0.0.1</nowiki></code>; 진단 포트를 외부에 열지 않음
|-
| <code><nowiki>S3RM_WIKI_DIRECT_URL</nowiki></code> || 아니요 || 비워 두면 직접 주소를 사용하지 않음. 외부 HTTP 화면을 명시적으로 열 때만 <code><nowiki>http://SERVER_IP:8080</nowiki></code>처럼 전체 주소를 입력하고 bind를 <code><nowiki>0.0.0.0</nowiki></code>으로 설정
|-
| <code><nowiki>S3RM_MCP_PUBLIC_URL</nowiki></code> || 예 || 클라이언트 주소 <code><nowiki>https://s3wiki.yonsei.ac.kr/mcp</nowiki></code>
|-
| <code><nowiki>S3RM_MCP_TOKEN_SHA256</nowiki></code> || 예 || 쓰기 토큰의 64자리 16진수 SHA-256 해시. 원문은 저장하지 않음
|-
| <code><nowiki>S3RM_MCP_BIND_ADDRESS</nowiki></code> || 아니요 || 도메인 프로필에서는 <code><nowiki>127.0.0.1</nowiki></code>. 공개 진입점은 Caddy
|-
| <code><nowiki>S3RM_MCP_HTTP_PORT</nowiki></code> || 아니요 || <code><nowiki>8765</nowiki></code>; MCP 컨테이너 8000번 포트에 연결한 loopback 진단 포트
|-
| <code><nowiki>S3RM_MCP_ALLOWED_HOSTS</nowiki></code> || 아니요 || 쉼표로 나눈 추가 <code><nowiki>Host</nowiki></code> 값. 공개 URL의 host는 자동 허용
|-
| <code><nowiki>S3RM_MCP_ALLOWED_ORIGINS</nowiki></code> || 아니요 || 쉼표로 나눈 추가 HTTP(S) Origin. 공개 URL의 origin은 자동 허용
|-
| <code><nowiki>S3RM_MCP_ALLOW_INSECURE_HTTP</nowiki></code> || 아니요 || <code><nowiki>false</nowiki></code>; 클라이언트 주소는 HTTPS만 사용
|-
| <code><nowiki>S3RM_PUBLIC_HOST</nowiki></code> || 아니요 || <code><nowiki>s3wiki.yonsei.ac.kr</nowiki></code>; Caddy 주소
|-
| <code><nowiki>S3RM_PUBLIC_HTTP_PORT</nowiki></code> || 아니요 || <code><nowiki>80</nowiki></code>; 리디렉션과 인증서 발급용 공개 HTTP 포트
|-
| <code><nowiki>S3RM_PUBLIC_HTTPS_PORT</nowiki></code> || 아니요 || <code><nowiki>443</nowiki></code>; 공개 HTTPS 포트
|-
| <code><nowiki>COMPOSE_PROFILES</nowiki></code> || 아니요 || <code><nowiki>domain</nowiki></code>을 넣으면 Caddy를 실행. 도메인 스크립트가 추가
|-
| <code><nowiki>S3RM_MAX_OUTPUT_BYTES</nowiki></code> || 아니요 || <code><nowiki>32768</nowiki></code>; 도구 결과 제한 2048~65536바이트. 전체 JSON-RPC 응답은 별도 147456바이트 제한
|-
| <code><nowiki>S3RM_SEARCH_SCAN_LIMIT</nowiki></code> || 아니요 || <code><nowiki>200</nowiki></code>; 후보 스캔 제한 20~1000페이지
|-
| <code><nowiki>S3RM_WIKI_TIMEOUT_SECONDS</nowiki></code> || 아니요 || <code><nowiki>20</nowiki></code>; MediaWiki 요청 제한 1~120초
|}

Compose의 <code><nowiki>mcp-http</nowiki></code>는 내부 <code><nowiki>http://mediawiki/api.php</nowiki></code>만 사용합니다. 이 주소와 위키 비밀번호는 클라이언트에 전달하지 않습니다.

직접 HTTP 화면을 함께 열어야 한다면 다음 두 값을 같이 설정합니다. MediaWiki는 정확히 이 Host로 들어온 요청에만 직접 주소를 사용합니다. 임의의 Host 헤더를 신뢰하지 않으며 정식 주소와 MCP 주소는 HTTPS 도메인으로 유지합니다.

<pre><nowiki>
S3RM_WIKI_BIND_ADDRESS=0.0.0.0
S3RM_WIKI_DIRECT_URL=http://165.132.118.220:8080
</nowiki></pre>

이 설정은 Docker의 호스트 리스너만 엽니다. 학교 경계 보안정책에서 TCP 8080이 차단되어 있으면 외부 접속은 계속 timeout입니다. 직접 주소는 위키 화면에만 쓰며 MCP URL로 등록하지 않습니다.

진단 포트만 바꿀 때는 외부 브라우저 주소를 그대로 둡니다.

<pre><nowiki>
S3RM_HTTP_PORT=8090
MW_SERVER_URL=https://s3wiki.yonsei.ac.kr
</nowiki></pre>

==== 도메인과 Caddy 프로필 ====

도메인 스크립트는 여러 번 실행해도 됩니다. Docker를 시작하지 않으며, 기존 토큰과 해시가 일치하면 토큰을 바꾸지 않습니다.

<pre><nowiki>
./scripts/configure-public-domain.sh s3wiki.yonsei.ac.kr \
--expected-ip 165.132.118.220
</nowiki></pre>

<code><nowiki>domain</nowiki></code> 프로필은 Caddy 컨테이너 하나를 시작합니다. Caddy는 TLS 인증서를 발급·갱신하고, HTTP를 HTTPS로 돌립니다. <code><nowiki>/mcp</nowiki></code>와 <code><nowiki>/mcp/*</nowiki></code>는 <code><nowiki>mcp-http</nowiki></code>로 보내고 나머지 경로는 MediaWiki로 보냅니다. MCP 경로를 다시 쓰거나 Lesson을 저장하지 않습니다. 동작 원리는 Caddy의 [https://caddyserver.com/docs/automatic-https 자동 HTTPS 안내]와 [https://caddyserver.com/docs/quick-starts/reverse-proxy 리버스 프록시 안내]를 참고하세요.

정적 <code><nowiki>Authorization</nowiki></code> 헤더를 보낼 수 있는 클라이언트는 공용 Bearer 토큰으로 세 개 변경 도구를 사용할 수 있습니다. 호스팅형 ChatGPT와 Claude 커넥터는 같은 URL에서 공개 조회 도구를 사용할 수 있습니다. 이 제품에서 변경 도구를 쓰려면 OAuth 진입점이 추가로 필요합니다. OAuth를 붙이더라도 MCP나 위키를 하나 더 만들지 않습니다.

=== 시작 ===

필수 변수와 Compose 모델을 출력 없이 확인합니다.

<pre><nowiki>
docker compose config --quiet
</nowiki></pre>

이미지를 빌드하고 서비스를 시작합니다. 아래 명령은 HTTPS 위키 API와 <code><nowiki>/mcp</nowiki></code>도 확인합니다.

<pre><nowiki>
make domain-up
</nowiki></pre>

이 확인은 명령을 실행한 서버 기준입니다. 학교 밖에서 80/443이 열렸는지는 다른 네트워크의 브라우저에서도 확인해야 합니다. 이미 실행 중인 서버의 HTTPS와 MCP만 다시 확인할 때는 <code><nowiki>make verify-domain</nowiki></code>을 사용합니다.

서비스 역할은 다음과 같습니다.

* <code><nowiki>db</nowiki></code>: MariaDB와 <code><nowiki>db_data</nowiki></code> 볼륨
* <code><nowiki>mediawiki</nowiki></code>: Apache/PHP, Semantic MediaWiki, Page Forms, 생성된 <code><nowiki>LocalSettings.php</nowiki></code>, <code><nowiki>mediawiki_config</nowiki></code>·<code><nowiki>mediawiki_images</nowiki></code> 볼륨
* <code><nowiki>bootstrap</nowiki></code>: 스키마·양식 페이지를 맞추고 MCP 계정과 그룹을 만드는 일회성 작업
* <code><nowiki>mcp-http</nowiki></code>: 공개 조회와 토큰 기반 변경을 제공하는 공용 Streamable HTTP 어댑터. Lesson DB나 영구 볼륨은 없음
* <code><nowiki>caddy</nowiki></code>: 위키와 MCP의 공개 HTTPS 진입점
첫 시작 상태를 확인합니다.

<pre><nowiki>
docker compose ps -a
docker compose logs -f mediawiki bootstrap mcp-http caddy
</nowiki></pre>

<code><nowiki>db</nowiki></code>, <code><nowiki>mediawiki</nowiki></code>, <code><nowiki>mcp-http</nowiki></code>, <code><nowiki>caddy</nowiki></code>가 실행 또는 healthy 상태이고, <code><nowiki>bootstrap</nowiki></code>이 코드 0으로 종료되면 정상입니다. Caddy 인증서도 발급되어야 합니다. <code><nowiki>bootstrap</nowiki></code>은 일회성 작업이므로 종료 상태가 정상입니다. <code><nowiki>docker compose up -d</nowiki></code>를 다시 실행해도 관리 스키마와 양식을 맞추며 일반 Lesson과 변경 이력은 보존합니다. 새 설치에는 Lesson 페이지가 없습니다. 첫 메모를 저장하기 전에는 최근 목록과 검색 결과가 비어 있어도 정상입니다.

 브라우저 설치 단계는 없습니다. 저장된 <code><nowiki>LocalSettings.php</nowiki></code>가 없으면 <code><nowiki>mediawiki</nowiki></code> entrypoint가 Apache를 시작하기 전에 MediaWiki CLI 설치를 실행하고 DB 마이그레이션을 적용합니다. <code><nowiki>/mw-config/</nowiki></code>에 접속하거나, 브라우저 설치를 다시 시작하거나, 생성된 <code><nowiki>LocalSettings.php</nowiki></code>를 컨테이너에 복사하지 마세요. 설치 화면이 나오거나 세션 만료 오류가 보이면 [[Help:S3 연구 메모리/문제 해결#브라우저에 설치 세션 만료가 표시됨|문제 해결 안내]]를 따릅니다.

[https://s3wiki.yonsei.ac.kr/]를 엽니다. 읽기와 검색은 로그인 없이 할 수 있습니다. 작성과 편집에는 이름이 있는 위키 계정이 필요합니다.

* <code><nowiki>/index.php/Special:Version</nowiki></code>: Semantic MediaWiki, Page Forms, S3 Research Memory 확장 기능 확인
* <code><nowiki>/index.php/연구_메모리#create-a-lesson</nowiki></code>: 문서 ID를 정하고 <code><nowiki>Lesson:</nowiki></code> 메모 작성
* <code><nowiki>/index.php/Special:Search</nowiki></code>: MediaWiki 전문 검색
* <code><nowiki>/index.php/Special:AllPages?namespace=3000</nowiki></code>: 모든 <code><nowiki>Lesson:</nowiki></code> 페이지
=== 브라우저 계정 만들기 ===

자기 가입은 꺼져 있습니다. 설정에서 익명 그룹(<code><nowiki>*</nowiki></code>)의 <code><nowiki>createaccount</nowiki></code> 권한을 제거했고, 관리자 그룹(<code><nowiki>sysop</nowiki></code>)만 계정을 만들 수 있습니다. 새 설치에서는 다음 순서로 일반 편집 계정을 만드세요.

# <code><nowiki>MW_ADMIN_USERNAME</nowiki></code>과 <code><nowiki>MW_ADMIN_PASSWORD</nowiki></code>로 로그인합니다.
# <code><nowiki>/index.php/Special:CreateAccount</nowiki></code>를 엽니다.
# 사용할 사람의 이름을 알 수 있는 사용자 이름과 새 임시 비밀번호를 입력합니다.
# 계정을 만든 뒤 <code><nowiki>/index.php/Special:ListUsers</nowiki></code>에서 확인합니다.
# <code><nowiki>sysop</nowiki></code>, <code><nowiki>bureaucrat</nowiki></code>, <code><nowiki>agent</nowiki></code> 그룹은 추가하지 않습니다. 로그인한 일반 계정은 자동으로 <code><nowiki>user</nowiki></code> 권한을 받아 양식으로 메모를 작성·편집할 수 있습니다.
# 새 계정으로 로그인해 비밀번호를 바꾸고 메모 양식이 열리는지 확인합니다.
관리자 계정이나 <code><nowiki>S3RM_WIKI_USERNAME</nowiki></code> 계정을 일상 편집에 함께 쓰지 마세요. 계정과 권한 기준은 [[Help:S3 연구 메모리/보안|S3RM1]]에 정리되어 있습니다.

=== 설치 확인 ===

로컬 테스트와 Compose 검사를 실행합니다.

<pre><nowiki>
make test
make check-compose
</nowiki></pre>

<code><nowiki>make test</nowiki></code>는 Compose 없이 메모리 내 위키 어댑터로 스키마, 에이전트 권한, 관계, 페이지네이션, 직렬화 출력 제한을 확인합니다. <code><nowiki>make check-compose</nowiki></code>는 테스트용 필수 값을 넣은 뒤 Compose 배포 모델을 확인합니다.

브라우저에서는 다음을 확인합니다.

# 로그아웃 상태에서 <code><nowiki>Special:Version</nowiki></code>, 검색, Lesson 페이지가 열리고, 작성·편집은 로그인을 요구하는지 확인합니다.
# 새 설치라면 Lesson 네임스페이스의 <code><nowiki>Special:AllPages</nowiki></code>가 비어 있어도 정상입니다.
# 로그인한 일반 계정으로 <code><nowiki>/index.php/연구_메모리#create-a-lesson</nowiki></code>을 열고 작성 양식이 보이는지 확인합니다. 확인용 가짜 메모는 저장하지 않습니다.
# 첫 실제 메모를 저장할 때 검색에 바로 나오는지, 필드와 근거 인용이 보이는지, '''역사 보기'''에 변경 이력이 생겼는지 확인합니다.
==== 클라이언트를 연결하기 전 공용 MCP 확인 ====

<code><nowiki>.env</nowiki></code>의 <code><nowiki>S3RM_MCP_PUBLIC_URL</nowiki></code>과 같은 주소를 설정합니다.

<pre><nowiki>
export S3RM_MCP_URL='https://s3wiki.yonsei.ac.kr/mcp'
</nowiki></pre>

서버에서 프로세스 상태를 먼저 확인합니다. <code><nowiki>S3RM_MCP_HTTP_PORT</nowiki></code>를 바꿨다면 8765도 같이 바꿉니다. 이 경로는 프로세스 상태만 반환하며 위키 데이터나 인증이 없습니다.

<pre><nowiki>
curl --fail --silent --show-error http://127.0.0.1:8765/healthz
</nowiki></pre>

이어서 토큰 없이 MCP 초기화를 보냅니다. HTTP나 JSON 오류가 있으면 0이 아닌 코드로 끝납니다.

<pre><nowiki>
python3 - <<'PY'
import json
import os
import urllib.request

payload = json.dumps({
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "s3rm-setup-smoke", "version": "1"},
},
}).encode()
request = urllib.request.Request(
os.environ["S3RM_MCP_URL"],
data=payload,
headers={
"Accept": "application/json, text/event-stream",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request, timeout=20) as response:
result = json.load(response)
assert result.get("result", {}).get("serverInfo", {}).get("name") == "S3 Research Memory"
print("anonymous MCP initialize: ok")
PY
</nowiki></pre>

토큰이 없는 클라이언트도 초기화, 도구 목록, <code><nowiki>search_lessons</nowiki></code>, <code><nowiki>get_lesson</nowiki></code>, <code><nowiki>find_related_lessons</nowiki></code>, <code><nowiki>find_analogies</nowiki></code>를 사용할 수 있습니다. [[Help:S3 연구 메모리/MCP 클라이언트|S3RM4]]에 따라 연결하고 <code><nowiki>search_lessons(limit=1)</nowiki></code>을 실행합니다. 다른 PC의 클라이언트에서도 같은 결과가 나오는지 확인하세요.

메모 작성, 관계 연결, 근거 첨부가 필요한 클라이언트에는 플랫폼 설정으로 공용 토큰을 불러옵니다. 연결 확인만 하려고 가짜 메모를 만들지 않습니다. 쓰기 권한 경계는 <code><nowiki>make test</nowiki></code>로 확인하고, 실제 첫 메모를 남길 때 MediaWiki 이력과 검색 결과를 확인합니다.

=== 평소 시작과 종료 ===

설치가 끝난 서비스를 시작합니다.

<pre><nowiki>
docker compose up -d
docker compose ps -a
make verify-domain
</nowiki></pre>

마지막 명령은 서버에서 본 HTTPS 위키와 MCP를 확인합니다. 다른 PC에서 접속되는지는 그 PC의 브라우저나 MCP 클라이언트로 따로 확인합니다.

볼륨을 남기고 종료합니다.

<pre><nowiki>
docker compose down
</nowiki></pre>

MediaWiki만 다시 시작합니다.

<pre><nowiki>
docker compose restart mediawiki
</nowiki></pre>

공용 MCP 프로세스만 다시 시작합니다.

<pre><nowiki>
docker compose restart mcp-http
docker compose ps mcp-http
</nowiki></pre>

의도적으로 설정을 바꾼 뒤 스키마·계정을 다시 맞춥니다.

<pre><nowiki>
docker compose up -d --force-recreate bootstrap
docker compose logs bootstrap
</nowiki></pre>

일반 운영 중에는 <code><nowiki>docker compose down --volumes</nowiki></code>, <code><nowiki>docker volume rm</nowiki></code>, 수동 SQL 삭제를 실행하지 마세요. 위키의 기준 데이터가 사라집니다.

=== 자격 증명 변경 ===

<code><nowiki>.env</nowiki></code> 값만 바꿔도 MariaDB나 MediaWiki에 이미 저장된 자격 증명은 바뀌지 않습니다. 해당 제품의 계정 관리 절차로 먼저 바꾸고, 같은 작업 시간에 <code><nowiki>.env</nowiki></code>와 관련 서비스를 함께 갱신합니다.

* 공용 MCP 토큰: <code><nowiki>./scripts/configure-mcp-token.sh --rotate</nowiki></code>를 실행하고 <code><nowiki>mcp-http</nowiki></code>를 다시 만듭니다. 변경 경로를 확인한 뒤 새 handoff를 전달하고 클라이언트를 재연결합니다. <code><nowiki>--rotate</nowiki></code>가 없으면 일치하는 기존 토큰을 보존합니다. 공개 조회는 계속되지만 이전·새 쓰기 토큰을 동시에 받을 수는 없습니다.
* MCP 위키 계정: <code><nowiki>S3RM_WIKI_PASSWORD</nowiki></code>를 바꾸고 <code><nowiki>bootstrap</nowiki></code>을 다시 실행한 뒤 <code><nowiki>mcp-http</nowiki></code>를 다시 만듭니다. <code><nowiki>bootstrap</nowiki></code>은 전용 계정과 <code><nowiki>agent</nowiki></code> 그룹을 맞추고 높은 권한을 제거합니다.
* 일반 위키 계정: MediaWiki 화면에서 비밀번호를 바꿉니다. DB 테이블을 직접 편집하지 마세요.
* MariaDB 계정: MariaDB 공식 계정 관리 절차로 서버 계정을 바꾼 뒤, 같은 작업 시간에 <code><nowiki>.env</nowiki></code>를 갱신합니다.
먼저 백업하고, 변경 뒤 조회를 확인합니다. 공용 토큰 절차는 [[Help:S3 연구 메모리/백업과 복원#공용 MCP 토큰 교체|S3RM0]]에 있습니다.

=== 업데이트 ===

MediaWiki 기본 이미지는 정확한 버전으로 고정되어 있습니다. PHP 의존성은 <code><nowiki>docker/mediawiki/composer.lock</nowiki></code>, Python 의존성은 <code><nowiki>mcp/uv.lock</nowiki></code>을 사용합니다. MariaDB 이미지는 호환 태그를 사용합니다.

# MediaWiki, Semantic MediaWiki, Page Forms, MariaDB, MCP 의존성의 릴리스 안내와 호환표를 확인합니다.
# [[Help:S3 연구 메모리/백업과 복원|S3RM0]]에 따라 전체 백업을 만들고 확인합니다.
# 버전 고정을 추적 가능한 커밋에서 바꿉니다. 실제 서버에서 검증하지 않은 floating 버전을 쓰지 마세요.
# <code><nowiki>make test</nowiki></code>와 <code><nowiki>make check-compose</nowiki></code>를 실행합니다.
# 별도 볼륨에 빌드하고 복원 시험을 합니다.
# 확인 뒤 실제 서버 이미지를 다시 만들고 <code><nowiki>bootstrap</nowiki></code>의 마이그레이션·동기화를 완료합니다.
<pre><nowiki>
docker compose build --pull mediawiki mcp-http
docker compose up -d
docker compose logs mediawiki bootstrap mcp-http caddy
</nowiki></pre>

새 MediaWiki에서 만든 DB를 더 오래된 MediaWiki로 복원하지 마세요. 호환성은 [https://www.semantic-mediawiki.org/wiki/Help:Installation Semantic MediaWiki 설치 안내], [https://www.mediawiki.org/wiki/Extension:Page_Forms/Download_and_installation Page Forms 설치 안내], [https://www.mediawiki.org/wiki/Manual:Upgrading MediaWiki 업그레이드 안내]를 기준으로 확인합니다.