Deploy Pixelfed

Deploy and Host Pixelfed on Railway

Pixelfed is an open-source, federated photo-sharing platform — an Instagram-shaped app you own, built on Laravel and speaking ActivityPub, so people on Mastodon, Misskey and any other fediverse server can follow your account and see your photos in their timeline. Photographers, camera clubs and communities self-host Pixelfed to publish images without an algorithmic feed, without advertising, and without a company deciding what happens to their archive. It ships a web client, albums, stories, collections, hashtags and a Mastodon-compatible API.

Deploy Pixelfed in its production shape rather than a single container. pixelfed serves the web app and API on FrankenPHP and runs Laravel Horizon and the scheduler beside it, because Pixelfed stages uploads on local disk before a queued job moves them. MySQL holds accounts, posts and sessions, Redis backs the cache and every queue, and a pixelfed-media bucket holds photos and videos so the disk is never the limit. The media service signs reads against that bucket and serves objects on their own domain, while mailpit captures confirmation and reset mail. Self-host Pixelfed on Railway with all six connected.

Getting Started with Pixelfed on Railway

Sign in at /login as the administrator created on first boot: the credentials are the PIXELFED_ADMIN_EMAIL and PIXELFED_ADMIN_PASSWORD variables on the pixelfed service, username curator. It is created only while the instance has no users, so a password you change later is never reverted — change it first. Then open Create New Post, upload a photo and publish it: the file is optimised by a queue worker, moved to object storage and served back from the media domain — the fastest check that every service is talking to the others. Confirm it renders on your profile grid, then use Admin Dashboard → Settings for the instance name, description, rules and Registration Status. Federation is on: follow @yourname@your-domain from Mastodon to watch posts arrive. Mailpit captures mail rather than delivering it, so point the MAIL_* variables at a real SMTP relay before inviting anyone.

About Hosting Pixelfed

Pixelfed is a photo-sharing server, not a gallery script: every account is a real ActivityPub actor with a public key, an inbox and an outbox, and posts are delivered to followers on other servers as they are published.

• Photo and video posts with albums, alt text, content warnings and location tagging
• ActivityPub federation: remote follows, likes, replies and boosts across the fediverse
• Stories, collections, bookmarks, hashtag following and a chronological home feed
• A Mastodon-compatible REST API for official and third-party mobile clients
• Moderation: reports, autospam, per-domain blocks, suspension, an admin dashboard

pixelfed answers HTTP and runs Horizon, which works fifteen queues covering federation delivery, inbox handling, feed fan-out and media processing. MySQL is the system of record, Redis carries the queues and cache, the bucket stores every uploaded file, and the media gateway signs reads so images are fetchable without the bucket being open.

Why Deploy Pixelfed on Railway

• MySQL, Redis and object storage are provisioned and wired at deploy time
• Media, queues, mail capture and the app come up together, already connected
• HTTPS, a public domain and health checks are handled for you
• Scaling is a slider, and the bucket grows independently of the disk

Common Use Cases

• A personal photography portfolio that federates, so Mastodon followers see new work
• A community or camera-club instance posting to a shared local feed, with real moderation tools
• A private family or team instance: registration closed, accounts created by the admin

Dependencies for Pixelfed

• pixelfed — ghcr.io/pixelfed/pixelfed:latest, from pixelfed/pixelfed; web app, API, Horizon, scheduler
• MySQL — mysql:9.4; the image bundles pdo_mysql only, so MySQL is the database
• Redis — redis:8.2; Horizon's queue backend and the application cache
• pixelfed-media — Railway object storage; every photo, video and thumbnail
• media — a dependency-free Node service that signs reads against that bucket
• mailpit — axllent/mailpit:latest; captures outgoing mail so sign-up is testable

Environment Variables Reference

Deployment Dependencies

• Source: github.com/pixelfed/pixelfed · image: ghcr.io/pixelfed/pixelfed
• Docs: docs.pixelfed.org · runtime: PHP 8.5 on FrankenPHP, Laravel 12, MySQL 9, Redis 8

Hardware Requirements for Self-Hosting Pixelfed

The volume holds Laravel's storage tree, avatars and briefly-staged uploads; photos live in object storage, so it does not grow with the archive. Image optimisation is the CPU-hungry part — raise HORIZON_MAX_PROCESSES and memory together if uploads back up.

Self-Hosting Pixelfed

Outside Railway, Pixelfed runs from its own repository with Docker Compose — clone it, create an environment file from the Docker example, then start the stack:

git clone https://github.com/pixelfed/pixelfed.git
cd pixelfed
cp .env.docker.example .env
docker compose up -d --build

That starts the app, a Horizon worker, a scheduler, MySQL and Redis. The three Pixelfed containers share a ./storage directory, which is why this template runs them in one service. Then generate the instance actor that signs federated requests and create your administrator:

docker compose exec pixelfed php artisan instance:actor
docker compose exec pixelfed php artisan user:create \
  --name="Your Name" --username=curator \
  --email=you@example.com --password='change-me' \
  --is_admin=true --confirm_email=1

Avoid usernames Pixelfed reserves for its own routes — admin, owner, root and support among roughly 350 others — since the CLI skips the sign-up form's validation. On Railway both commands run at boot.

How Much Does Pixelfed Cost to Self-Host?

Pixelfed is free and open source under the AGPL-3.0 licence: no paid tier, no seat count, no hosted edition. On Railway you pay for infrastructure only — the app, MySQL, Redis, the media gateway, mail capture and the storage your photos occupy. Costs scale with traffic, uploads and how many servers you federate with.

FAQ

What is Pixelfed? An open-source photo-sharing platform that federates over ActivityPub. It looks and works like Instagram, but each instance is independent and its accounts can be followed from Mastodon and other fediverse servers.

What does this Railway template deploy? The Pixelfed app with Horizon and the scheduler, MySQL, Redis, an object-storage bucket, a gateway that serves media publicly, and Mailpit for capturing outgoing mail.

Why does the template include MySQL, Redis and object storage? MySQL stores accounts, posts and sessions. Redis carries the cache and the fifteen queues Horizon works, including federation delivery and image processing. Object storage keeps photos off the volume, so the archive grows without resizing a disk.

Where are my photos stored, and how are they served? In the pixelfed-media bucket. Railway's object storage has no anonymous read, so the media service signs each request and streams the object back on its own domain — the one AWS_URL points at.

How do I let other people sign up for my instance? Change Registration Status in Admin Dashboard → Settings. Configure a real SMTP relay first if email verification stays on, since Mailpit captures mail instead of sending it.

Can I use the Pixelfed mobile app, and will my instance federate with Mastodon? Yes to both. OAUTH_ENABLED is true, so official and Mastodon-compatible clients sign in, and ActivityPub is on by default.

How do I connect a custom domain? Add it to the pixelfed service, then update APP_URL, APP_DOMAIN and ADMIN_DOMAIN to match. Do it before the instance federates: changing the domain later breaks the identity remote servers know.