Kerkerker aggregates video sources into a self-hosted Next.js site

What the platform actually aggregates

Kerkerker is described as a movie and series resource aggregation platform. The README calls it a modern aggregation platform that supports the Dailymotion video source, Douban information matching and several deployment methods, and the project description adds multi-source switching and smart matching to that list. A live demo is hosted at kerkerker.vercel.app.

The feature list is short enough to enumerate and specific enough to judge. Video aggregation pulls from Dailymotion and other video sources. Douban matching attaches the Chinese film database's information and ratings to a title automatically. Danmaku, the scrolling comment overlay used by Chinese video sites, is matched and loaded automatically, with a manual search as a fallback. The player is ArtPlayer, with HLS support, playback speed and keyboard shortcuts. The interface is described as a Netflix style layout that is responsive across mobile and desktop, and there is an admin area at /login for configuring video sources and channels.

For the intended user, the appeal is that the hard parts of building such a site are assembled rather than invented. Source configuration, metadata matching, comment overlay, player controls and the admin surface exist, and what remains for the adopter is content, styling and hosting. The scope is a self-hosted front end with a small database, not a transcoding pipeline or a rights management system, and the README does not describe any upload, encoding or DRM behaviour.

The stack is named in the badges and confirmed by the package metadata: Next.js 16, TypeScript 5, MongoDB 7 and Docker, with Tailwind CSS for styling and React 19 as the UI library.

The directory layout shows where each concern lives

The project structure documented in the README maps the features onto files, which is the fastest way to understand the code.

The app directory holds the Next.js App Router routes, and components holds the React components, including a player subdirectory with LocalHlsPlayer.tsx for local HLS playback and DanmakuPanel.tsx as the danmaku search panel. The lib directory is the utility layer, with cache.ts as an in-memory cache, db.ts handling the MongoDB connection, and a player subdirectory containing danmaku-service.ts.

The rest of the tree confirms the runtime assumptions. There is a proxy.ts at the top level, a vercel.json for the Vercel deployment path, next.config.ts, hooks, types, docs and a tests directory. Two compose files sit alongside the production one, docker-compose.dev.yml and docker-compose.server.yml, and the scripts directory holds install.sh, the one-click deployment script referenced by the README, along with dev.sh and prod.sh, which the package scripts invoke.

The dependencies tell the same story from the other direction. artplayer and artplayer-plugin-danmuku supply the player and its comment overlay, hls.js handles HLS streams in the browser, axios and swr cover HTTP and data fetching, mongodb is the database driver, dotenv loads configuration, and clsx and lucide-react handle styling and icons. The @octokit/rest dependency is the one that does not obviously belong, and the repository does not document what it is used for.

One naming detail is worth flagging for anyone reading the code. The environment variables are prefixed NEXT_PUBLIC_ for the danmaku API URL and token, which means those values are compiled into the client bundle and readable by anyone who opens the developer tools.

Docker Compose with a health-gated database

The production compose file is the most complete deployment description in the repository, and it is more careful than the summary that appears in the README.

The application service builds from the local Dockerfile, is named kerkerker-app, and publishes port 3008 on the host:

  app:
    container_name: kerkerker-app
    ports:
      - "3008:3000"

It waits for the database using the health-gated form of depends_on, and it joins a dedicated bridge network called kerkerker-network with restart set to unless-stopped. The database service uses the mongo:7 image, is named kerkerker-mongodb, and publishes 27018 on the host for 27017 in the container. Its health check is a real ping rather than a port probe:

    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5

That health check is what the application's depends_on condition waits for, so a slow database start does not produce a crash loop. Data is persisted in two named volumes, mongodb-data for the database files and mongodb-config for the configuration directory, both with the local driver.

The image itself is a three-stage build on node:20-alpine that installs dependencies with npm ci, builds the Next.js application with production environment variables set, and then copies only the standalone output, the static assets and the public directory into a clean runner stage. The final image creates a system user and group with fixed identifiers, chowns the application directory, drops to that unprivileged user, and exposes the port:

FROM node:20-alpine AS runner
WORKDIR /app
ENV HOSTNAME=0.0.0.0
USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]

The container also carries its own health check against the application, so a failing application is visible to any orchestrator watching the image rather than only through the logs.

Two other deployment paths, and a script that pipes into bash

The README documents two alternatives to Docker Compose, and they suit different situations.

The Vercel path is the one the project recommends. A deploy button clones the repository into a Vercel project, and the operator sets two environment variables in the console, a MongoDB connection string and an admin password. The consequence is spelled out in a note: a Vercel deployment needs a cloud MongoDB such as a MongoDB Atlas free tier, because the container that serves the app is not the container that holds the database. The environment variables the deployment needs are:

ADMIN_PASSWORD=
MONGODB_URI=
MONGODB_DB_NAME=
NEXT_PUBLIC_DOUBAN_API_URL=
NEXT_PUBLIC_DANMU_API_URL=
NEXT_PUBLIC_DANMU_API_TOKEN=

The third path is a VPS script for a server that already has Docker. The README gives two one-liners that fetch and run the installer over curl or wget. Once it is installed, the stack lives in a kerkerker directory under the home directory and is driven by a management script with start, stop, restart, logs, update and backup subcommands. The backup command is the one to look at before trusting the deployment, since the database is the only thing in the stack worth keeping.

That install style deserves a note on its own. Piping a remote script into a shell is the pattern most often criticised in deployment guides, and it is the pattern the README offers first, with no checksum and no pinned commit in the command. A reviewer who wants the same result with the same guarantees should read scripts/install.sh in the repository and run it from a local checkout instead.

The admin password default is the first thing to change

The configuration surface is small, and that makes it easy to audit, with one exception.

Only one variable is required, MONGODB_URI, the MongoDB connection string, and the rest have documented defaults. MONGODB_DB_NAME defaults to kerkerker, the danmaku API address has a public default endpoint, and the danmaku token is unset by default. The .env.example file in the repository lists the same set with empty values, which is the right starting point for a deployment.

The exception is ADMIN_PASSWORD, whose documented default is admin123. The admin area at /login is where video sources and channels are configured, so an installation left on the default value has an open control panel. The compose file passes the variable through from the host environment, which means the value lives in the .env file that the setup instructions create from the sample, and that file is the thing to protect.

The second point is the danmaku token. NEXT_PUBLIC_DANMU_API_TOKEN is a client-prefixed variable, so its value is sent to the browser as part of the client bundle. If the upstream danmaku API expects that token to be secret, this design cannot keep it secret, and an operator who has paid for a private endpoint should expect it to be visible to anyone using the site. The compose file similarly passes NEXT_PUBLIC_DOUBAN_API_URL, and no NEXT_PUBLIC_DOUBAN_API_TOKEN is listed, so the Douban integration is configured by address alone.

The port mapping deserves a second look too. The compose file in the repository publishes 3008:3000, while the summary of docker-compose.yml in the README shows 3000:3000 and tells the reader to change the left-hand number. The two documents disagree, and the one that actually ships is the file in the repository.

Version 0.1.0, no releases, and Chinese-first documentation

A few facts about the state of the project are worth knowing before you build on it.

The package is private and sits at version 0.1.0, and the repository publishes no GitHub releases, so there is no changelog to read and no tag to pin. The last push was on 2026-09-24. The licence is MIT, with the notice recorded as MIT License 2026, which is permissive enough for a company to fork and change without publishing anything back, subject to keeping the copyright notice in copies.

The documentation is written in Chinese, including the feature list, the deployment walkthroughs and the environment variable tables, while the code, the type definitions and the interface strings in the file listing are in English. The README is therefore usable for a Chinese-reading team, and anyone else will be reading the tables of variables and commands rather than prose. The screenshots in the screenshot directory cover the home page, search, detail and playback views.

The code layout suggests more rigour than the release history shows. There is a tests directory, an eslint.config.mjs, strict TypeScript in tsconfig.json and a pre-built CI setup, yet the package.json scripts list no test command at all, only dev, build, start, lint and the two Docker helpers. A project with a tests directory and no way to run it is a gap rather than a strength, and it is the first thing to fix if you take this on.

None of this makes the project unusable. It makes it a young codebase with good bones, which is a good reason to read the source before running it in production rather than a reason to run it in production first.

Editorial conclusion

Kerkerker fits a developer who wants a ready-made video aggregation front end, with source configuration in an admin panel, Douban metadata matching, danmaku and an HLS player already wired together, and who is comfortable owning the deployment. It is the wrong base for a public service as it stands, because the admin password defaults to admin123, the danmaku API token is exposed to the browser through a NEXT_PUBLIC variable, and there is no release history to pin. Before deploying, set ADMIN_PASSWORD, put the app behind a TLS terminating proxy, decide whether the douban and danmaku API variables should point at your own endpoints, and reconcile the port difference between the README and the compose file, which map 3000 and 3008 respectively.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. unilei/kerkerker on GitHub