andcbii/shelfcheck repository overview

⁠Shelfcheck

Shelfcheck is a private, single-user web app that compares the TV shows in your Trakt collection with Trakt's aired episode list. It creates a clean report showing which aired episodes are missing from your collection and lets you ignore shows you do not want included.

Shelfcheck was created with ChatGPT by OpenAI.

⁠Features

• Scans your Trakt TV collection for missing aired episodes
• Saves your latest report and scan progress
• Lets you exclude selected shows from the report
• Stores all configuration and app data in local Docker volumes
• Includes a built-in health check

⁠Docker Compose example

Create a file named compose.yaml:

services:
  shelfcheck:
    image: andcbii/shelfcheck:latest
    container_name: shelfcheck
    ports:
      - "3000:3000"
    volumes:
      - shelfcheck-config:/config
      - shelfcheck-data:/data
    restart: unless-stopped

volumes:
  shelfcheck-config:
  shelfcheck-data:

Start the container:

docker compose up -d

Open http://localhost:3000, enter your Trakt details, and start your first scan.

The container runs as UID/GID 1001. If you use bind mounts instead of named volumes, make sure the mounted directories are writable by that user.

⁠Getting the Trakt API values

Shelfcheck needs a Trakt Client ID and an OAuth Access Token. The client secret is used only while obtaining a token and must not be entered into Shelfcheck.

1. Sign in to Trakt and open Your API Apps⁠.

2. Create a new application. Give it a name such as Shelfcheck and set its redirect URI to a URL you control. For local/manual setup, http://localhost:3000 can be used. The redirect URI is case-sensitive and must be identical in every OAuth step.

3. Save the application, then copy its Client ID. This is the first value Shelfcheck needs.

4. Authorize the application using Trakt's authorization-code flow. Open the following URL after replacing the placeholders:

   https://auth.trakt.tv/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http%3A%2F%2Flocalhost%3A3000
   

   Copy

5. Approve access. Trakt redirects your browser to the configured URI with ?code=... in the address bar. Copy that code.

6. Exchange the code for a token. Replace all placeholder values below; redirect_uri must exactly match the URI configured above.

   curl --request POST \
     --url https://auth.trakt.tv/oauth/token \
     --header "Content-Type: application/json" \
     --data '{
       "code": "YOUR_AUTHORIZATION_CODE",
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
       "redirect_uri": "http://localhost:3000",
       "grant_type": "authorization_code"
     }'
   

   Copy

7. Copy the access_token from the JSON response. Enter it in Shelfcheck together with the Client ID.

Trakt access tokens currently expire after seven days. Shelfcheck does not store or use the refresh token, so repeat the authorization process and replace the access token when Trakt reports that it has expired. Treat the client secret, authorization code, access token, and refresh token as secrets.

You can also provide the values manually in /config/config.yml:

trakt:
  client_id: "your-trakt-client-id"
  access_token: "your-trakt-access-token"

⁠Storage

Keep both volumes when updating or recreating the container. Running docker compose down preserves named volumes; adding --volumes removes them.

⁠Ports

⁠Updating

docker compose pull
docker compose up -d