Moka

Docs

How to install Moka, connect it to your services and keep it running. This page follows the code on the main branch.

Before you start

Moka is a development preview. There are no releases yet, and settings or the database can change between commits. Point it at a copy of your media, or at folders you can afford to have reorganised.

You will need:

  • A machine that stays on: a NAS, a mini PC, a home server. Docker makes it easiest.
  • A download client: qBittorrent or Transmission for torrents, SABnzbd for Usenet.
  • One or more Torznab or Newznab indexers, added directly or through Prowlarr.
  • Folders for your downloads and your library, ideally on the same disk.

Moka ships with no content sources. What it can find depends entirely on what you connect.

Install with Docker

There is no published image yet, so you build it from the repository. The build takes a few minutes.

git clone https://github.com/openVESSL/Moka.git
cd Moka
cp docker-compose.example.yml docker-compose.yml
# set your media folder under volumes, then:
docker compose up -d --build

The example mounts two folders:

  • ./config as /config: the database, caches and the secret key.
  • Your media folder as /data, holding both downloads and the library (see Folders and hardlinks).

Then open http://your-server:8484.

Run from source

You need Rust (stable), Node.js 22 or newer with pnpm, and FFmpeg for playback. The web app is built into the server binary, so build it first.

pnpm --dir web install
pnpm --dir web build
cargo run --release -p moka-server

Moka listens on http://localhost:8484 and keeps its data in ./config.

First run

On the first visit Moka asks you to create an account. That first account is the admin. Moka starts empty, so the catalog works right away but nothing can be downloaded until you connect your services.

Add people for your household or friends under Settings → People, and choose what each one may do: request, have requests approved automatically, manage requests or manage the library. Settings → Request limit caps how much each person can request in a period.

Connect your services

Download client
Connections → Download clients. Add qBittorrent, Transmission or SABnzbd with its address and login. Moka adds its downloads under their own category, moka by default.
Indexers
Connections → Indexers. Paste a Torznab or Newznab address with its API key, or import every indexer you already have in Prowlarr at once. Moka searches all of them together.
Library
Settings → Library. Choose a films folder and a shows folder. If they already hold titles, scan them and Moka brings them in as they are.
Quality
Settings → Quality. List the releases you accept, best first. Moka downloads the first acceptable one it finds and upgrades it until it reaches the point where you told it to stop.
Jellyfin
Connections → Jellyfin. Moka tells Jellyfin about new files right after import and brings back what people watched there. If the two see your media under different paths, map one to the other.
Radarr
Connections → Radarr. Let Radarr do the searching and downloading: approved film requests go to Radarr, and every film it has appears in Moka to watch.
Other apps
Connections → API keys. Apps that talk to Radarr or Sonarr, such as indexer managers, request apps and subtitle apps, can use Moka's address with a key from here. Connections → Notifications tells Discord or any service that accepts JSON when something is requested, ready or stuck, and calls a subtitle app's webhook after each import.

Folders and hardlinks

Keep downloads and the library on the same disk, and in Docker inside the same mount. Then an import is a hardlink: instant, and it takes no extra space while the download keeps seeding. Across disks Moka copies instead. It never moves or deletes the downloaded file.

/srv/media/
  downloads/   # your download client saves here
  movies/      # films folder in Settings → Library
  shows/       # shows folder in Settings → Library

Films are filed as Title (Year) {tmdb-ID} and shows as Show (Year) {tmdb-ID}/Season 01, names other media servers read without trouble.

Playback

Files the browser can play are sent as they are. Others are repackaged or converted on the fly with FFmpeg. Subtitles inside the file or next to it are picked up, styled ones included.

Conversion is faster on a graphics card. Pick it under Settings → Playback: NVIDIA (NVENC), Intel or AMD on Linux (VAAPI), or Intel Quick Sync. If the card fails, Moka falls back to the processor. In Docker the card has to be passed to the container; the compose example shows how for each kind.

Configuration

Everything else is set in the web app. These environment variables cover what has to be known at start:

VariableDefaultWhat it does
MOKA_CONFIG_DIR ./config Database, caches and the secret key. /config in Docker.
MOKA_PORT 8484 Port for the web app and the API.
MOKA_HOST 0.0.0.0 Address to listen on.
MOKA_DATABASE_URL SQLite in the config folder Only if you want the database somewhere else.
MOKA_SECRET_KEY secret.key in the config folder Base64, 32 bytes. Encrypts stored passwords and API keys.

Backups and updates

Back up the config folder, and keep moka.db and secret.key together. Without the key, stored indexer keys and passwords cannot be read and have to be entered again.

To update a Docker install, pull and rebuild:

git pull
docker compose up -d --build

Moka upgrades its database on start and keeps a copy of the previous one next to it.

Getting help

Questions, ideas and bug reports go to the issues on GitHub. Say what you tried, what you expected and what happened; real setups help more than anything else right now.

Found a security problem? Please do not open a public issue. Use Security → Report a vulnerability on the repository.