moyro

Air-gap installation · v0.2.52 release

레지스트리 없이 설치하는
moyro 오프라인 배포

하나의 압축 Docker image와 내부 PostgreSQL로 서비스를 기동하고 로그인과 재시작까지 확인합니다.

v0.2.52 release platform · linux/amd64

1. 대상 망 준비

Docker를 실행할 수 있는 Linux amd64 호스트와 moyro 전용 PostgreSQL 데이터베이스를 준비합니다. 릴리스 archive에는 애플리케이션과 웹 UI만 있으며 PostgreSQL image는 포함하지 않습니다.

  • 호스트에서 PostgreSQL 내부 주소와 port로 연결할 수 있어야 합니다.
  • 사용자 접속용 8065 port 또는 내부 reverse proxy를 준비합니다.
  • PostgreSQL과 moyro-data volume을 함께 백업할 위치를 정합니다.
  • TLS가 필요하면 승인된 내부 reverse proxy에서 종료합니다.
지원 토폴로지는 애플리케이션 컨테이너 한 개입니다.
v0.2.52은 외부 PostgreSQL과 로컬 file volume을 사용합니다. SMTP 관리 설정, S3, Redis fan-out, outbound link preview와 multi-replica 설정 전파는 지원하지 않습니다. SMTP host가 없으면 이메일 capability는 false이고 digest worker도 시작하지 않습니다.
Forwarded header는 기본적으로 신뢰하지 않습니다.
Reverse proxy가 외부의 Forwarded와 X-Forwarded-For를 제거하도록 구성한 뒤, moyro에 직접 연결하는 proxy 주소만 사이트 설정의 Trusted proxy CIDRs에 추가하세요. 직접 peer가 일치할 때만 chain을 오른쪽부터 해석해 원본 client IP와 공개 scheme/host를 사용합니다. 로그인 시작·provider callback·session exchange는 분리된 rate limit을 사용합니다.

2. v0.2.52 이미지 로드

v0.2.52 릴리스의 custom asset 이름은 moyro-v0.2.52.tar.gz이며 로드되는 image tag는 moyro:v0.2.52입니다. 실제 게시 여부와 SHA-256은 GitHub Release에서 확인한 뒤 조직의 승인된 매체로 archive를 반입하세요.

$ sha256sum moyro-v0.2.52.tar.gz

$ docker load --input moyro-v0.2.52.tar.gz
Loaded image: moyro:v0.2.52

$ docker image inspect \
    --format '{{.Os}}/{{.Architecture}} {{.Config.Labels}}' \
    moyro:v0.2.52

먼저 SHA-256이 게시된 GitHub Release notes의 값과 정확히 같은지 확인합니다. 그 다음 출력 platform이 linux/amd64이고 OCI version label이 v0.2.52인지 확인합니다.

3. 정확히 네 가지 환경변수

/etc/moyro/moyro.env를 만들고 다음 네 값만 moyro에 전달합니다.

POSTGRES_DSN=postgres://moyro:password@db.internal:5432/moyro?sslmode=require
BOOTSTRAP_ADMIN=admin@example.internal
BOOTSTRAP_ADMIN_PASSWORD=replace-with-12-to-72-byte-secret
ENCRYPTION_KEY=replace-with-standard-base64-for-32-random-bytes

신뢰할 수 있는 관리 workstation에서 openssl rand -base64 32로 encryption key를 생성하고 결과 한 줄을 사용합니다. 파일 권한을 600으로 제한하세요.

ENCRYPTION_KEY를 잃어버리거나 바꾸지 마세요.
v0.2.52에는 온라인 root-key 재암호화 절차가 없습니다. DB와 별도의 보호 위치에 백업하고 인스턴스 수명 동안 같은 값을 유지합니다.

4. 읽기 전용 container 실행

$ docker volume create moyro-data

$ docker run -d --name moyro \
  --restart unless-stopped \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --env-file /etc/moyro/moyro.env \
  --mount type=volume,src=moyro-data,dst=/var/lib/moyro \
  --publish 8065:8065 \
  moyro:v0.2.52

Container는 non-root 사용자로 실행되며 /var/lib/moyro volume에 로컬 파일 상태를 보존합니다. 시작 과정에서 PostgreSQL advisory lock을 얻은 뒤 아직 적용하지 않은 번호형 migration을 순서대로 실행하고, 이름·checksum·적용 시각을 schema_migrations에 기록합니다. 이미 적용한 파일의 checksum이 달라졌거나 migration이 실패하면 서비스 시작도 실패합니다.

5. 인수 검증

$ curl --fail http://127.0.0.1:8065/healthz
ok

$ docker logs --tail 100 moyro
  1. /healthz가 ok를 반환하는지 확인합니다.
  2. 브라우저에서 로그인 화면과 React asset이 표시되는지 확인합니다.
  3. 로그인 화면의 버전이 v0.2.52인지 확인합니다.
  4. Bootstrap 관리자 로그인이 되는지 확인합니다.
  5. docker restart moyro 뒤 health와 같은 관리자 로그인을 다시 확인합니다.
  6. 업그레이드 설치라면 durable 업데이트의 읽음 상태, 작업·결정의 원본 링크와 권한, 예약 발송의 중복 여부 및 outgoing webhook의 PostgreSQL 재시도를 확인합니다.
오프라인 배포 검증 대상인 moyro 로그인 화면과 버전
로그인 화면과 프로필 컨텍스트 메뉴의 버전은 로드한 Docker tag와 같아야 합니다.

6. 첫 로그인 뒤 서비스 설정

관리자 프로필 메뉴에서 서비스 관리를 엽니다. 먼저 사이트 이름, 사용자가 접속하는 canonical Public Base URL, 로컬 가입 정책, outgoing webhook hostname allowlist와 메시지 초안 보안 정책을 저장합니다. Reverse proxy를 사용하는 경우 외부 forwarding header를 제거하도록 proxy를 구성한 뒤 직접 peer의 CIDR만 Trusted proxy CIDRs에 입력합니다. 초안은 1~30일 local 보존, 현재 session만 또는 저장 안 함 중 하나를 선택하고 로그아웃 cleanup을 정합니다. Keycloak OIDC를 활성화하려면 Public Base URL이 반드시 먼저 저장되어 있어야 합니다. 공개 가입을 계속 닫아 둘 때는 사이트 설정의 사용자 초대에서 일반 사용자 링크 또는 허용 채널·접근 만료·파일 다운로드 정책이 있는 게스트 링크를 발급합니다.

오프라인 설치 뒤 입력하는 moyro 사이트와 outbound 설정
Allowlist가 비어 있으면 outgoing webhook callback이 차단됩니다.

필요한 경우에만 내부 Keycloak, OpenAI 호환 AI, 개인 키 정책, MCP와 승인 정책을 각각 설정하고 연결을 확인합니다. Keycloak은 realm issuer 또는 정확한 discovery 문서 주소를 받을 수 있으며, 연동 확인에서 discovery와 JWKS signing key를 실제 조회합니다. Groups claim과 정확한 그룹별 팀·채널·역할 매핑을 저장하면 SSO 로그인 때 멤버십을 중복 없이 추가합니다. Discovery·token·JWKS는 container에서, authorization endpoint는 사용자 브라우저에서 접근 가능해야 합니다. 서로 다른 HTTP(S) origin의 front-channel/back-channel은 지원합니다. HTTPS issuer가 HTTP token·JWKS·UserInfo endpoint를 광고하면 기본적으로 거부하며, 격리된 신뢰 내부망인 경우에만 신뢰할 수 있는 내부망의 HTTP back-channel 허용을 켜세요. Client secret과 authorization code가 평문으로 전송되고 HTTP 통신과 JWKS가 가로채기·변조될 수 있습니다. 브라우저 authorization endpoint는 옵션과 관계없이 HTTPS여야 합니다. Client secret과 redirect 등록은 실제 테스트 로그인으로 별도 검증하세요.

운영 자동화는 Moyro native /api/moyro/v1와 Mattermost 호환 /api/v4 OpenAPI 3.1 계약을 구분해 사용합니다.

Native plugin을 sandbox로 취급하지 마세요.
관리 페이지에서 업로드하거나 /var/lib/moyro/plugins에 배치한 실행 파일은 서비스 UID, 컨테이너 namespace, volume과 network를 공유하는 서명 미검증 완전 신뢰 코드입니다. manage_plugins 관리자는 검토한 Mattermost .tar.gz를 runtime에 업로드·교체·활성화·비활성화·설정·삭제할 수 있지만 archive 검사는 sandbox나 공급망 검증이 아닙니다.

PostgreSQL archive E2E는 Botman 0.1.2의 status/config 보안, Chatdump 0.5.1의 export/config/replace, Langflow 0.1.20의 mock SSE bot workflow, EchoSummary 0.6.5의 mock vLLM slash/DM workflow를 기능적으로 검증합니다. 네 archive 모두 설치와 재시작을 거칩니다. 공개 CI는 checksum으로 고정한 EchoSummary 0.6.4 자산을 사용하고 local release gate가 0.6.5를 추가 검증합니다. 이 경계는 임의의 Mattermost 플러그인, 다른 버전, 실제 외부 AI 공급자나 명시하지 않은 기능의 호환을 보장하지 않습니다.

7. 백업과 업그레이드

다음 세 항목을 같은 복구 시점의 세트로 보관합니다.

  1. 조직의 PostgreSQL 절차로 생성한 moyro DB 백업
  2. 업로드 파일이 있는 moyro-data volume 백업
  3. 별도 보호 위치의 ENCRYPTION_KEY

업그레이드 전 세 항목을 백업하고 새 archive를 로드한 뒤 같은 환경 파일과 volume으로 새 tag를 실행합니다. Health, 버전, 로그인, 채널 게시, durable 업데이트 읽음 상태, 작업·결정, 예약 발송, WebSocket, 파일 및 활성화한 내부 연동을 다시 확인하고 schema_migrations의 최신 version과 checksum을 기록하세요.

v0.2.5의 000012_sso_handoff_idempotency는 같은 browser binding의 응답 유실 재시도에 60초 동안 같은 session을 반환합니다. v0.2.52은 000013_work_management, 000014_knowledge_documents, 000015_collaboration_controls를 추가해 자동화·업무 이력, 대화 문서와 citation, 알림 규칙·게스트 경계를 보존합니다. 복구 검증에는 cookie 기반 로그인·/users/me, 자동화 중복 방지, 문서 원본 권한, 게스트 만료와 SSO 그룹 온보딩을 함께 포함하세요.

Webhook queue는 durable하지만 아직 완전한 transactional outbox는 아닙니다.
Callback과 시도 이력은 PostgreSQL에 남아 재시작 뒤에도 lease와 backoff로 처리됩니다. 다만 post commit과 delivery 등록은 하나의 transaction이 아니므로 enqueue 오류 로그를 별도로 감시하세요.
Image-only rollback을 가정하지 마세요.
DB schema가 변경된 릴리스는 이전 image만 다시 실행해 안전하게 돌아갈 수 없을 수 있습니다. 이전 image와 그 시점의 DB·volume 백업을 함께 보존하세요.

연결 가능한 staging host에서는 저장소의 scripts/verify-release.sh moyro:v0.2.52 moyro-v0.2.52.tar.gz로 offline startup, web UI, version, bootstrap login과 restart 검증을 실행할 수 있습니다. v0.2.52의 최종 통과 여부는 해당 릴리스 gate 결과로 확인하세요.