booksarestillbetter/synapse repository overview

docker run -d \
  --name synapse \
  --network host \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=UTC \
  -v ./config:/etc/synapse \
  -v ./session:/var/lib/synapse \
  -v ./data:/data \
  -v ./media:/media \
  --ulimit nofile=65535:65535 \
  --restart unless-stopped \
  booksarestillbetter/synapse:latest

services:
  synapse:
    image: booksarestillbetter/synapse:${TAG:-latest}
    container_name: synapse
    restart: unless-stopped
    # Host networking is the right default for a BitTorrent daemon specifically: the peer
    # listen port is then exactly the port a router/firewall rule forwards, with no Docker NAT
    # layer complicating inbound peer connections. Switch to a bridge network + explicit `ports:`
    # below if you'd rather keep it isolated (you'll need to port-forward the peer port yourself).
    network_mode: "host"
    environment:
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      - TZ=${TZ:-UTC}
      - SYNAPSE_CONFIG=/etc/synapse/synapse.toml
    volumes:
      # Config directory (auto-seeds a default synapse.toml here if missing)
      - ${SYNAPSE_CONFIG_DIR:-./config}:/etc/synapse
      # Session/state directory (resume data, encrypted session store)
      - ${SYNAPSE_SESSION_DIR:-./session}:/var/lib/synapse
      # Data directory — covers downloads, incomplete, and watch under one mount
      - ${SYNAPSE_DATA_DIR:-./data}:/data
      # Optional: a separate directory a front-end can watch for completed files (only used if
      # you enable [lifecycle] staging/hardlinking or a completion webhook).
      - ${SYNAPSE_MEDIA_DIR:-./media}:/media
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
    healthcheck:
      test: [ "CMD-SHELL", "curl -fsS http://127.0.0.1:8080/api/v1/health 2>/dev/null || pidof synapsed >/dev/null || exit 1" ]
      interval: 30s
      timeout: 5s
      retries: 3

# Stage 1: Build — full Rust toolchain, workspace compiled from source.
# io_uring is a runtime concern (needs a 5.1+ host kernel; synapse-diskio falls back to
# POSIX I/O automatically when it isn't available), not a build-time one, so no special
# kernel/headers requirement here beyond a normal Rust build environment.
FROM rust:1.94-slim-bookworm AS builder
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends pkg-config protobuf-compiler libssl-dev && rm -rf /var/lib/apt/lists/*

COPY Cargo.toml Cargo.lock ./
COPY crates/ ./crates/
RUN cargo build --release -p synapsed

# Stage 2: Runtime — minimal Debian base, just the one binary and CA certs (tracker
# announces over HTTPS need them).
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl gosu && rm -rf /var/lib/apt/lists/*

COPY --from=builder /app/target/release/synapsed /usr/local/bin/synapsed

# Default config template (stored outside of /etc/synapse so volume mounts cannot mask it)
RUN mkdir -p /usr/share/synapse
COPY example_config.toml /usr/share/synapse/synapse.toml.default
COPY example_config.toml /etc/synapse.default.toml
COPY example_config.toml /etc/synapse/synapse.toml.default

RUN useradd --system --create-home --home-dir /var/lib/synapse synapse \
    && mkdir -p /data/downloads /var/lib/synapse/session /etc/synapse /media \
    && chown -R synapse:synapse /data /var/lib/synapse /etc/synapse /media /usr/share/synapse

COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

VOLUME ["/data", "/var/lib/synapse"]

# gRPC control plane, REST/Swagger/metrics, BitTorrent peer port (TCP+UDP).
EXPOSE 50051 8080 54345 54345/udp

# Healthcheck probes HTTP health if enabled, or falls back to verifying synapsed is running.
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
  CMD curl -fsS http://127.0.0.1:8080/api/v1/health 2>/dev/null || pidof synapsed >/dev/null || exit 1

WORKDIR /var/lib/synapse
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]