MyLists

The all-in-one media tracking platform.

MyLists is a comprehensive, type-safe web-app designed to help you organize and track your movies, TV series, anime, manga, books, and video games in one unified interface.

Key Features

• Multi-Media lists: Dedicated lists for Movies, Series, Anime, Manga, Books, and Games.
• Upcoming Media: Get notified when new Media are released.
• Advanced Analytics: Visualize your habits with detailed statistics, trends, and platform-wide insights.
• Modern Full-Stack Architecture: Built with TanStack Start and end-to-end type-safety.
• Daily Moviedle: A daily guessing game to test your movie knowledge.
• Achievements System: Earn unique badges and track your progress as you consume more media.
• Secure Authentication: Robust user management powered by Better-Auth.

Quick Start

Ensure you have Bun installed on your machine.

1. Clone the repo

   git clone https://github.com/crossoufire/MyLists.git
   cd MyLists

2. Install deps

   bun install

3. Configure the env file

   Create a .env file in the root directory and set the three required security values:

   cp .env.example .env
   openssl rand -hex 32

   Run the OpenSSL command twice and use the generated values for ADMIN_TOKEN_SECRET and BETTER_AUTH_SECRET, then choose an ADMIN_PASSWORD of at least 8 chars. All other values have defaults or enable optional features.

4. Initialize Database Initialize a new SQLite database in the instance directory.

   bun run new:db

5. Create a new user To create a new user without email verification, OAuth2 setup, and with different roles (user, manager, admin), you can use the CLI:

   bun run cli -- create-user \
     --email admin@example.com \
     --password "change-me-strong-password" \
     --username admin \
     --role admin

6. Run the Dev Server

   bun run dev

Docker Deployment

Docker deployment is documented in docs/docker-deployment.md.

The Docker Compose setup builds the app image and starts Redis. It mounts persistent storage for SQLite, images, and Redis data. Provide cron/maintenance scheduling and public HTTPS from your deployment platform when needed. PostHog is optional and disabled when its public key is empty.

---

Environment Variables

Below is an explanation for each key found in .env.example:

Variable	Description	Required	Default
Main Configuration
DATABASE_URL	SQLite database path	❌	./instance/site.db
VITE_BASE_URL	Base URL used by the frontend	❌	http://localhost:3000
VITE_CONTACT_MAIL	Email used to be contacted by users	❌
File Management
UPLOADS_DIR_NAME	Folder name where uploaded files are stored	❌	static
BASE_UPLOADS_LOCATION	Path to the uploads dir (relative or absolute)	❌	./public/static/
Admin Access
ADMIN_PASSWORD	Admin dashboard privilege-escalation password	✅
ADMIN_TOKEN_SECRET	Secret key for admin access token signing	✅
ADMIN_TTL_COOKIE_MIN	Lifespan of the admin session cookie (in minutes)	❌	10
Admin Mail Service
ADMIN_MAIL_USERNAME	Gmail address used to send application emails	❌
ADMIN_MAIL_PASSWORD	Gmail password or app password	❌
Cache / Redis
CACHE_TTL_MIN	Cache duration (in minutes)	❌	5
REDIS_ENABLED	Enables Redis-backed cache, rate limits, and API monitoring	❌	false
REDIS_URL	Redis connection string, required only if Redis is enabled	❌	redis://localhost:6379
Authentication
BETTER_AUTH_SECRET	Secret used by Better Auth for encryption	✅
OAuth2 Providers
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	GitHub OAuth2 credentials	❌
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google OAuth2 credentials	❌
API Keys
THEMOVIEDB_API_KEY	Enables movie, series, and anime external data through TMDB	❌
GOOGLE_BOOKS_API_KEY	API key for Google Books	❌
IGDB_CLIENT_ID / IGDB_CLIENT_SECRET	Enables game external data through IGDB	❌
LLM Integration (Optional)
LLM_MODEL_ID	Model ID (OpenRouter) used to generate book genres	❌	google/gemini-2.5-flash-lite
LLM_BASE_URL	Base URL for the chosen LLM API	❌	https://openrouter.ai/api/v1
LLM_API_KEY	API key token for the LLM provider	❌

---

Redis Setup

Redis caching is optional.

• To run without Redis, set:

  REDIS_ENABLED=false

• To use Redis, ensure Redis is available and configured:

  REDIS_ENABLED=true
  REDIS_URL=redis://redis:6379

• Redis is used for shared caching, shared rate limiting, and API monitoring rollups.

• Without Redis, the app falls back to in-memory cache/rate limiting.

• The admin API monitoring page will not collect outbound API rollups without Redis.

---

Optional Feature Availability

Missing optional configuration does not prevent MyLists from starting. Login and registration only show configured authentication methods, while unavailable media providers return a clear error when used.

• Without admin mail credentials, email registration, password reset, email changes, and mail-dependent maintenance are disabled. Email login still works for verified accounts created with the create-user CLI.
• GitHub and Google OAuth are enabled independently when their complete client ID/secret pair is present.
• Without TMDB, movie, series, and anime external search/details are unavailable. Without IGDB, game external search/details are unavailable.
• Google Books and Jikan remain available without credentials. GOOGLE_BOOKS_API_KEY is optional.
• Without LLM_API_KEY, book genre enrichment is skipped with a task warning.

For every optional credential pair, either set both values or leave both blank. A partial pair is treated as a configuration error so typos are caught early.

---

LLM Integration (Optional)

The LLM is exclusively used to generate genre data for books since Google Books does not provide genre metadata. You can choose how this background task runs:

1. Manually, by executing it with the CLI
2. Automatically, using a scheduled cron job

When LLM_API_KEY is absent, direct and scheduled enrichment runs are skipped with a log.

---

Contributing

Contributions are welcome!
If you’d like to improve MyLists, fork the repo, create a feature branch, and open a pull request.

---

Built with ❤️ using Bun, Drizzle, Better-Auth, React, TypeScript, and TanStack.