Pixelfed: self-hosting a federated photo network on Laravel

The problem Pixelfed solves, and who ends up running it

Pixelfed is a photo sharing server, not a service you sign up to once. The README frames it as photo sharing without algorithmic barriers, and the repository is the software an operator installs to run one instance of that idea. The unit of adoption is an instance, not an account. You become the person who owns the database, the storage, the queue and the upgrade path.

That shapes the audience. It is for someone who wants a photo-first timeline that federates with the wider fediverse, and who is willing to run a Laravel application to get it. Topics on the repository list activitypub, federation, laravel and social-network, which is an accurate summary of what you are taking on: a full web application plus a federation protocol implementation.

The software is licensed AGPL-3.0 and the default branch is dev, with v0.14.2 released on 2026-09-21. The last push to the repository was on 2026-09-21, so the codebase is moving. Anyone who wants a frozen artifact to deploy once and forget should read that as a warning rather than a feature.

How the pieces fit: Laravel, Horizon, Redis and ActivityPub

The stack is visible in the repository root. There is an artisan file, app/, config/, routes/, database/ and resources/, which is a standard Laravel layout. Front-end assets are built with Laravel Mix: package.json defines development, watch, hot and production scripts, and webpack.mix.js sits at the root. The UI is Vue 2 with Vuex and vue-router, plus bootstrap-vue, and media handling pulls in hls.js and blurhash. None of this is exotic, but it is a lot of moving parts for a photo site.

The docker-compose.yml shows the intended runtime shape. A db service runs mysql:9 with a volume at ./mysql-9-data. A redis service runs redis:7-alpine with appendonly enabled. A pixelfed service builds from the local Dockerfile, publishes port 8080, and sets SSL_MODE to off on the assumption that a reverse proxy terminates TLS. The comment above that block says the app, a Horizon queue worker and a scheduled task all run from the same image, and AUTORUN_ENABLED is set to true.

Federation is opt-in at the configuration layer. .env.example ships ACTIVITY_PUB, AP_REMOTE_FOLLOW, AP_INBOX, AP_OUTBOX and AP_SHAREDINBOX all set to false. A private instance that never talks to other servers is a supported starting point; turning those keys on is what makes the instance part of the fediverse. The Dockerfile is also worth reading for a different reason: it compiles ffmpeg from source with --toolchain=hardened and a long list of codec flags, because the server processes untrusted uploaded media.

Installing Pixelfed with Docker Compose and reaching the web UI

The repository ships both a Dockerfile and a docker-compose.yml, and DOCKER_COMPOSE_SETUP.md exists at the root for the container path. The .env.example file is the template for configuration. Copy it to .env and fill in the values before starting anything, because the compose file reads it via env_file for both the database and the app.

cp .env.example .env

The database block in .env.example defaults to DB_CONNECTION mysql on 127.0.0.1:3306 with database, username and password all set to pixelfed. The compose file overrides the host by service name, so the app reaches the db container over the pixelfed-network. Redis defaults to the predis client on port 6379.

docker compose up -d

The pixelfed service publishes 8080:8080, so the web UI answers on that port behind whatever reverse proxy you put in front of it. With AUTORUN_ENABLED set to true, the image runs the Laravel setup steps on boot rather than requiring a manual artisan sequence. The first thing to check after the containers report healthy is that the app can reach MySQL, since the db service has a healthcheck using mysqladmin ping with a 30 second start period.

Before opening registration, decide the instance policy. .env.example sets OPEN_REGISTRATION to false and ENFORCE_EMAIL_VERIFICATION to false, with PF_MAX_USERS at 1000. Leaving open registration off until you have tested uploads and federation is the safer order.

Database support is the sharpest edge in the README

The README is unusually direct about this. MySQL 9 and above is officially supported, MariaDB 11 and above is officially supported, and PostgreSQL 14 and above is best effort as of writing. The note that follows says the ecosystem needs work to test the codebase in a database-agnostic way, and that doing so would require considerable engineering effort.

Read that as a real constraint rather than a formality. If your infrastructure standard is PostgreSQL, Pixelfed is the wrong tool, and the project says so itself. The compose file reinforces the point by shipping mysql:9, not a Postgres image. There is also a strict mode asymmetry: the README notes strict mode is not the default on MySQL but is the default on MariaDB, which means the same schema and queries run under different validation rules depending on which of the two supported engines you pick. If you hit an error that looks like a data truncation or a default-value problem, that difference is the first thing to check.

The second limitation is operational. The compose file runs the web app, the Horizon queue worker and the scheduler from one image with AUTORUN_ENABLED on. That is convenient for a first boot and less convenient when a queue worker needs to be restarted independently of the web tier. The README does not document a rollback procedure for a failed upgrade, and the CHANGELOG.md is the place to look for what changed between releases such as v0.14.0, v0.14.1 and v0.14.2.

Pixelfed against Mastodon and against running a plain gallery

The obvious comparison is Mastodon, because both speak ActivityPub and both federate. The difference is in the data model. Mastodon is built around short text posts with attached media; Pixelfed is built around photos, albums and a grid, with MAX_ALBUM_LENGTH and MAX_CAPTION_LENGTH as first-class configuration keys. If your community is text-first with occasional images, Mastodon is the closer fit. If the image is the post and the caption is secondary, Pixelfed is the one designed for that.

The second comparison is a self-hosted gallery such as any static or CMS-based photo site. That option gives you no federation at all: your photos stay on your server and reach only the people you send there. Pixelfed's AP_INBOX, AP_OUTBOX and AP_SHAREDINBOX keys are exactly the switch between those two worlds. Turning them on means your instance has to handle inbound traffic from other servers, which is a different operational burden from serving pages to your own visitors.

The third comparison is simply joining an existing Pixelfed instance instead of running one. The README points to the fediverse and links to a user count from FediDB, and it offers YunoHost and RepoCloud as hosted deployment routes. If you want the photo experience without the Laravel application, that is the path, and it costs you control over registration policy, storage and upgrades.

Licence, maintenance and what an upgrade actually costs

Pixelfed is AGPL-3.0. That matters for anyone who modifies the code and runs it as a network service, because the licence's network clause is the reason it was chosen over a permissive licence. The repository does not offer legal advice and neither does this article; if you plan to fork and operate a modified instance, read the LICENSE file and get your own answer.

The maintenance picture is straightforward from the repository facts. The repository is not archived. The last push was on 2026-09-21, and v0.14.2 was released the same day, with v0.14.1 and v0.14.0 two days earlier. That is a fast release cadence, and it means upgrade cost is not a one-off. Every release can touch the Laravel application, the front-end bundle built by Mix, and the federation code.

Budget for the upgrade path accordingly. Because the default branch is dev, tracking the branch is not the same as tracking tagged releases. The image is built from the local Dockerfile, so a rebuild is part of every upgrade, and that Dockerfile compiles ffmpeg from source, which is the slowest step in the build and one you should expect to repeat. The .env.example file is also a moving target: if a release adds a key, your existing .env will not have it, and the compose file reads that file directly.

Editorial conclusion

Adopt Pixelfed if you already run PHP and MySQL or MariaDB and want a photo-first instance that federates with the wider network. Do not adopt it if your database is PostgreSQL or you expect a container to be production-ready on first boot. Before committing, read DOCKER_COMPOSE_SETUP.md, check which IMAGE_DRIVER your host supports, and confirm that ACTIVITY_PUB and the AP_* keys match the federation you intend to enable.

Frequently asked questions

Official sources

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