Photonix: a self-hosted photo manager with ML tagging, run from Docker Compose

The gap Photonix fills: a private library that tags itself

Most home photo servers give you folders, albums and a search box that matches filenames. Photonix aims at a different question: which of these ten thousand images contains a dog, a beach, or the same face. The README describes a web application you run on your home server so you can find what you want from your collection on any device, with smart filtering produced automatically by object recognition, location awareness, colour analysis and other algorithms. The intended user is someone with a server at home, a large photo folder and no wish to upload it to a hosted service. The repository topics list face-recognition, object-detection, tensorflow, django, react and docker, which matches that description. It is not a sync client, not a mobile-first gallery app, and not a hosted product. The README is direct about maturity: the project is currently in development and not feature complete for a version 1.0, and it invites people who do not mind putting up with broken parts to run the Docker image.

Architecture: Django, GraphQL, Postgres, Redis and TensorFlow in one stack

The shape of the system is visible in requirements.txt and the repository layout. Django 6.0.7 is the application server, with graphene and graphene-django providing a GraphQL API, django-graphql-jwt for authentication and django-cors-headers for the browser client. The ui/ directory holds the React front end, which talks to that API rather than to server-rendered pages. Postgres is the store (psycopg2-binary), Redis is used for locking and queueing (redis, python-redis-lock), and gunicorn serves the application in production. The machine learning side is TensorFlow 2.21.0, numpy, scipy, opencv-python-headless and annoy. Annoy is a nearest-neighbour library, which is the piece that would let a face or object embedding be matched against the rest of the library. Import is driven by asyncinotify, so the server watches the photo directory for new files rather than requiring a manual rescan, and python-dateutil, pytz and pyshp suggest EXIF dates and location data are part of the pipeline. None of this is documented in the README beyond the feature list; the dependency file is the clearest statement of how the pieces fit.

Installing Photonix with Docker Compose and importing your first photos

The README gives a Compose-based install using the pre-built image. Create a directory, download the example Compose file into it and make a place for the photos:

mkdir photonix
cd photonix
curl https://raw.githubusercontent.com/photonixapp/photonix/master/docker/docker-compose.example.yml > docker-compose.yml
mkdir -p  data/photos

The README then says to bring the stack up with docker-compose up, which pulls and runs the required images. A few seconds after starting, the web interface should answer on port 8888. The README does not document a first-run setup wizard, so the account and library are created from the command line in a second terminal:

docker-compose run photonix python photonix/manage.py createsuperuser --username USERNAME --email example@example.com
docker-compose run photonix python photonix/manage.py create_library USERNAME "My Library"

Replace USERNAME with your own. After that, move photos into data/photos and the README states they should get detected and imported immediately. The README warns that you are responsible for keeping your own backups in case of error, and notes that the database, thumbnails and cache data are stored separately from the photos, so mounting your real collection does not scatter generated files through it. If you want to work on the code rather than run it, the Makefile offers make build, make start, make shell and make test against docker/docker-compose.dev.yml.

Where Photonix will disappoint you

The README states the project is not feature complete for version 1.0 and that you should expect broken parts. That is not modesty; it is the operating assumption. The newest release listed is v0.24.0 from 2021-11-18, while the last push to the default branch was 2026-07-21. Code is moving; tagged releases are not. If you install from a version tag rather than from master, you are installing something roughly five years old, and the requirements.txt in the repository (Django 6.0.7, TensorFlow 2.21.0, Pillow 12.3.0) reflects the current tree, not that release. The README documents no rollback procedure for a failed upgrade, no migration path between versions and no export format, so a library built today has no documented way out. The upgrade instructions are kill, pull and bring back up, which assumes the schema migration succeeds. There is also no documented multi-user permission model beyond creating users, and no statement about what happens when the watcher misses a file. Treat the import pipeline as something to verify on a copy of your library before trusting it with the original.

Photonix compared with a folder-based server like PhotoPrism or Immich

The closest alternatives are other self-hosted photo servers, and the difference is in how much the machine does for you and how much the project promises. A conventional folder-based server indexes filenames, dates and EXIF, and leaves the organising to you. Photonix puts TensorFlow, OpenCV and Annoy inside the stack so that object, face and colour analysis happen during import, and the README frames that automatic filtering as the point of the product. The trade-off is weight and predictability: a stack containing TensorFlow and a nearest-neighbour index has more moving parts than a server that only reads EXIF, and more places for an import to fail quietly. Immich and PhotoPrism are not named in the README, so the honest comparison is structural rather than a feature table: Photonix is a Django and GraphQL application with a React client, distributed as a Docker image and a Compose file, and its own README positions it as pre-1.0. If your requirement is a finished product with a mobile app and a documented backup story, a folder-based server is the safer choice. If your requirement is automatic tagging of a large local collection and you can tolerate rough edges, Photonix is aimed exactly at that.

Licence, upgrades and what maintenance actually costs

Photonix is AGPL-3.0. For a home server that you run for yourself, the practical effect is that the source is available and modifications you distribute carry the same licence. If you were considering embedding Photonix in a product or offering it as a hosted service, the AGPL's network clause is the part to read with a lawyer; nothing here is legal advice. On maintenance, the repository is not archived and the last push was on 2026-07-21, two months before this article, so the codebase is being touched. That is not the same as a supported release cadence: the newest tagged release is v0.24.0 from 2021-11-18. Running a pre-built image means you inherit whatever master contains at pull time, and the README's upgrade path is docker-compose pull followed by docker-compose up, with no documented way to pin or roll back. The dependency list is broad, including TensorFlow, OpenCV, Django and Postgres drivers, so a rebuild can pull in a large set of new versions at once. Budget for that: keep the Compose file and the data directories under version control or backup, and test an upgrade on a second copy before running it against the library you care about.

Editorial conclusion

Adopt Photonix if you want a self-hosted library that tags itself and you are comfortable running Docker Compose and creating the first user from the command line. Do not adopt it if you need a stable, feature-complete photo manager: the README states the project is in development and not feature complete for version 1.0. Before pointing it at your only copy of a photo collection, verify the mount path in docker-compose.yml, confirm where the database and thumbnails are written, and decide who owns backups, because the README puts that responsibility on you.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. photonixapp/photonix on GitHub
3. Project website
4. README
5. Releases