Skip to content

Installation Guide

Catalogerr can be installed in two ways:

  • One-line installer (recommended) — sets up everything automatically.
  • Manual setup — for advanced users who want more control.

One-Line Installer (New in v1.1.3)

Catalogerr now ships with an installer script that handles the entire setup.

Run this command on your server:

curl -sSL https://raw.githubusercontent.com/CipherWorkZ/Catalogerr_live/main/install.sh | sudo bash

The installer will:

  • Download the latest release archive
  • Create /etc/Catalogerr_live with proper permissions
  • Generate .env and config.yaml
  • Prompt you for an admin password
  • Run admin.py to seed the database
  • Create and enable catalogerr-api.service (systemd + Gunicorn)

Note: The installer is still experimental — please report issues on GitHub.

Manual Setup Instructions

If you prefer manual setup, you need to configure a .env file and a config.yaml.

1. Environment Variables

Create a file named .env in the project root:

# --- Sonarr Integration ---
SONARR_URL=http://<your-sonarr-host>:8989
SONARR_API_KEY=<your-sonarr-api-key>

# --- Radarr Integration ---
RADARR_URL=http://<your-radarr-host>:7878
RADARR_API_KEY=<your-radarr-api-key>

# --- Application Secrets ---
APP_API_KEY=<random-secret-key>
TMDB_API_KEY=<your-tmdb-api-key>

# --- Admin Login ---
ADMIN_USER=admin
ADMIN_PASSWORD=<choose-a-strong-password>

# --- Database ---
DB_FILE=index.db

# --- Application Metadata ---
APP_NAME=Catalogerr
APP_VERSION=1.1.3
INSTANCE_NAME=MyServer

# --- Runtime Information (for system status endpoint) ---
RUNTIME_VERSION=Python 3.12
OS_NAME=Ubuntu
OS_VERSION=22.04

2. Configure Media Paths

Create config.yaml in the project root:

parent_paths:
  - name: movies
    path: /path/to/movies
  - name: tvshows
    path: /path/to/tvshows
  - name: archive
    path: /path/to/archive

3. Initialize the Database

Run the following to seed the database and create the first admin:

python3 admin.py

4. Start the Server

For development:

python3 main.py

For production (Gunicorn):

gunicorn -w 4 -b 0.0.0.0:8008 main:app

If you used the installer, Catalogerr runs automatically under systemd:

systemctl status catalogerr-api.service

Features Installed

  • Drive indexing & storage tracking
  • Metadata enrichment via TMDB
  • Poster caching
  • Collection dashboards
  • Backup awareness
  • ARR ecosystem connectors (Sonarr/Radarr)
  • Servarr-style dashboard
  • Backup/restore support
  • Built-in Changelog viewer
  • Auto-installer (systemd + Gunicorn)

Project Structure (for reference)

Catalogerr_live/
├── routes/         # Flask blueprints (catalog, system, tasks, stats, auth, connectors, etc.)
├── services/       # Core logic (auth, tasks, jobs, settings, stats, utils)
├── modules/        # Connector + poster handling
├── static/         # Shared static files (js/api.js, logos, posters)
├── templates/      # Jinja2 templates (dashboard, catalog, tasks, settings, stats, changelog)
├── admin.py        # Initialization script
├── install.sh      # Auto installer (v1.1.3+)
├── main.py         # Flask app entrypoint
└── config.yaml     # Media paths config

Get Involved

Catalogerr is being built openly.
- 🌐 Website: catalogerr.patserver.com
- 💻 GitHub: CipherWorkZ/Catalogerr_live

Contributions and feedback are welcome!