Docker Compose 및 PostgreSQL을 사용하여 Matrix Synapse를 배포하세요.

Synapse를 영구 구성 디렉터리와 PostgreSQL 데이터베이스를 사용하는 Docker Compose 프로젝트로 실행하세요. 아래 설정은 Synapse의 서명 키를 생성하고 homeserver.yaml, PostgreSQL에 연결하며, HTTP 리스너를 localhost에 유지하여 서버를 인터넷에 개방하기 전에 역방향 프록시 뒤에 HTTPS 및 페더레이션을 배치할 수 있도록 합니다.

Synapse는 Matrix 홈서버로, 계정, 채팅방, 이벤트 및 미디어를 저장합니다. Docker Compose는 하나의 YAML 파일에서 Synapse 및 PostgreSQL 컨테이너를 실행합니다. 이는 단일 머신 환경을 위한 시작점이며, 완전한 공개 Matrix 배포 환경은 아닙니다.

시작하기 전에

Docker Engine과 Docker Compose 플러그인을 설치한 다음 제대로 docker compose version작동하는지 확인하십시오. Docker Desktop은 Windows 및 macOS에서 Compose를 포함하고 있으며, Linux 사용자는 Docker 패키지 저장소에서 Compose 플러그인을 설치할 수 있습니다. Docker의 Compose 설치 지침을 참조하십시오 .

설정을 생성하기 전에 영구적인 Matrix 서버 이름을 선택하십시오. 이 이름은 사용자 ID(예: `<matrix_server_name>`)에 표시되며 @alex:matrix.example.org, 나중에 변경하는 것은 일반적인 호스트 이름 편집이 아닙니다. 이 예에서 ` matrix.example.org<matrix_server_name>`은 Matrix 서버 이름이자 공용 호스트 이름입니다. 공용 서버의 경우 DNS 레코드를 호스트로 지정하고 HTTPS 역방향 프록시를 설정하십시오. Synapse에서 생성된 8008번 포트의 HTTP 리스너는 로컬 테스트에 적합하지만, 실제 사용에는 HTTPS가 필요하다고 설치 설명서에 명시되어 있습니다.

1. 프로젝트와 비밀번호를 생성하세요

Docker 호스트에 작업 디렉터리와 영구 폴더를 생성합니다. 작업 synapse디렉터리에는 생성된 구성 파일과 서명 키가 저장되고, 영구 폴더에는 data/postgres데이터베이스 파일이 저장됩니다.

mkdir -p ~/matrix-synapse/synapse ~/matrix-synapse/data/postgres
cd ~/matrix-synapse
umask 077
openssl rand -hex 32

명령의 출력을 새 .env파일 에 복사합니다 DB_PASSWORD=.... 이 파일은 비공개로 유지하고 안전한 백업을 만드십시오. Compose는 .envCompose 파일 내의 치환 값을 읽습니다. Synapse는 해당 변수를 자동으로 확장하지 않습니다 homeserver.yaml. 3단계에서 이 구성 파일에도 동일한 암호를 입력해야 합니다.

docker-compose.yml 파일, 환경 변수 파일, Synapse 구성 폴더 및 데이터 폴더를 포함하는 matrix-synapse 프로젝트 디렉터리의 터미널 화면을 보여주는 예시입니다.
프로젝트 폴더는 Compose 정의, Synapse 구성 및 영구 데이터베이스 파일을 구분합니다.

2. 두 가지 서비스를 정의하십시오.

프로젝트 디렉터리에 파일을 생성합니다 docker-compose.yml. 이 예제에서는 Element HQ에서 게시한 공식 Synapse 이미지와 PostgreSQL 16을 사용합니다. Synapse 포트는 모든 네트워크 인터페이스가 아닌 루프백 인터페이스에 바인딩됩니다. 상태 확인 기능을 통해 Compose는 Synapse를 시작하기 전에 PostgreSQL이 완료될 때까지 기다립니다.

services:
  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    environment:
      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
    volumes:
      - ./synapse:/data
    ports:
      - "127.0.0.1:8008:8008"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5

1단계에서 생성한 임의 값을 사용하여 값을 입력하십시오 DB_PASSWORD=your-generated-value. .env이 파일을 소스 제어 시스템에 커밋하지 마십시오. 나중에 PostgreSQL의 주요 버전을 변경하는 경우, 기존 데이터 디렉터리를 최신 이미지로 지정하는 대신 PostgreSQL의 업그레이드 절차를 따르십시오.

3. Synapse 구성을 생성하고 PostgreSQL을 선택합니다.

마운트된 디렉터리에 초기 구성 및 서명 키를 생성합니다 synapse. 위에서 선택한 것과 동일한 서버 이름을 사용하십시오. 통계 옵션을 명시적으로 설정하십시오. 설정은 다음과 같습니다 no.

docker compose run --rm --no-deps \
  -e SYNAPSE_SERVER_NAME=matrix.example.org \
  -e SYNAPSE_REPORT_STATS=no \
  synapse generate

공식 컨테이너 generate모드는 homeserver.yaml필요한 서명 키를 생성합니다. synapse/homeserver.yaml해당 SQLite 데이터베이스 섹션을 열고 다음 내용으로 교체하십시오. PASTE_THE_SAME_DB_PASSWORD_HERE는 에 저장된 정확한 값으로 교체해야 합니다 .env. 이 필드는 Compose 보간이 아닌 Synapse 구성 값의 리터럴입니다.

database:
  name: psycopg2
  args:
    user: synapse
    password: PASTE_THE_SAME_DB_PASSWORD_HERE
    dbname: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10
psycopg2를 통해 PostgreSQL이 구성되고, 데이터베이스는 Synapse, 호스트는 db, 포트는 5432, 연결 풀이 설정된 homeserver.yaml 편집기 화면 예시입니다.
Synapse 데이터베이스 섹션은 PostgreSQL의 내부 포트에서 실행되는 Compose 서비스 이름(db)을 가리킵니다.

생성된 파일은 registration_shared_secret비공개로 유지하세요. Synapse는 이 파일을 명령줄 사용자 등록 도구에 사용하므로, 이 파일을 얻은 사람은 관리자를 포함한 누구든지 계정을 생성할 수 있습니다. 공개 등록은 의도적으로 제공하려는 경우가 아니라면 비활성화 상태로 유지하고, 공개 등록 시 발생할 수 있는 악용 방지 조치에 대한 검토가 완료된 경우에만 사용하세요.

4. Synapse를 시작하고 로그를 확인합니다.

해당 디렉터리에서 docker-compose.ymlCompose 파일의 유효성을 검사하고 서비스를 시작하십시오.

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 synapse db

첫 번째 명령은 Compose가 파일을 구문 분석하고 해결할 수 있는지 확인합니다 DB_PASSWORD. 다음 명령은 백그라운드에서 데이터베이스와 홈 서버를 시작합니다. 데이터베이스 연결 오류 또는 구성 파일 누락이 있는지 로그를 확인하십시오. 이 설정은 로컬 폴더를 바인드 마운트하므로 컨테이너를 다시 생성해도 데이터베이스 및 Synapse 구성이 유지됩니다.

Synapse 스택을 시작하기 위해 `docker compose up -d` 명령어를 입력한 터미널 프롬프트 예시입니다.
구성 파일을 생성하고 검토한 후 Synapse 및 PostgreSQL 서비스를 시작하십시오.

5. 로컬 엔드포인트를 확인하고 계정을 생성합니다.

Docker 호스트에서 Matrix 클라이언트 버전 요청을 실행하십시오. JSON 응답이 오면 클라이언트 API가 정상적으로 응답하는 것입니다. 빈 응답, 연결 거부 또는 HTTP 오류가 발생하면 Synapse 로그를 확인하여 8008번 포트가 실행 중인지 확인해야 합니다.

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

응답이 오면 대화형으로 초기 사용자를 생성합니다. 이 명령은 사용자 이름과 암호를 입력하라는 메시지를 표시합니다. 관리자 계정이 특별히 필요한 경우가 아니면 관리자 항목에는 "아니요"를 선택하십시오.

docker compose exec synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008
로컬호스트 포트 8008에서 Synapse의 Matrix 클라이언트 버전 엔드포인트로 curl 요청을 보내는 예시 터미널 프롬프트입니다.
버전 엔드포인트 응답이 성공적이면 Synapse가 로컬에서 응답하고 있음을 확인시켜 줍니다. 이 샘플 프롬프트는 테스트 결과가 아닌 확인 과정을 보여줍니다.

안전하게 접근할 수 있도록 하세요

localhost 전용 포트 매핑은 의도적인 것입니다. 암호화되지 않은 HTTP 리스너에 대한 직접적인 공개 액세스를 방지하기 위함입니다. 원격 클라이언트의 경우, 유효한 TLS 인증서가 있는 역방향 프록시를 구성하고 Matrix 경로를 Synapse로 포워딩하십시오. 프록시는 `@True` X-Forwarded-For및 `@ X-Forwarded-ProtoExport` 헤더를 전달해야 합니다. 생성된 리스너 구성에서 x_forwarded: true포트 8008에 대해 `@True`를 활성화하십시오. 컨테이너화된 Synapse 리스너가 `@True`에만 바인딩되도록 설정하지 마십시오 127.0.0.1. 이렇게 하면 프록시 컨테이너가 해당 리스너에 접근할 수 없게 됩니다. 역방향 프록시도 컨테이너화된 경우, 프록시와 Synapse를 공유 Docker 네트워크에 배치하고 서비스 이름 `@True`로 프록시하십시오 synapse:8008.

페더레이션은 로컬 시작과 별개입니다. 다른 Matrix 서버는 일반적으로 8448 포트 또는 위임된 HTTPS 검색을 통해 사용자의 서버를 검색하고 연결해야 합니다. DNS, 역방향 프록시 라우팅 및 필요한 모든 .well-known레코드는 선택한 서버 이름과 일치해야 합니다. 공개 홈서버를 설정하기 전에 Synapse의 역방향 프록시 문서 및 설치 지침을 따르십시오 . 음성 및 화상 통화를 위한 안정적인 미디어 연결을 위해서는 TURN 서버도 필요합니다.

Synapse가 PostgreSQL에 연결할 수 없는 경우, (Compose 서비스 이름) host이 올바른지, 두 암호가 정확히 일치하는지, 데이터베이스 컨테이너가 정상인지 확인하십시오. 엔드포인트에 연결할 수 없는 경우, Synapse 로그를 확인하고 다른 서비스가 호스트 포트 8008을 이미 사용하고 있는지 확인하십시오. PostgreSQL 데이터 디렉터리와 Synapse 구성 및 서명 키를 모두 백업하십시오. 서명 키는 서버의 ID를 확인하는 데 필수적입니다.dbdocker compose ps

PostgreSQL 구성에 대한 자세한 내용은 Synapse의 PostgreSQL 가이드를 참조하십시오 . 컨테이너 옵션 및 사용자 생성에 대해서는 Synapse의 공식 Docker 문서를 참조하십시오 .

댓글 남기기

사용자 지정 Matrix Room 별칭을 도메인에 설정하세요

Element 또는 Matrix API를 사용하여 권한, Synapse 명명 및 연동을 확인하고 Matrix 회의실에 도메인에서 쉽게 공유할 수 있는 주소를 부여하세요.

안정적인 Matrix 음성 및 영상 통화를 위해 coturn을 설정하세요.

coturn과 Synapse를 일치하는 TURN 자격 증명으로 구성하고, 필요한 릴레이 포트를 열고, Matrix 클라이언트가 릴레이 후보를 가져올 수 있는지 확인합니다.

Docker Compose 및 PostgreSQL을 사용하여 Matrix Synapse를 배포하세요.

Docker Compose 및 PostgreSQL을 사용하여 Matrix Synapse를 배포하세요.

Docker Compose, PostgreSQL, 비공개 설정 파일, 그리고 HTTPS를 통해 노출하기 전에 필요한 검사 기능을 사용하여 Synapse 홈 서버를 영구적으로 설정합니다.

Element Web의 테마와 브랜딩을 맞춤 설정하세요

Element 웹 배포에 브랜드 이름, 사용자 지정 색상 및 로그인 자산을 설정하는 동시에 Element 브랜드로 유지되는 부분을 파악하세요.

추측 없이 Synapse의 Systemd 파일 제한을 늘리는 방법

추측 없이 Synapse의 Systemd 파일 제한을 늘리는 방법

Synapse가 프로세스별 파일 열기 제한에 도달했는지 진단하고, 해당 서비스 또는 워커에 대한 systemd 드롭인을 설정하고, 실제 제한을 확인합니다.

요소에 "복호화 실패" 오류가 표시되나요? 누락된 룸 키를 복구하세요.

요소에 "복호화 실패" 오류가 표시되나요? 누락된 룸 키를 복구하세요.

오류가 특정 브라우저 또는 특정 이벤트에만 국한되는지 확인한 다음, Element의 복구 키 또는 신뢰할 수 있는 장치를 사용하여 암호화된 나머지 기록을 손상시키지 않고 복구할 수 있습니다.

데이터 손실 없이 오래된 Synapse 메시지와 미디어를 정리하세요

Synapse의 기록 및 미디어 삭제 API 또는 보존 설정을 사용하여 오래된 데이터를 안전하게 제거한 다음 완료 여부와 디스크 공간 복구를 확인하십시오.

Simple-Matrix-Bot-Lib을 사용하여 Python으로 Matrix Echo Bot을 구축하세요.

Simple-Matrix-Bot-Lib을 사용하여 Python으로 Matrix Echo Bot을 구축하세요.

최신 라이브러리를 설치하고, 전용 Matrix 계정을 연결한 다음, 더욱 안전한 자격 증명 처리와 명확한 테스트를 포함하는 간단한 !echo 봇을 실행하세요.

Matrix를 WhatsApp, Telegram, Discord에 각각 별도의 브리지로 연결하세요.

Matrix를 WhatsApp, Telegram, Discord에 각각 별도의 브리지로 연결하세요.

등록, 로그인 및 테스트가 각각 다른 세 개의 Mautrix 브리지를 설정하여 Docker 네트워킹, 계정 정책 및 동기화 관련 예상치 못한 문제를 방지하세요.

공유 파일을 손상시키지 않고 Synapse 미디어 디스크 공간을 확보하세요

Synapse 저장소를 채우는 항목을 찾고, 안전한 미디어 보존 설정을 지정하고, 디스크에서 파일을 직접 삭제하지 않고 원격 캐시를 정리하세요.