MyLists

Ensure you have Bun installed on your machine.

1. Clone the repo

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

1. Install deps

bun install --frozen-lockfile

1. Configure the env file

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.

1. Initialize Database

bun run new:db

1. Create a new user

bun run cli -- create-user \
     --email [email protected] \
     --password "change-me-strong-password" \
     --username admin \
     --role admin

1. Run the Dev Server

bun run dev

Commit bun.lock alongside package.json when updating dependencies. Deployment uses the committed lockfile without resolving new versions.

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 | ❌ | | | MAL_CLIENT_ID | Enables manga data and anime genres through MyAnimeList | ❌ | | | 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 config does not prevent MyLists from starting. Login and registration only show configured auth methods.

• Without admin mail credentials, email registration, password reset, email changes, and mail-dependent maintenance are disabled. Email login still works for verified accounts

• GitHub and Google OAuth are enabled 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.
• Without MAL_CLIENT_ID, manga external search/details are unavailable and anime uses TMDB genres without MyAnimeList enrichment. Register an API client at

• Google Books remains available without credentials. GOOGLE_BOOKS_API_KEY is optional.
• Without LLM_API_KEY, book genre enrichment is skipped with a task warning.

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

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.