Welcome to Kometa Quickstart

✨ Features

Kometa Quickstart is more than just a YAML generator — it’s a full interactive environment for configuring, validating, and running Kometa. Key features include:

Multiple Ways to Run Quickstart

• Local Python: Works on Windows, macOS, and Linux
• Frozen Builds: Precompiled executables for Windows, macOS, and Linux (no Python required)
• Docker Image: Official image on Docker Hub with persistent /config volume support
• Branch Support: Choose between master (stable) and develop (bleeding-edge) branches for every runtime option

Safe Playground Mode

• Plex Test Libraries: Downloadable from the start page so you can experiment without touching production libraries
• No Risk to Production: All Quickstart data, credentials, and configs are stored locally

Config Management & History

• SQLite-Backed Storage: All configs and page data are stored in a database, so you can switch between configs at any time
• Automatic Backups: Every config is saved as a versioned .yml file for historical reference
• Download & Run Anywhere: Final configs can be downloaded and run outside Quickstart if preferred

Guided, Validated Workflow

• Step-by-Step Pages: Each section validates its own data, giving you instant feedback before proceeding
• Library Telemetry: Pulls real Plex server data (Plex Pass status, library types, agent/scanner compatibility)
• Dynamic Toggles & Templates: Rich UI for enabling collections, overlays, and builder template variables

Built-in Kometa Runner

• One-Click Execution: The final page creates a Kometa virtual environment (if needed), installs dependencies, and runs kometa.py against the generated config
• Run Command Builder: Dynamically builds and previews CLI commands with flags like --run, --operations-only, --times, etc.
• Process Management: Start, stop, and monitor Kometa runs directly from the web interface

Live Previews & Assets

• Overlay Preview Generator: Combines overlays and template variables into real-time preview images
• Custom Artwork Uploads: Drag-and-drop or fetch library images from a URL so you can see what the overlays look like on your favorite poster.

Automatic Updates

• Quickstart Self-Updater: One-click update to latest master or develop branch
• Kometa Sync: Option to pull and update Kometa itself (nightly/master) before running

Kometa Quickstart is a guided Web UI that helps you create a Configuration File for use with Kometa.

Special thanks to meisnate12, bullmoose20, chazlarson, and Yozora for their contributions to this tool.

Table of Contents

• Welcome to Kometa Quickstart
• ✨ Features
  • Multiple Ways to Run Quickstart
  • Safe Playground Mode
  • Config Management & History
  • Guided, Validated Workflow
  • Built-in Kometa Runner
  • Live Previews & Assets
  • Automatic Updates
• Table of Contents
• Prerequisites
• Installing Quickstart
• 1 - Installing on Windows
• 2 - Installing on Mac
• 3 - Installing on Ubuntu (Linux)
• 4 - Running in Docker
  • docker run
  • docker compose
• 5 - Installing locally
  • Windows:
  • Linux/Mac:
  • Debugging & Changing Ports

Prerequisites

We recommend completing the Kometa installation walkthrough before running Quickstart. This prepares Kometa to accept the configuration file Quickstart generates. Running Quickstart first may lead to mismatches with the walkthrough and issues that the walkthrough does not address.

Completing the walkthrough will also familiarize you with creating a Python virtual environment, which is recommended when running this as a Python script.

Installing Quickstart

There are five primary ways to install and run Quickstart, listed from simplest to more advanced.

Caution

We strongly recommend running this yourself rather than relying on someone else to host Quickstart.

This ensures that connection attempts are made exclusively to services and machines accessible only to you. Additionally, all credentials are stored locally, safeguarding your sensitive information from being stored on someone else's machine.

1 - Installing on Windows

• Go to the Releases page and download the standalone .exe.

• Choose the build you want (master or develop) and download the appropriate asset.

• Place the file in its own folder and double-click to run it.

• Manage Quickstart from the system tray icon.

2 - Installing on Mac

• Go to the Releases page and download the standalone file.

• Choose the build you want (master or develop) and download the appropriate asset.

• Place the file in its own folder.

• Open Terminal, navigate to the folder, and make the file executable: chmod 755 <name of file>.

• Run it: ./<name of file>.

• You may need to allow unsigned applications in macOS System Settings under Privacy & Security.

• Manage Quickstart from the system tray icon.

3 - Installing on Ubuntu (Linux)

• Go to the Releases page and download the standalone file.

• Choose the build you want (master or develop) and download the appropriate asset.

• Place the file in its own folder.

• Open a terminal, navigate to the folder, and make the file executable: chmod 755 <name of file>.

• Run it: ./<name of file>.

• Manage Quickstart from the system tray icon.

Warning

You will likely need to perform these steps first to have a system tray icon show up:

sudo apt update
sudo apt install -y libxcb-xinerama0 libxcb-xinerama0-dev libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0

4 - Running in Docker

NOTE: The /config directory in these examples is NOT the Kometa config directory. Create a Quickstart-specific directory and map it to /config.

Here are some minimal examples:

docker run

docker run -it -v "/path/to/config:/config:rw" kometateam/quickstart:develop

docker compose

services:
  quickstart:
    image: kometateam/quickstart:develop
    container_name: quickstart
    ports:
      - 7171:7171
    environment:
      - TZ=TIMEZONE #optional
    volumes:
      - /path/to/config:/config #edit this line for your setup
    restart: unless-stopped

5 - Installing locally

Windows:

1. Ensure Git and Python are installed.

Git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Python: https://www.python.org/downloads/windows/

2. git clone Quickstart, switch to your preferred branch (develop, master), create and activate a virtual environment, upgrade pip, and install the requirements.

Run the following commands within your Command Prompt window:

cd c:\this\dir\has
git clone https://github.com/Kometa-Team/Quickstart
cd Quickstart
git checkout develop
git stash
git stash clear
git pull
python -m venv venv
.\venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

4. Run Quickstart. After completing the guided pages, the final page will automatically create the Kometa virtual environment, install the requirements, and allow you to run kometa.py using the validated config generated by Quickstart.

python quickstart.py

Linux/Mac:

1. Ensure Git and Python are installed.

Git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Python:

Mac: https://www.python.org/downloads/macos/

Ubuntu/Debian: sudo apt-get install python3

Fedora: sudo dnf install python3

2. git clone Quickstart, switch to your preferred branch (develop, master), create and activate a virtual environment, upgrade pip, and install the requirements.

cd /this/dir/has
git clone https://github.com/Kometa-Team/Quickstart
cd Quickstart
git checkout develop
git stash
git stash clear
git pull
python3 -m venv venv
source venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

4. Run Quickstart. After completing the guided pages, the final page will automatically create the Kometa virtual environment, install the requirements, and allow you to run kometa.py using the validated config generated by Quickstart.

python3 quickstart.py

At this point, Quickstart has been installed and you should see something similar to this:

Quickstart should launch a browser automatically. If you are on a headless machine (Docker or Linux without a GUI), open a browser and navigate to the IP address of the machine running Quickstart; you should be taken to the Quickstart Welcome Page.

• Manage Quickstart from the system tray icon

Debugging & Changing Ports

You can enable debug mode to add verbose logging to the console window.

There are three ways to enable debugging:

• Add --debug to your Run Command, for example: python quickstart.py --debug.

• Open the .env file at the root of the Quickstart directory, and set QS_DEBUG=1 (restart required).

• Use the Quickstart system tray icon to toggle it on or off (no restart required).

Quickstart runs on port 7171 by default. You can change it in one of three ways:

• Add --port=XXXX to your Run Command, for example: python quickstart.py --port=1234

• Open the .env file at the root of the Quickstart directory, and set QS_PORT=XXXX where XXXX is the port you want to run on. (restart required)

• Use the Quickstart system tray icon to choose a new port (restarts automatically).