Nextup

Documentation

Everything from first install to the last setting, in the order you need it.

What Nextup is

A tracker for the television and films you watch, that you run on your own machine. It remembers where you are in every show, works out what is waiting, and tells you when a film reaches home viewing. One account, no signup, and it never talks to us.

Everything it knows about shows and films comes from TMDB, fetched by your server with your own free key.

Before you start

You need two things.

  • Docker, with the compose plugin.
  • A free TMDB account and its API key. Make the account, then go to themoviedb.org/settings/api and copy the API Key for v3 auth. You paste it into Nextup later, not into a file.

Installing

Make the directory your data will live in, owned by user 1000:

sudo mkdir -p /opt/nextup
sudo chown -R 1000:1000 /opt/nextup

Save this as docker-compose.yml beside it:

services:
  nextup:
    image: ghcr.io/gh-lm/nextup:latest
    container_name: nextup
    restart: unless-stopped
    ports:
      - "127.0.0.1:4090:8080"
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    read_only: true
    tmpfs:
      - /tmp
    volumes:
      - /opt/nextup:/data
      - /etc/localtime:/etc/localtime:ro
docker compose up -d

Then open it, sign in with admin and nextup, and Nextup will ask you to choose your own password before it shows anything else.

The Settings page

Everything that makes your copy yours is set here, not in a file.

  • Your username and password.
  • The TMDB key. Checked against TMDB before it is saved, then stored encrypted.
  • The morning email. Your mail server, the port, whether it uses STARTTLS, SSL or neither, the username and password, who the message comes from and who it goes to, and the time it is sent, to the minute. A switch turns the clock between 24 hour and am and pm.
  • Watchable after. How long to wait before something counts as available, so a programme that airs at eleven at night does not appear until you would really watch it. It governs the dashboard, the films list and the email alike.
  • The accent colour, from a fixed set.
  • Backups, covered below.

Settings that live in the environment

Only the things that decide where the app lives. No keys or passwords ever go here.

  • NEXTUP_DATA_DIR, default /data. Where the database, the keys and the poster cache live.
  • NEXTUP_PORT, default 8080. The port inside the container.
  • NEXTUP_HTTPS_ONLY, default 0. Set it to 1 only when every way in really is HTTPS. See the security page.
  • TZ. Only needed if you want a different timezone from the machine itself. The compose above mounts /etc/localtime instead, so the container follows the server.

What lives in the data directory

  • nextup.db, the shows, the episodes and what you have watched.
  • secret.key, which encrypts the TMDB key and the mail password.
  • session.key, which signs the login cookie.
  • images/, the cached posters and stills.

Backing up that one directory backs up everything.

Backing up and moving

The Settings page has a Download a backup button. One JSON file holds every show and film you added, everything you marked watched, what you dismissed and your settings, with enough show detail for a fresh copy to be usable at once. It also holds your username and a hash of your password, so keep the file private.

Your TMDB key and mail password are left out by default, because they are encrypted with a key that stays on that server. A second button includes them as plain text, so keep that file somewhere safe.

Restoring is the same page in reverse. See the runbook for moving to another machine.

Updating

docker compose pull
docker compose down
docker compose up -d

A plain up -d does not fetch a newer latest on its own. Every release is tagged with its version number as well, so you can pin one if you would rather. The source is inside the image too, under /app, as the licence requires.

Licence and credits

Nextup is free software under the GPL version 3. The full text is on the licence page.

This product uses the TMDB API but is not endorsed or certified by TMDB. Streaming service listings come from JustWatch by way of TMDB.