Docker Jacred-FDB

Available languages: English | Russian

A Docker image for Jacred - a torrent tracker aggregator that provides a unified API for multiple torrent trackers. This containerized implementation offers enhanced security, multi-architecture support, and automated CI/CD workflows.

🚀 Features

• Multi-Architecture Support: Available for amd64, arm64, and arm platforms
• Security-First: Non-root user execution, minimal attack surface
• Robust Operations: Health checks, graceful shutdown, signal handling
• Automated CI/CD: Semantic versioning with automated releases
• SBOM & Attestations: Supply chain security with SLSA attestations
• Optimized Build: Self-contained .NET 9 binary with AOT compilation
• Configuration Management: Persistent configuration with volume mounts

📋 Quick Start

Docker Run

docker run -d \
  --name jacred \
  -p 9117:9117 \
  -v jacred-config:/app/config \
  -v jacred-data:/app/Data \
  --restart unless-stopped \
  ghcr.io/pavelpikta/jacred-fdb:latest

Docker Compose

name: jacred

services:
  jacred:
    image: ghcr.io/pavelpikta/jacred-fdb:latest
    container_name: jacred
    restart: unless-stopped
    ports:
      - "9117:9117"
    volumes:
      - jacred-config:/app/config
      - jacred-data:/app/Data
    environment:
      - TZ=Europe/London
      - UMASK=0027
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--spider", "http://127.0.0.1:9117"]
      interval: 30s
      timeout: 15s
      retries: 3
      start_period: 45s
    deploy:
      resources:
        limits:
          memory: 2048M

volumes:
  jacred-config:
  jacred-data:

🐳 Available Images

Registries

Registry	Image	Description
GitHub Container Registry	ghcr.io/pavelpikta/jacred-fdb	Latest builds with attestations
GitHub Container Registry	ghcr.io/pavelpikta/jacred-fdb:v1.0.0	Specific version example
GitHub Container Registry	ghcr.io/pavelpikta/jacred-fdb:1.0.0	Specific version example

Tags

Tag	Description	Update Frequency
latest	Latest stable release from main branch	On new releases
develop	Development builds from develop branch	On each commit
v1.2.3	Specific semantic version	Immutable
1.2.3	Specific semantic version	Immutable
sha-abcd123	Specific commit SHA	Immutable

⚙️ Configuration

Environment Variables

Variable	Default	Description
TZ	UTC	Container timezone
UMASK	0027	File creation mask
ASPNETCORE_URLS	http://0.0.0.0:9117	Application listen address
ASPNETCORE_ENVIRONMENT	Production	ASP.NET Core environment

Volumes

Path	Purpose	Required
/app/config	Configuration files	✅
/app/Data	Application data and logs	✅

Initial Configuration

The container automatically creates an initial configuration file (init.conf) on first run:

{
  "listenip": "any",
  "listenport": 9117,
  "apikey": "",
  "mergeduplicates": true,
  "openstats": true,
  "opensync": true,
  "log": false,
  "syncapi": "http://redapi.cfhttp.top",
  "synctrackers": ["rutracker", "rutor", "kinozal", "nnmclub", "megapeer", "bitru", "toloka", "lostfilm", "baibako", "torrentby", "selezen"],
  "disable_trackers": ["hdrezka", "anifilm", "anilibria"],
  "syncsport": false,
  "syncspidr": true,
  "maxreadfile": 200,
  "tracks": false,
  "tracksdelay": 20000,
  "tsuri": ["http://127.0.0.1:8090"],
  "timeStatsUpdate": 30,
  "timeSync": 60,
  "evercache": {
    "enable": false,
    "validHour": 1,
    "maxOpenWriteTask": 200,
    "dropCacheTake": 200
  }
}

Configuration Lifecycle

• First start copies the bundled /app/init.conf into the persisted /app/config/init.conf volume.
• Subsequent starts keep your changes by syncing /app/config/init.conf back to /app/init.conf before Jacred launches.
• Edit the file in the mounted volume, then restart the container to apply configuration updates.

Data Layout

Path	Contents
/app/Data/fdb	Jacred database files
/app/Data/temp	Temporary files such as stats.json
/app/Data/tracks	Tracker cache and intermediate data
/app/config/init.conf	Persisted runtime configuration

🏗️ Build Information

Build Arguments

Argument	Default	Description
ALPINE_VERSION	3.22.2	Base Alpine Linux version
JACRED_VERSION	dd15c374...	Jacred source commit SHA
DOTNET_VERSION	9.0	.NET runtime version

Multi-Stage Build

The Docker image uses a multi-stage build process:

1. Builder Stage: Compiles Jacred from source using .NET 9 SDK
2. Runtime Stage: Minimal Alpine Linux with only required dependencies

Optimization Features

• Self-contained deployment (no .NET runtime required)
• Single-file executable with compression
• Ahead-of-time (AOT) compilation optimizations
• Trimmed runtime dependencies

🔒 Security

Container Security

• Non-root execution: Runs as user jacred (UID: 1000)
• Minimal attack surface: Alpine Linux base with essential packages only
• Read-only filesystem: Application binaries are read-only
• Signal handling: Graceful shutdown on SIGTERM/SIGINT

Supply Chain Security

• SBOM Generation: Software Bill of Materials for dependency tracking
• SLSA Attestations: Build provenance and integrity verification
• Dependency Updates: Automated via Dependabot
• Security Scanning: Integrated vulnerability assessment

Verification

Verify image signatures and attestations:

# Install cosign
curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64"
sudo mv cosign-linux-amd64 /usr/local/bin/cosign
sudo chmod +x /usr/local/bin/cosign

# Verify attestation
cosign verify-attestation \
  --type slsaprovenance \
  --certificate-identity-regexp 'https://github\.com/pavelpikta/docker-jacred-fdb/\.github/workflows/.+' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/pavelpikta/jacred-fdb:latest

🚦 Health Checks

The container includes a built-in health check that verifies the application is responding:

HEALTHCHECK --interval=30s \
    --timeout=15s \
    --start-period=45s \
    --retries=3 \
    --start-interval=5s \
    CMD wget --quiet --spider http://127.0.0.1:9117 || exit 1

📊 Monitoring

Application Logs

# View real-time logs
docker logs -f jacred

# View logs with timestamps
docker logs -t jacred

Health Status

# Check container health
docker inspect jacred --format='{{.State.Health.Status}}'

# View health check logs
docker inspect jacred --format='{{range .State.Health.Log}}{{.Output}}{{end}}'

🔧 Troubleshooting

Common Issues

Container Won't Start

# Check container logs
docker logs jacred

# Verify volume mounts
docker inspect jacred --format='{{range .Mounts}}{{.Source}}:{{.Destination}} {{.Mode}}{{end}}'

Permission Issues

# Fix volume permissions
sudo chown -R 1000:1000 /path/to/your/volumes

Configuration Problems

# Recreate default configuration
docker exec jacred rm -f /app/config/init.conf
docker restart jacred

Debug Mode

Run container with debug output:

docker run --rm -it \
  -p 9117:9117 \
  -v jacred-config:/app/config \
  ghcr.io/pavelpikta/jacred-fdb:latest \
  /bin/sh

🔄 Updates

• Pull the latest image: docker pull ghcr.io/pavelpikta/jacred-fdb:latest
• Recreate the container so the new image starts while reusing existing volumes.
• Confirm the version by reviewing the startup banner in docker logs jacred.

💾 Backup & Restore

• Backup configuration:

  docker run --rm \
    -v jacred-config:/app/config \
    -v "$(pwd)":/backup \
    alpine tar czf /backup/jacred-config.tar.gz -C /app config

• Backup data by swapping the volume for -v jacred-data:/app/Data and adjusting the archive name.

• Restore by extracting the archives into the respective named volumes before starting the container.

🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

Development Workflow

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Commit your changes using Conventional Commits:

   git commit -m "feat: add amazing new feature"

4. Push to the branch: git push origin feature/amazing-feature

5. Open a Pull Request

Commit Convention

We use Conventional Commits for automated versioning:

• feat: - New features (minor version bump)
• fix: - Bug fixes (patch version bump)
• docs: - Documentation changes
• ci: - CI/CD changes
• chore: - Maintenance tasks
• BREAKING CHANGE: - Breaking changes (major version bump)

Local Development

# Clone the repository
git clone https://github.com/pavelpikta/docker-jacred-fdb.git
cd docker-jacred-fdb

# Build locally
docker build -t jacred-fdb:local .

# Test the build
docker run --rm -p 9117:9117 jacred-fdb:local

📄 License

This project is licensed under the Apache License 2.0.

🙏 Acknowledgments

• Jacred-FDB - The amazing torrent tracker aggregator
• Alpine Linux - Secure, lightweight base image
• GitHub Actions - CI/CD automation
• Semantic Release - Automated versioning

---

If this project helped you, please consider giving it a ⭐!