✨ Features

🔐 Security Architecture

Zero-Knowledge Authentication (ZKE)

Trackarr uses a Zero-Knowledge authentication system: the server never sees or stores your password. All cryptographic operations happen client-side.

┌─────────────────────────────────────────────────────────────────────┐
│                        REGISTRATION FLOW                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────┐                              ┌─────────────────┐  │
│  │   CLIENT    │                              │     SERVER      │  │
│  └──────┬──────┘                              └────────┬────────┘  │
│         │                                              │           │
│         │ 1. Solve PoW Challenge (anti-spam)           │           │
│         │ ◄────────────────────────────────────────────┤           │
│         │                                              │           │
│         │ 2. Generate random salt (32 bytes)           │           │
│         │ 3. Derive key = PBKDF2(password, salt)       │           │
│         │ 4. Compute verifier = SHA256(key)            │           │
│         │                                              │           │
│         │ 5. Send {username, salt, verifier} ─────────►│           │
│         │    Password NEVER leaves client           │           │
│         │                                              │           │
│         │                              6. Store salt + │           │
│         │                                 verifier     │           │
│         │                              7. Create session           │
│         │ ◄──────────────────────────────── 8. OK ─────┤           │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                          LOGIN FLOW                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────┐                              ┌─────────────────┐  │
│  │   CLIENT    │                              │     SERVER      │  │
│  └──────┬──────┘                              └────────┬────────┘  │
│         │                                              │           │
│         │ 1. Request challenge ───────────────────────►│           │
│         │                                              │           │
│         │ ◄──────── 2. Return {salt, challenge} ───────┤           │
│         │                                              │           │
│         │ 3. Derive key = PBKDF2(password, salt)       │           │
│         │ 4. Compute verifier = SHA256(key)            │           │
│         │ 5. Generate proof = SHA256(verifier+challenge)           │
│         │                                              │           │
│         │ 6. Send {username, proof, challenge} ───────►│           │
│         │    Password NEVER leaves client           │           │
│         │                                              │           │
│         │                       7. Compute expected =  │           │
│         │                          SHA256(storedVerifier+challenge)│
│         │                       8. Verify proof == expected        │
│         │ ◄──────────────────────────────── 9. Session ┤           │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Key Properties:

• Password never transmitted — Only cryptographic proofs
• PBKDF2 with 100k iterations — Brute-force resistant
• Unique challenge per login — Prevents replay attacks
• Proof of Work — Stops automated registration attacks

🚨 Panic Mode (Emergency Encryption)

The Panic Button allows administrators to instantly encrypt all sensitive data in an emergency. Once activated, all torrent files become unusable and user data is unreadable.

┌───────────────────────────────────────────────────────────────────┐
│                       NORMAL STATE                                │
│  • Torrents downloadable                                          │
│  • User data readable                                             │
│  • Posts & comments visible                                       │
└───────────────────────────────────────────────────────────────────┘
                              │
                    PANIC ACTIVATED
                              │
                              ▼
┌───────────────────────────────────────────────────────────────────┐
│                      ENCRYPTED STATE                              │
│  • .torrent files → AES-256-GCM encrypted (unusable)              │
│  • Torrent names  → [ENCRYPTED]                                   │
│  • Torrent sizes  → 0                                             │
│  • User credentials → Encrypted                                   │
│  • Forum posts    → Encrypted                                     │
└───────────────────────────────────────────────────────────────────┘
                              │
                    RESTORE (with password)
                              │
                              ▼
┌───────────────────────────────────────────────────────────────────┐
│                       RESTORED STATE                              │
│  All data restored to original state                              │
└───────────────────────────────────────────────────────────────────┘

How it works:

1. First admin sets a Panic Password during registration (min. 12 chars)
2. Panic password is hashed and stored securely (never in plaintext)
3. Activation: Admin → Settings → Panic → Type ENCRYPT_ALL_DATA
4. Restoration: Enter the original Panic Password

Encryption details: | Component | Algorithm | |-----------|-----------| | Key Derivation | scrypt (32 bytes) | | Encryption | AES-256-GCM | | IV | 16 bytes random (per session) |

WARNING: Without the Panic Password, encrypted data is permanently lost. There is no recovery mechanism.

🚀 Quick Start

Prerequisites

• Node.js 20+ • Docker & Docker Compose • npm

DNS Configuration (Required before installation)

IMPORTANT: Before running the installer, you must configure your DNS records to point to your VPS IP address.

Create the following A records pointing to your server's IP:

Note: DNS propagation can take up to 24-48 hours, but usually completes within a few minutes. The installer will fail to obtain SSL certificates if DNS is not properly configured.

Option 1: Automated Installation (Recommended)

Best for production deployments. Handles dependencies, secrets, SSL, and systemd automatically.

# Download and run the installer
curl -fsSL https://raw.githubusercontent.com/florianjs/trackarr/main/scripts/install.sh -o install.sh
chmod +x install.sh
sudo ./install.sh

The installer will:

• Install Docker and dependencies
• Generate cryptographic secrets
• Configure firewall rules
• Set up TLS/SSL with Let's Encrypt
• Create systemd service for auto-restart
• Configure PostgreSQL, Redis, Caddy, and monitoring
• Set up Prometheus + Grafana monitoring

Monitoring: After installation, Grafana is accessible at https://monitoring.your-domain.com/grafana

Default credentials: admin / admin (you'll be prompted to change on first login) Having issues with the password ? Just launch :

cd /opt/trackarr
docker exec -it trackarr-grafana grafana cli admin reset-admin-password <new-password>

Option 2: Development with Docker

Databases are only exposed to the container network for security.

# Clone repository
git clone https://github.com/florianjs/trackarr.git && cd trackarr
cp .env.example .env

# Start all services (app + postgres + redis)
docker compose up -d

# View logs
docker compose logs -f app

Open http://localhost:3000

🔒 Security

For production, always use the install script to ensure proper secret generation and security configuration.

Key Security Features

Rate Limits

Production Security Checklist

Use install.sh — it handles security automatically:

• Generates cryptographic secrets (32-64 chars)
• Configures TLS for all connections
• Sets up Caddy reverse proxy with HTTPS
• Configures firewall (ports 80, 443 only)
• Network isolation (databases not exposed)

Manual steps after install:

• [ ] Set up automated PostgreSQL backups

🏗️ Tech Stack

🐳 Docker Commands

docker compose up -d              # Start services
docker compose down               # Stop services
docker compose logs -f            # View logs
docker compose down -v            # Stop + remove volumes

Health Checks

docker exec trackarr-db pg_isready           # PostgreSQL
docker exec trackarr-redis redis-cli ping    # Redis

Updating

To update your Trackarr installation to the latest version:

cd /opt/trackarr
git checkout main
git pull origin main
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d --build

Note: This will rebuild the containers with the latest code. Your data (PostgreSQL, Redis) is persisted in Docker volumes and will not be affected.

Troubleshooting

Full restart (stop and start all services):

cd /opt/trackarr
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d

Full restart with rebuild (if you suspect issues with cached images):

cd /opt/trackarr
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d --build --force-recreate

View logs to debug issues:

docker compose -f docker-compose.prod.yml logs -f
docker compose -f docker-compose.prod.yml logs -f app  # App only

🧪 Development

npm run dev              # Start dev server (HMR)
npm run build            # Production build
npx drizzle-kit push     # Push schema changes
npx drizzle-kit studio   # Database GUI

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

🙏 Acknowledgements

Trackarr is built on the shoulders of giants. We'd like to thank the following open source projects:

👥 Contributors

Thanks to all our contributors! Sorted by number of commits.

Avatar	Contributor	Commits
	Dim145	4
	IkiaeM	4

📄 License

MIT License — see LICENSE for details.