Cinemati — Personal Movie & Series Tracker

A simple local app to manage your watchlist: movies, series, seasons, ratings, franchises, custom lists, and statistics. All data stays on your machine in data/library.json.

No AI required — all metadata (titles, descriptions, images, cast, franchises) comes straight from TMDB.

Storage (works offline)

• data/library.json — your library with all its details (descriptions, cast, franchises...)
• data/images/ — images are stored locally (posters, backdrops, cast photos)
• After adding an item, all its data and images stay with you — browsing your library works fully offline
• Only searching for new items and new franchises requires internet

Requirements

• Node.js 20 or newer — we recommend the latest LTS (currently 24): https://nodejs.org

Running

node server.js

Then open: http://127.0.0.1:8080

TMDB Token (one-time)

1. Sign up at https://www.themoviedb.org, open the API page, and get a token.
2. From the app: Settings → paste the token → Save token (or place it manually in config.json like this:)

   { "tmdbToken": "your_token_here" }
   

3. Without a token, TMDB search/add won't work — everything else still works fine.

Moving the app to another machine

1. Copy the whole project folder (or clone it):

   git clone https://your-forgejo.example.com/your-user/cinemati.git
   cd cinemati
   

2. Run node server.js
3. Your data: copy data/library.json (and config.json for the token) from the old machine to the same locations on the new one — or use the Export data button on the home page, then Import backup on the new machine.

Running with Docker (docker-compose)

The image is published to the built-in Forgejo registry: your-forgejo.example.com/your-user/cinemati.

1. One-time: make Docker trust the your-forgejo.example.com self-signed certificate — add to /etc/docker/daemon.json and restart Docker:

   { "insecure-registries": ["your-forgejo.example.com"] }
   

   The repo is public — no docker login is needed to pull.

2. Copy docker-compose.yml to the server and create a .env from .env.example with your TMDB token:

   cp .env.example .env   # then edit TMDB_TOKEN inside .env
   

3. Copy your current data/ folder (library + images) next to docker-compose.yml to keep your data.
4. Run:

   docker compose pull
   docker compose up -d
   

   Then open: http://:8080

Automatic builds (Forgejo Actions)

The Dockerfile is built and published to the registry with this tagging strategy:

Tag	When it updates
sha-xxxxxxx	Every push to main or a v* tag (immutable per commit)
vX.Y.Z	Only when a release tag (v*) is pushed
latest	Only when a release tag (v*) is pushed — always points to the newest release

So docker compose pull (using :latest) always gets the latest released version, while :sha-... lets you pin any specific commit.

Only the newest 3 releases are kept — each release automatically prunes older vX.Y.Z git tags and their registry images.

One-time requirements (on the server):

1. Register a Forgejo Runner on your-forgejo.example.com (see the Forgejo docs).
2. Add a secret named REGISTRY_TOKEN in the repo (Settings → Actions → Secrets) with an access token.
3. Make sure the runner's Docker trusts your-forgejo.example.com (same insecure-registries as above).

Features

• Movies / Series with search and filters by genre and grouping (year / decade / genre)
• Currently watching, Watched with OK / No rating
• Franchises: detects the franchise and shows the remaining parts with quick add
• Custom lists, Watch later, Episode progress, Rewatch
• Statistics: monthly, watch calendar, genres
• Random pick, List view, Light/dark mode, Refresh from TMDB
• Backup (JSON export/import)

Internationalization (i18n)

All UI text lives in public/locales/ (one file per language). The default UI language is Arabic.

• public/locales/ar.js — Arabic translations
• public/locales/en.js — English translations

To add a language, create public/locales/<lang>.js, add the matching keys, and include the file in index.html. Switch languages with setLang("<lang>").

Versioning

The project uses Semantic Versioning (MAJOR.MINOR.PATCH):

• MAJOR — radical/large changes (breaking changes, big rewrites).
• MINOR — adding/removing a feature or medium changes.
• PATCH — small fixes and tweaks only.

To release a new version:

npm run release -- major    # or: minor | patch

This bumps package.json, commits, and tags vX.Y.Z. Pushing the tag builds and publishes the versioned Docker image. See CHANGELOG.md for the release history.

Notes

• Language: Arabic UI, metadata (titles and descriptions) in English from TMDB
• Requires internet for TMDB (search, images, cast, franchises)
• Data is stored locally only — nothing is uploaded anywhere