Synch

Cloudflare 없이 Synch 자체 호스팅

Docker Compose 또는 일반 systemd로 자신의 하드웨어에서 Synch 서버를 실행하세요. Cloudflare나 타사 서비스가 필요하지 않습니다.

Cloudflare를 전혀 사용하고 싶지 않다면 Synch 서버를 일반 Node.js 프로세스로 실행할 수도 있습니다. 이 가이드는 홈랩 NAS, 소형 VPS, Incus/LXC 컨테이너처럼 장시간 프로세스를 실행하고 포트를 노출할 수 있는 자신의 하드웨어에서 Docker Compose 또는 systemd를 사용해 Synch를 실행하는 방법을 설명합니다.

데이터는 모두 디스크에 저장됩니다. 볼트마다 SQLite 파일 하나가 생성되고, 계정과 볼트 메타데이터를 위한 작은 앱 데이터베이스가 추가됩니다. D1, Durable Objects, R2는 필요하지 않으며, 직접 관리하는 디렉터리에 파일만 저장됩니다.

대신 무료 Cloudflare 계정에 배포하려면 Cloudflare 자체 호스팅 가이드를 참고하세요.

배포 전 준비

어떤 방식을 선택하든 Obsidian을 사용하는 기기에서 서버에 연결할 수 있어야 합니다. 로컬 네트워크에서만 사용할 수도 있고, 집 밖에서도 동기화하려면 인터넷을 통해 접근할 수도 있습니다. 후자의 경우 reverse proxy 뒤에 TLS를 설정하세요. 서버 자체는 일반 HTTP만 사용합니다.

Docker Compose로 배포하기

Docker와 Docker Compose가 설치되어 있어야 합니다.

  1. 저장소를 복제하고 API 디렉터리로 이동합니다.

    git clone https://github.com/hjinco/synch.git
cd synch/apps/api

  2. 예시 환경 파일을 복사합니다.

    cp .env.example .env

  3. .env를 편집하고 다음 값을 입력합니다.

    • PUBLIC_URL - 클라이언트가 이 서버에 접속할 때 사용할 주소입니다. 예를 들어 LAN에서는 http://192.168.1.50:8787, reverse proxy 뒤에서는 https://synch.your-domain.example을 사용할 수 있습니다. 스킴과 포트를 포함해 정확히 일치해야 하며, 들어오는 요청의 origin을 검증하는 데 사용됩니다.

    • BETTER_AUTH_SECRET 및 SYNC_TOKEN_SECRET - 서로 독립적인 두 개의 무작위 secret입니다. 각각 다음 명령으로 생성하세요.

      openssl rand -hex 32

    • AUTH_ALLOWED_EMAILS (필수) - 계정을 만들 수 있는 정확한 이메일 주소를 쉼표로 구분해 입력합니다.

      AUTH_ALLOWED_EMAILS=you@example.com,family@example.com

      비교할 때 대소문자와 앞뒤 공백은 무시합니다. 이 설정은 신규 계정 생성만 제한하므로 목록에서 주소를 제거해도 기존 사용자는 계속 로그인할 수 있습니다.

  4. 서버를 시작합니다.

    docker compose up -d

볼트와 blob 데이터는 재시작 및 업그레이드 후에도 synch-data Docker 볼륨에 유지됩니다. 새 호스트로 옮기려면 이 볼륨과 .env 파일을 함께 복사하세요.

Blob 저장소

기본적으로 암호화된 파일 내용은 같은 데이터 볼륨 안의 디스크에 저장됩니다. AWS S3, MinIO, R2 등 S3 호환 버킷을 사용하려면 시작하기 전에 .env의 BLOB_STORAGE=s3 블록 주석을 해제하고 값을 입력하세요.

업그레이드

git pull
docker compose up -d --build

데이터베이스 마이그레이션은 시작할 때 자동으로 실행됩니다.

Docker 없이 systemd로 실행하기

서버는 단순한 Node.js 프로세스(src/self-host.ts)이며, tsx로 실행됩니다. Docker는 편의를 위한 선택 사항일 뿐 필수 조건은 아닙니다. 예를 들어 이미 VM(Incus/LXC 컨테이너 등)을 사용하고 있고 Docker를 별도 의존성으로 추가하고 싶지 않다면 이 방식을 선택할 수 있습니다.

Debian/Ubuntu에서는 install.sh가 아래 과정을 자동화합니다. 저장소를 복제한 뒤 cd apps/api && sudo ./install.sh를 실행하세요. git pull 이후 업데이트와 재시작을 위해 다시 실행해도 안전합니다. 직접 설정하려면 다음 단계를 따르세요.

  1. Node.js 24와 빌드 도구 모음을 설치합니다. better-sqlite3에 맞는 사전 빌드 바이너리가 없을 때 네이티브 모듈을 빌드하는 데 필요합니다.

    # Debian/Ubuntu
sudo apt install -y nodejs python3 make g++
sudo corepack enable

  2. 저장소를 복제하고 production 의존성을 설치합니다.

    git clone https://github.com/hjinco/synch.git /opt/synch
cd /opt/synch/apps/api
pnpm install --frozen-lockfile --filter @synch/api... --prod

  3. .env.example을 .env로 복사하고, 위 Docker Compose 단계와 동일하게 값을 입력합니다.

  4. 예시 systemd unit을 설치하고 시작합니다.

    sudo useradd --system --home /var/lib/synch-api --create-home synch
sudo cp synch-api.service.example /etc/systemd/system/synch-api.service
# /opt/synch 또는 synch 사용자를 사용하지 않았다면 unit의 경로/User/Group을 수정하세요.
sudo systemctl daemon-reload
sudo systemctl enable --now synch-api

  5. 정상 실행 중인지 확인합니다.

    curl http://localhost:8787/health
sudo journalctl -u synch-api -f

업그레이드(systemd)

cd /opt/synch
git pull
cd apps/api
pnpm install --frozen-lockfile --filter @synch/api... --prod
sudo systemctl restart synch-api

localhost에만 바인딩하기

기본적으로 서버는 0.0.0.0(모든 인터페이스)에서 수신합니다. Docker Compose가 포트 publish를 수행하려면 이 설정이 필요합니다. systemd 배포를 로컬 reverse proxy(예: tailscale serve, nginx, Caddy) 뒤에서 실행하고 서버가 LAN이나 공용 인터페이스에서 직접 접근되지 않게 하려면 .env에 HOST=127.0.0.1을 설정하세요. 예시 systemd unit과 install.sh는 이미 이 설정을 사용합니다.

변경한 뒤에는 PUBLIC_URL을 클라이언트가 실제로 연결할 주소(reverse proxy의 주소, 127.0.0.1이 아님)로 업데이트하고 서비스를 재시작하세요. PUBLIC_URL은 better-auth가 들어오는 요청의 origin을 검증할 때 사용합니다.

Obsidian 연결하기

  1. Obsidian을 엽니다.
  2. Settings로 이동합니다.
  3. Synch 설정을 엽니다.
  4. Self-hosted server에 서버의 PUBLIC_URL을 붙여 넣습니다. 끝에 /를 붙이지 마세요.
  5. Save를 클릭합니다.
  6. 평소처럼 로그인하고 vault 설정을 계속 진행합니다.