NexusPHP: a private tracker stack rebuilt on Laravel and Filament

What a private tracker actually is, in feature terms

NexusPHP is described as a private tracker application based on NexusPHP, and the description in Chinese calls it a complete PT site building solution based on NexusPHP plus Laravel plus FilamentPHP.

PT is the abbreviation the community uses for a private tracker, a torrent index where access is by invitation rather than open, and the whole design follows from that. The feature list is a list of the mechanics of a membership site, not of a file browser.

The core is 发种, uploading a torrent. 求种 is requesting that others upload something. Then there is the 特别区 for a special section, subtitles, an examination or assessment system, H&R rules, which are the hit and ratio requirements a member must meet, a 认领 claiming mechanism, a review queue, sign in with make up cards for missed sign ins, badges, items, custom tags, third party full text search, box rules, a forum, an appeals process, multiple languages, automatic backup, plugin support, an admin backend and a JSON API.

The H&R part is what makes it a tracker rather than a file listing. A member is expected to upload at a certain ratio and download a certain amount, and the system tracks both and flags members who fall short, and the examination and appeals features are how a member disputes a flag. That is the social contract the software exists to enforce.

Some features are explicitly provided by plugins rather than the core, and the list is revealing. Post likes, post rewards, sticky promotion, custom menus, a lucky wheel, custom roles and permissions, per section H&R, and TGBot are all plugin work. So the architecture is a core site with an extension point that the community uses for the parts that vary between trackers.

The project also invites internationalisation work through a discussion thread, and the README is published in both Chinese and English, with a Chinese and an English version in the repository.

The system requirements are the real specification

The requirements section is unusually complete, and it is the first thing to read before evaluating the project.

PHP 8.2, 8.3, 8.4 or 8.5, and a long list of required extensions: bcmath, ctype, curl, fileinfo, json, mbstring, openssl, pdo_mysql, tokenizer, xml, mysqli, gd, redis, pcntl, sockets, posix, gmp, zend opcache, zip, intl, pdo_sqlite, sqlite3 and pdo_pgsql.

That list tells you a lot. Both pdo_mysql and pdo_pgsql, plus both sqlite3 and pdo_sqlite, so either a MySQL or a PostgreSQL database is the primary store and SQLite is an alternative for smaller or local setups. The redis extension, which is standard for a PHP project that needs queues and caching. pcntl and posix for process control, which is what you need for a long running worker. sockets for the peer protocol, gmp for the big integer arithmetic that the hash and piece calculations require, and gd for image handling.

The database is MySQL 5.7 or newer, or PostgreSQL 16 or newer, and Redis 4.0.0 or newer. The other requirements are supervisor and rsync, which is the same pair the Docker compose file makes sense of, since supervisor runs the queue worker and the scheduler, and rsync moves things between the tracker and the storage.

The `.env.example` file backs that up with the application configuration, and it is a long file. Beyond the usual Laravel settings there are the pieces that make a tracker a tracker. The CAPTCHA settings are there, with available drivers listed as image, cloudflare_turnstile and google_recaptcha_v2, and a default of image. There is Meilisearch configuration for search, Elasticsearch configuration, a SFTP block for the storage side, a GeoIP2 database setting, Google Drive credentials for offsite, AWS credentials, Pusher for broadcasting, and the S3 style bucket settings.

There are also a few settings that reveal the operational design. `USE_CRON_TRIGGER_CLEANUP=true` suggests cleanup can be driven by cron rather than only by the scheduler. `UID_STARTS=10001` is a uid allocation offset, which is a common trick for a system that creates many user accounts. And `SESSION_LIFETIME=120` sets a two hour session lifetime.

The Docker quick start, and the warning attached to it

The quick start in the documentation is four lines of shell, and the surrounding prose is more informative than the commands themselves.

First, install Docker, and note that DOMAIN is the domain you intend to use, which you should point DNS at in advance, and that using an IP instead of a domain also works. The ports are specified as needed, and the instruction is to change them if port 80 is already in use locally and to make sure the port is exposed to the outside. Then step two is to create the `.env` and choose the correct `TIMEZONE`, with the other values left at their defaults.

The commands are:

docker pull xiaomlove/nexusphp:latest
docker run --name my-nexusphp -e DOMAIN=xxx.com -p 80:80 xiaomlove/nexusphp:latest

And then the line that matters most for anyone planning a deployment: for a production environment it is recommended to follow the documentation for a real machine installation.

That sentence is a warning dressed as a footnote, and it is worth taking seriously for a specific reason. A tracker accumulates state that a demo does not have. Uploaded torrents, per user download history, ratio and hit counts, the H&R flags, the sign in records, the announcements, the forum posts. A container image with a mounted volume is a perfectly reasonable way to run that, but the mount is the only thing standing between you and the data, and the compose file's backup path defaulting to a temporary directory is a reminder that the backup is a configuration decision someone has to make.

The other thing the quick start reveals is the shape of the deployment. One container, a domain, a port. Behind that, the compose file shows the full production arrangement, so the single container image is the simplified path and the compose file is the real one.

The rest of the project's public surface is small and worth listing, because for a project of this size the documentation is the product as much as the code. There is a blog at nexusphp.org, documentation at doc.nexusphp.org, and a Telegram developer channel. The repository has both a Chinese and an English README, and the English one is at a separate path, and the project invites internationalisation contributions through a discussion thread.

The Docker build files live in a `.docker/` directory with separate Dockerfiles for the PHP tier and for openresty, and the compose file references them directly, so the images are built from the repository rather than pulled, which is the same decentralisation instinct you see in other self-hosted infrastructure projects.

Six containers, and why the queue and scheduler are separate

The compose file is the clearest picture of the runtime architecture, and it is a good design to read.

There is a `php` service built from a Dockerfile in `.docker/php/`, with the source mounted at `/var/www/html` and a backup directory mounted from a configurable path. Then three services that run the same image as the PHP service but with a different `SERVICE_NAME` environment variable: `queue`, `scheduler` and `cleanup`.

So the same application image runs in four roles, distinguished by an environment variable rather than by four different builds. That is efficient and it has a second benefit, since the worker, the scheduler and the cleanup job are running the same code as the web tier and cannot drift from it.

The `queue` service depends on php, redis and mysql and has `restart: always`. The `scheduler` depends on the same three and also restarts always. The `cleanup` service depends on php, redis and mysql with the same restart policy. And the `php` service itself depends on mysql and redis, with no restart policy on it.

The dependencies are the interesting part. The queue and the scheduler both need the PHP service to be up, which suggests the workers connect to the application and its database rather than being fully independent processes, and the ordering avoids a worker starting against a schema that is not ready.

The `openresty` service is built from `.docker/openresty/Dockerfile` and is the front door, the reverse proxy in front of the PHP tier. OpenResty rather than nginx is a deliberate choice, since it is nginx with Lua scripting built in, and a tracker benefits from being able to run the block logic in Lua at the proxy layer rather than pushing every request into PHP.

All the services sit on a shared `appnet` network, and every service configures the same logging driver with a 1024 megabyte maximum file size and three rotated files, which is a reasonable default for a service whose access logs are large and whose disk is often a small VPS volume.

A legacy codebase with a modern front end

The repository layout shows two eras of PHP development living side by side, and understanding that tells you what you are adopting.

The legacy side is visible in the directory names. There is `nexus/` which is the NexusPHP core, `classes/`, `include/`, `imdb/`, `bitbucket/`, `subs/`, `torrents/` and `attachments/`, plus a `public/` directory with an `index.html`. The `nexus/` directory in particular is the giveaway, since NexusPHP is a tracker codebase whose structure predates modern PHP frameworks, and it is a codebase with its own conventions, its own database tables and its own URL routing.

The modern side is a Laravel application. There is an `artisan` file, a `bootstrap/` directory, a `config/` directory, a `database/` directory with migrations, `routes/`, `resources/` with views, `storage/`, `app/` with the application code, `tests/` with a `phpunit.xml`, and a `composer.json` and `composer.lock`.

So this is not a fresh Laravel application with a tracker bolted on. It is the original NexusPHP tracker with a Laravel and Filament administration layer around it and the two connected. That has a clear consequence for anyone evaluating it. The Laravel parts will feel current, and the tracker core will feel like a 2000s codebase, because it largely is one, and the seams between them are where the work is.

The front end is a separate story again, and the `package.json` shows it. The build is Laravel Mix at `^6.0.6` with Tailwind CSS at `^3.3.6` and PostCSS at `^8.1.14`, and the runtime dependencies are `alpinejs` at `^3.13.3` and the `@awcodes/alpine-floating-ui` package. So the newer parts of the interface are Alpine.js components styled with Tailwind, which is a light, modern choice, while the older pages are the classic server rendered PHP.

Two other things in the layout are worth a glance. The `_db/` directory holds the database schema, and `_doc/` holds the documentation, both with the underscore prefix that keeps them out of the way of the public document root. The `lang/` directory holds the translations, matching the multi language feature, and the `storage/` directory is the writable area Laravel needs.

And there is a `docker-compose.yml` at the top level alongside a `.docker/` directory, and the README recommends the on-machine install for production. The Chinese quick start says to install Docker, set the domain, and run the container, and then says that for a production environment it is recommended to follow the documentation for a real machine installation. That is an honest warning, and it is worth taking seriously, because a tracker that has been running for years accumulates real user data and real upload state.

Editorial conclusion

NexusPHP fits a community running its own small private tracker, because the feature set covers the parts that are hard to rebuild, including hit and ratio rules, request sections, subtitle handling, a moderation queue, sign in with make up cards, badges and a plugin system. Skip it if you need a general purpose file index, because this is a torrent tracker with a specific social model, and read the deployment notes before using Docker in production, since the documentation recommends the on-machine install for production and describes the container route as the quick start. Before you plan an install, check the required PHP extensions, the database version and the Redis version, because the requirement list is long and specific. The last push was on 2026-10-14 with version 1.9.15.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. README
4. Releases
5. xiaomlove/nexusphp on GitHub