Docker Compose를 사용하여 Synapse Matrix 서버를 설치하는 방법

예시: 소규모 자원봉사 단체가 주소에 Matrix 홈서버를 구축하려는 경우를 가정해 보겠습니다 chat.example.com. 이는 가상의 설정이며, 실제 테스트된 서버에 대한 보고서가 아닙니다. 동일한 단계를 실제 도메인에도 적용할 수 있지만, Matrix 서버 이름은 신중하게 선택해야 합니다. Synapse는 이 이름을 사용자 ID에 사용하며, 나중에 변경할 수 없습니다.

이 가이드는 Docker Compose를 사용하여 Synapse 서비스와 PostgreSQL 데이터베이스를 생성합니다. Synapse의 공식 Docker 이미지는 기본적으로 SQLite를 사용하므로 임시 테스트에는 편리하지만, Synapse의 Docker 문서에서는 프로덕션 환경에서는 PostgreSQL 사용을 권장합니다. 따라서 이 예제에서는 먼저 Synapse 구성을 생성하고, 데이터베이스 설정을 PostgreSQL로 변경한 다음 두 컨테이너를 모두 시작합니다. 공식 이미지는 다음과 같습니다 ghcr.io/element-hq/synapse. 본 가이드의 지침 및 이미지 세부 정보는 2026년 10월 6일 기준 최신 공식 문서를 기준으로 작성되었습니다. 이미지 태그 및 지원되는 소프트웨어 버전은 변경될 수 있으므로 장기간 배포하기 전에 링크된 문서를 검토하시기 바랍니다.

설치하기 전에 필요한 사항

Docker Engine과 Docker Compose 플러그인이 설치된 Linux 서버 또는 Docker를 지원하는 호스트가 필요합니다. Compose가 사용 가능한지 확인하십시오 docker compose version. 운영 체제에 맞는 Docker 공식 설치 지침을 따르십시오.
서버를 가리키는 도메인 또는 서브도메인입니다. 이 예에서 chat.example.com는 Synapse 서버 이름이므로 로컬 사용자 ID는 와 같이 표시됩니다 @alex:chat.example.com. 구성을 생성하기 전에 를 직접 관리하는 도메인으로 바꾸십시오.
공용으로 사용할 수 있는 리버스 프록시 또는 다른 TLS 종료 방식입니다. Synapse의 기본 HTTP 리스너는 포트 360에서 8008인터넷에 연결된 HTTPS 엔드포인트가 아닙니다. 이 Compose 예제에서는 해당 포트를 호스트의 루프백 인터페이스에 바인딩하여 동일한 시스템의 리버스 프록시가 접근할 수 있도록 합니다.

이름이 모든 클라이언트 연결의 URL과 반드시 일치하는 것은 아닙니다. 클라이언트에게 서비스를 제공하는 동안 SYNAPSE_SERVER_NAME와 같은 더 짧은 ID를 사용하려면 도메인 및 검색 구성을 신중하게 설정해야 합니다. 계정을 생성하기 전에 이 부분을 결정하십시오.@alex:example.comchat.example.com

1. 작업 디렉터리와 데이터베이스 암호를 생성합니다.

서버에서 Compose 프로젝트와 Synapse 파일이 저장될 디렉토리를 만드세요.

mkdir -p ~/matrix-synapse/data
cd ~/matrix-synapse

.envDocker Compose가 읽을 로컬 파일을 생성합니다 . 암호 관리자 또는 로컬 보안 생성기를 사용하여 길고 무작위적인 암호를 생성하고, 해당 암호를 파일 이름 뒤에 저장합니다 POSTGRES_PASSWORD=. 나중에 YAML 따옴표 관련 문제를 방지하기 위해 이 예시에서는 문자와 숫자를 혼합하여 사용합니다. 이 파일을 공개 저장소에 커밋하지 말고, 권한을 제한하십시오.

umask 077
nano .env

해당 파일에는 예를 들어 와 같이 한 줄이 포함되어야 합니다 POSTGRES_PASSWORD=replace-with-a-long-random-value. 이 텍스트는 자리 표시자이며 재사용할 암호가 아닙니다. 3단계에서 Synapse 데이터베이스 구성을 위해 암호를 보관하십시오.

2. Synapse 및 PostgreSQL 서비스를 정의합니다.

compose.yaml프로젝트 디렉터리에 생성 :

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: chat.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"

volumes:
  postgres_data:

chat.example.com최종적으로 선택한 서버 이름으로 바꾸십시오 . PostgreSQL 상태 확인을 통해 Compose는 Synapse를 시작하기 전에 데이터베이스가 준비되었다는 보고를 받을 때까지 기다립니다. 명명된 데이터베이스 볼륨과 호스트에 마운트된 ./data디렉터리는 컨테이너를 교체해도 유지됩니다. 컨테이너만 제거한다고 해서 이러한 항목이 삭제되지는 않습니다. docker compose down -v데이터베이스 볼륨을 의도적으로 삭제하려는 경우가 아니라면 이 작업을 수행하지 마십시오.

이 예시는 :latest첫 번째 풀 작업을 간단하게 하기 위한 것입니다. 유지 관리되는 서버의 경우, 특정 Synapse 릴리스 태그 또는 이미지 다이제스트를 선택하여 기록한 다음, 릴리스 노트를 검토한 후 계획된 업그레이드 프로세스를 통해 업데이트하십시오. 변경 가능한 latest태그가 항상 동일한 버전을 유지한다고 가정하지 마십시오.

3. Synapse의 설정을 생성하고 PostgreSQL을 가리키도록 지정합니다.

공식 이미지를 구성 생성 모드로 한 번 실행하십시오. Compose는 ./data에 마운트되므로 /data생성된 구성과 서명 키는 호스트에 유지됩니다.

docker compose run --rm synapse generate

이 명령은 Compose 환경에서 선택한 서버 이름과 익명 통계 옵션을 사용합니다. Synapse는 서명 키도 생성합니다. 이 키는 데이터 디렉터리에 보관하고 보호된 백업에 포함해야 합니다. 일반적인 컨테이너 업데이트 중에는 서명 키를 다시 생성하거나 삭제하지 마십시오.

data/homeserver.yaml생성된 섹션을 열고 다음 설정으로 교체하십시오. 자리 표시자 대신 database:정확한 암호를 사용하십시오 ..env

database:
  name: psycopg2
  args:
    user: synapse
    password: 'replace-with-the-same-random-value'
    dbname: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

주변 YAML 들여쓰기를 유지하고 활성화된 섹션이 하나만 있는지 확인하십시오 database:. 호스트 이름은 컨테이너가 공유 기본 네트워크에서 확인할 수 있는 Compose 서비스 이름입니다. 구성에는 Synapse에서 문서화된 PostgreSQL 엔진 이름 과 데이터베이스 인자 이름(예: )이 postgres사용됩니다 .psycopg2dbname

이 간단한 예시에서는 데이터베이스 암호가 Synapse 구성 파일과 보호된 .env파일 모두에 나타납니다. 두 파일 모두 비밀 정보로 취급하고, 호스트 접근을 제한하며, 배포 환경에 따라 필요한 경우 전용 비밀 정보 관리 방식을 사용하십시오. 실제 암호를 로그, 스크린샷 또는 지원 요청에 붙여넣지 마십시오.

4. Docker Compose를 사용하여 Synapse를 시작합니다.

스택을 백그라운드에서 시작합니다.

docker compose up -d

서비스 상태를 확인하고 시작 로그를 읽어보세요.

docker compose ps
docker compose logs --tail=100 synapse

Synapse가 처음 시작할 때 데이터베이스 설정을 완료할 때까지 기다리세요. 실행 중인 컨테이너는 해당 프로세스가 활성화되어 있다는 의미일 뿐입니다. 계속 진행하기 전에 로그에서 구성, 데이터베이스 또는 권한 오류를 확인하세요. 로그가 도착하는 대로 확인하려면 [ 로그 추적 중지]를 누르고 [로그 추적 중지] docker compose logs -f synapse를 누르세요 .Ctrl+C

5. 로컬 API를 확인하고 공개 액세스를 구성합니다.

Docker 호스트에서 Synapse 클라이언트 API 버전 엔드포인트를 요청합니다.

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

성공적인 응답은 지원되는 Matrix 클라이언트 API 버전을 설명하는 JSON 형식입니다. 이는 HTTP 리스너가 로컬에서 응답하고 있음을 확인시켜주지만, DNS, HTTPS 또는 페더레이션이 올바르게 구성되었음을 증명하는 것은 아닙니다.

선택한 도메인에 대한 요청을 전달하고 유효한 TLS 인증서를 획득하도록 호스트 역방향 프록시를 구성하십시오 http://127.0.0.1:8008. 프록시 설정 시 Matrix 요청 경로를 유지하십시오. 그런 다음 공개 엔드포인트를 확인하십시오.

curl -fsS https://chat.example.com/_matrix/client/versions

예시 호스트 이름을 실제 호스트 이름으로 바꾸십시오. 클라이언트가 별도의 사용자 ID 도메인에서 홈서버를 검색해야 하는 경우, 해당 설계에 맞는 Matrix WND(Well-Known Discovery) 레코드를 게시하십시오. 페더레이션을 위해서는 올바른 공용 라우팅 및 DNS 설정이 필요하며, 로컬 포트만 여는 것으로 8008는 완전한 공용 배포가 이루어지지 않습니다. 서비스를 공개하기 전에 Synapse의 리버스 프록시 및 페더레이션 관련 지침을 검토하십시오.

6. 첫 번째 관리자 계정을 생성합니다.

Synapse는 기본적으로 공개 계정 등록을 비활성화합니다. 개인 서버의 경우 이 기본 설정을 유지하고 명령줄에서 계정을 생성하세요. `<계정 이름>` registration_shared_secret에 강력한 값을 임시로 추가한 data/homeserver.yaml다음 Synapse를 다시 시작하여 변경 사항을 적용합니다.

docker compose restart synapse

컨테이너 내부에서 등록 도구를 실행합니다. 사용자 이름과 비밀번호를 입력하라는 메시지가 표시되며, 설정을 통해 --admin첫 번째 관리자가 생성됩니다.

docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

계정 생성 후 registration_shared_secret구성에서 해당 암호를 제거하고 Synapse를 다시 시작하십시오. 암호를 그대로 두면 암호를 얻은 사람은 누구나 등록 인터페이스를 통해 일반 계정 또는 관리자 계정을 등록할 수 있습니다. 리버스 프록시에서 제공하는 서버 URL을 사용하여 사용자 지정 홈서버를 지원하는 Matrix 클라이언트를 통해 로그인하십시오.

백업, 업그레이드 및 일반적인 문제 해결

올바른 데이터를 백업하십시오. PostgreSQL 데이터를 중지하거나 정기적으로 스냅샷을 생성하고 ./data구성, 미디어 및 서명 키를 포함한 모든 데이터를 백업하십시오. 백업 파일 compose.yaml만으로는 홈서버를 복원할 수 없습니다. 백업 파일은 서버와 별도의 위치에 저장하고 주기적으로 읽을 수 있는지 확인하십시오.
Synapse가 해당 디렉터리에 쓰기 권한이 없습니다 /data. 호스트 소유권 및 권한을 확인하십시오 ./data. 공식 이미지의 런타임 사용자는 구성 파일을 읽고 데이터를 쓸 수 있는 권한이 필요합니다. 디렉터리를 모든 사용자가 쓸 수 있도록 설정하지 말고 호스트 소유권을 신중하게 조정하십시오.
데이터베이스 연결 실패: 데이터베이스 구성에서 를 사용하고 있는지 host: postgres, 암호가 일치하는지 .env, 그리고 docker compose logs postgres데이터베이스 상태가 정상인지 확인하십시오. Compose의 depends_on준비 상태 조건은 시작 시 경쟁 조건을 줄여주지만 잘못된 자격 증명을 수정하지는 않습니다.
로컬 API는 작동하지만 클라이언트가 연결할 수 없는 경우, 선택한 도메인 구성에 대한 DNS 레코드, TLS 인증서, 리버스 프록시 업스트림 및 검색 레코드를 확인하십시오. 루프백 전용 포트 매핑은 동일 호스트 프록시를 위한 의도적인 설정입니다. 다른 컨테이너에 있는 프록시는 공유 Docker 네트워크와 다른 라우팅 구조가 필요합니다.
업그레이드:docker compose pull 먼저 백업을 수행하고, Synapse 릴리스 노트를 검토하고, 고정된 이미지 태그를 업데이트한 다음, 명령어를 사용하여 서비스를 다시 생성하십시오 docker compose up -d. 데이터 디렉터리, 데이터베이스 볼륨, 서버 이름 및 서명 키는 그대로 유지하십시오.

예시로 제시된 자원봉사자 그룹 설정에서 설치는 로컬 버전 엔드포인트가 응답하고, 프록시를 통해 HTTPS 엔드포인트가 응답하며, 관리자가 의도한 Matrix ID 도메인을 사용하여 로그인할 수 있을 때만 완료됩니다. 이러한 확인 사항은 첫 번째 배포가 정상적으로 작동하는지 여부를 판단하는 실질적인 지표이지만, 더 넓은 커뮤니티를 초대하기 전에 보안, 백업, 연동 및 운영 요구 사항을 검토하는 것을 대체하는 것은 아닙니다.