Skip to main content

Installation with Docker

Ygégé is available as an official multi-architecture Docker image. This guide explains how to deploy and configure the service.

Prerequisites​

Quick Installation​

With Docker Run​

docker run -d \
  --name ygege \
  -p 8715:8715 \
  uwucode/ygege:latest

With Docker Compose​

Create a compose.yml file:

services:
  ygege:
    image: uwucode/ygege:latest
    container_name: ygege
    restart: unless-stopped
    ports:
      - "8715:8715"
    environment:
      LOG_LEVEL: "info"
      # TMDB_TOKEN: "your_tmdb_token"  # Optional
      # USE_TOR: "true"               # Optional: enable Tor routing
      # TOR_PROXY: "127.0.0.1:9050"   # Optional: alternative Tor proxy
    healthcheck:
      test: ["CMD-SHELL", "curl --fail http://localhost:$${BIND_PORT:-8715}/health || exit 1"]
      interval: 1m30s
      timeout: 20s
      retries: 3
      start_period: 10s

Then start the service:

docker compose up -d

Configuration​

With config.json file​

Create a config.json file and mount it read-only:

{
    "bind_ip": "0.0.0.0",
    "bind_port": 8715,
    "log_level": "info",
    "tmdb_token": null,
    "use_tor": false,
    "tor_proxy": "127.0.0.1:9050"
}

With environment variables​

The following variables are supported:

VariableDescriptionDefault
BIND_IPListening IP address0.0.0.0
BIND_PORTListening port8715
LOG_LEVELLog level (trace, debug, info, warn, error)info
TMDB_TOKENTMDB API token (optional)-
USE_TOREnable Tor routing (optional)false
TOR_PROXYSOCKS5 Tor proxy address (optional)127.0.0.1:9050

Available Docker Tags​

TagDescription
latestLatest stable version
stableAlias for latest
noupxVersion without UPX compression (for Synology)
0.6.2Specific version
developDevelopment version

For systems with older architectures​

If you encounter segmentation faults on older architectures or certain NAS (like Synology), use the noupx image:

services:
  ygege:
    image: uwucode/ygege:noupx
    # ... rest of configuration

Verification​

Once the container is started, verify it's working:

curl http://localhost:8715/health

You should receive an OK response.

Security​

Non-root User​

The Ygégé Docker image runs by default with a non-root user (UID 10001) for security reasons. This ensures:

  • ✅ Compatibility with Docker and Kubernetes security policies
  • ✅ Protection against privilege escalation
  • ✅ Compliance with container security best practices

Permission Management​

"Permission denied" Error

If you get Error: Os { code: 13, kind: PermissionDenied } after updating, it's related to volume permissions.

Recommended solution: Use named volumes (already in the example above):

volumes:
  - ygege_sessions:/app/sessions  # Automatic permission management

Alternative with bind mounts: If you need to mount a local folder:

services:
  ygege:
    image: uwucode/ygege:latest
    user: "10001:10001"  # Container UID/GID
    volumes:
      - ./ygege/sessions:/app/sessions

Then set permissions:

Linux/macOS:

sudo chown -R 10001:10001 ./ygege/sessions
sudo chmod -R 755 ./ygege/sessions

Windows (PowerShell as Administrator):

icacls ".\ygege\sessions" /grant Everyone:(OI)(CI)F /T

Running with a Custom UID​

If you want to run the container with a specific UID/GID (for example to match your host user):

docker run -d \
  --name ygege \
  --user 1000:1000 \
  -p 8715:8715 \
  -v ./config:/app/sessions \
  -v ./config.json:/app/config.json \
  uwucode/ygege:latest

Or with Docker Compose:

services:
  ygege:
    image: uwucode/ygege:latest
    user: "1000:1000"  # Your UID:GID
    # ... rest of configuration
tip

Make sure mounted volumes have appropriate permissions for the specified user:

sudo chown -R 1000:1000 ./config ./sessions
Security Warning

Running as root is not recommended and may present security risks. Use this option only if you understand the implications.

If you absolutely need to run the container as root:

Docker Run:

docker run -d \
  --name ygege \
  --user 0:0 \
  -p 8715:8715 \
  uwucode/ygege:latest

Docker Compose:

services:
  ygege:
    image: uwucode/ygege:latest
    container_name: ygege
    user: "0:0"  # Root
    restart: unless-stopped
    environment:
      LOG_LEVEL: "info"
    ports:
      - "8715:8715"

With this configuration, you won't have permission issues, but you lose the security benefits of non-root mode.

Next Steps​