This is an old revision of the document!

pixelfed
Jonathan Haack
Haack's Networking
support@haacksnetworking.org

pixelfed

Complete Pixelfed Installation Tutorial: Fresh Setup or Full Rebuild

This tutorial provides a comprehensive, step-by-step guide to installing or rebuilding a Pixelfed instance from scratch on a Ubuntu-based system (assuming a VM or server with Apache, MySQL/MariaDB, Redis, and PHP already partially set up). It incorporates all necessary configurations, including PHP dependencies, database setup, Git cloning, environment configuration, migrations, OAuth setup, queue worker (Horizon), Apache virtual hosts, .htaccess for rewrites, image storage fixes, admin user creation, verification checks, debugging commands, and update instructions.

The process assumes you're running as a user with sudo privileges. It destroys any existing Pixelfed installation and database, then rebuilds everything fresh. Run commands sequentially. If you're starting from a completely bare system, ensure basic packages like Apache, MariaDB, Redis, and Git are installed first (e.g., via sudo apt install apache2 mariadb-server redis-server git).

Prerequisites: Install PHP 8.4 and Dependencies

Pixelfed requires PHP 8.4 with specific extensions for database, image processing, Redis, and more. Update your package list and install them.

cd /var/www
sudo apt update
sudo apt install php8.4-fpm php8.4-mysql php8.4-curl php8.4-gd php8.4-mbstring php8.4-xml php8.4-zip php8.4-bcmath php8.4-intl php8.4-redis php8.4-imagick php8.4-imap php8.4-ldap -y
sudo systemctl restart php8.4-fpm

This ensures PHP-FPM is running and ready for Apache integration.

Step 1: Nuke the Old Database (If Exists)

Log in to MySQL/MariaDB as root and drop any existing Pixelfed-related database to start fresh.

mysql -u root -p

Inside the MySQL shell, run:

DROP DATABASE IF EXISTS pixelfed;
DROP DATABASE IF EXISTS pixel;
EXIT;

Step 2: Create the New 'pixel' Database and User

Create a new database named 'pixel' with a dedicated user for security. Log in to MySQL as root again.

mysql -u root -p

Inside the MySQL shell, run:

CREATE DATABASE pixel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'pixel'@'localhost' IDENTIFIED BY 'lweRt5-xmcvQW2_poRtyUG51.78345^';
GRANT ALL PRIVILEGES ON pixel.* TO 'pixel'@'localhost';
FLUSH PRIVILEGES;
EXIT;

This sets up a UTF-8 compatible database optimized for Pixelfed's schema.

Step 3: Nuke the Old Pixelfed Directory (If Exists)

sudo rm -rf /var/www/pixelfed

Step 4: Clone Fresh Pixelfed from Git (Dev Branch)

Clone the latest development branch from the official repository. The 'dev' branch often includes fixes and features not yet in stable.

cd /var/www
git clone -b dev https://github.com/pixelfed/pixelfed.git pixelfed

Step 5: Set Permissions for the New Installation

sudo chown -R www-data:www-data /var/www/pixelfed
sudo chmod -R 775 /var/www/pixelfed/storage /var/www/pixelfed/bootstrap/cache

This prevents permission errors during runtime, such as failed uploads or cache writes.

Step 6: Install Dependencies with Composer

cd /var/www/pixelfed
sudo -u www-data composer install --no-dev --optimize-autoloader

This pulls in Laravel and other required packages without development tools for a production setup.

Step 7: Configure the .env File

sudo nano /var/www/pixelfed/.env

Paste or update with the following content (replace placeholders if needed, e.g., passwords, domains, or mail settings):

APP_NAME="GNU/Linux Pics"
APP_ENV=production
APP_KEY= # Generated later
APP_DEBUG=false
APP_URL=https://gnulinux.pics
APP_DOMAIN=gnulinux.pics
ADMIN_DOMAIN=gnulinux.pics
SESSION_DOMAIN=gnulinux.pics
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=pixel
DB_USERNAME=pixel
DB_PASSWORD=lweRt5-xmcvQW2_poRtyUG51.78345^
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
REDIS_CLIENT=predis
REDIS_SCHEME=tcp
CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
HORIZON_PREFIX=horizon-
MAIL_MAILER=smtp
MAIL_HOST=mail.haacksnetworking.org
MAIL_PORT=587
MAIL_USERNAME=webmaster
MAIL_PASSWORD==R0undC@arg3dTer$sProduc3!inu73@4r!ied
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=webmaster@haacksnetworking.org
MAIL_FROM_NAME="GNU/Linux Pics"
ACTIVITY_PUB=true
AP_REMOTE_FOLLOW=true
AP_INBOX=true
AP_OUTBOX=true
AP_SHAREDINBOX=true
RELAY=true
OPEN_REGISTRATION=true
ENFORCE_EMAIL_VERIFICATION=true
PF_MAX_USERS=1000
PF_OPTIMIZE_IMAGES=true
IMAGE_QUALITY=80
MAX_PHOTO_SIZE=15000
MAX_CAPTION_LENGTH=500
MAX_ALBUM_LENGTH=4
INSTANCE_DISCOVER_PUBLIC=true
PF_ENABLE_CLOUD=false
FILESYSTEM_CLOUD=s3
#AWS_ACCESS_KEY_ID=
#AWS_SECRET_ACCESS_KEY=
#AWS_DEFAULT_REGION=
#AWS_BUCKET=
#AWS_URL=
#AWS_ENDPOINT=
#AWS_USE_PATH_STYLE_ENDPOINT=false

Save and exit.

Step 8: Run Database Migrations

sudo -u www-data php artisan migrate --force

Step 9: Create the Public Storage Symlink (Critical for Images)

sudo -u www-data php artisan storage:link

Verify the symlink:

ls -l /var/www/pixelfed/public/storage

Expected output: storage → ../storage/app/public

If images fail to display after uploads, recheck permissions:

sudo chown -R www-data:www-data /var/www/pixelfed/storage
sudo chmod -R 775 /var/www/pixelfed/storage
#oauth bits require stronger perms
sudo chmod 600 /var/www/pixelfed/storage/oauth-private.key
sudo chmod 600 /var/www/pixelfed/storage/oauth-public.key

Step 10: Generate Application Key

sudo -u www-data php artisan key:generate

Step 11: Set Up Passport for OAuth

sudo -u www-data php artisan passport:keys --force
sudo -u www-data php artisan passport:install --force

Step 12: Set Up Horizon for Queue Worker

sudo -u www-data php artisan horizon:install

Step 13: Cache Configurations, Routes, and Views

sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo -u www-data php artisan view:cache
sudo -u www-data php artisan optimize

Step 14: Configure Apache Virtual Hosts

For the non-SSL site (HTTP redirect):

sudo nano /etc/apache2/sites-enabled/000-default.conf

Paste:

<VirtualHost *:80>
    ServerName gnulinux.pics
    RewriteEngine On
    RewriteCond %{SERVER_NAME} =gnulinux.pics
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

For the SSL site:

sudo nano /etc/apache2/sites-enabled/000-default-le-ssl.conf

Paste:

<VirtualHost *:443>
    ServerName gnulinux.pics
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/gnulinux.pics/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/gnulinux.pics/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf
    DocumentRoot /var/www/pixelfed/public
    <Directory /var/www/pixelfed/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    <FilesMatch \.php$>
        SetHandler "proxy:unix:/run/php/php8.4-fpm.sock|fcgi://localhost/"
    </FilesMatch>
    LimitRequestBody 524288000
    ErrorLog ${APACHE_LOG_DIR}/gnulinux-pics_error.log
    CustomLog ${APACHE_LOG_DIR}/gnulinux-pics_access.log combined
</VirtualHost>

Ensure AllowOverride All in main config:

sudo nano /etc/apache2/apache2.conf

In the <Directory /var/www/> block ensure:

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

Step 15: Configure .htaccess for URL Rewrites

sudo nano /var/www/pixelfed/public/.htaccess

Paste:

Options +FollowSymLinks -Indexes
RewriteEngine On
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]

Step 16: Create and Enable Horizon Systemd Service

sudo nano /etc/systemd/system/pixelfed.service

Paste:

[Unit]
Description=Pixelfed Horizon Queue Worker (Laravel Horizon)
After=network.target apache2.service php8.4-fpm.service redis-server.service mariadb.service
Wants=apache2.service php8.4-fpm.service redis-server.service mariadb.service
 
[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/pixelfed
ExecStart=/usr/bin/php artisan horizon
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal
NoNewPrivileges=yes
PrivateTmp=true
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/www/pixelfed/storage
ReadWritePaths=/var/www/pixelfed/bootstrap/cache
 
[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable pixelfed.service
sudo systemctl restart pixelfed.service
sudo systemctl status pixelfed.service
journalctl -u pixelfed.service -n 50

Step 17: Restart All Services

sudo apache2ctl configtest
sudo systemctl reload apache2
sudo systemctl restart apache2 php8.4-fpm pixelfed.service redis-server

Step 18: Create Admin User

sudo -u www-data php artisan user:create

Follow prompts (example values):

Name: Admin
Username: admin
Email: webmaster@haacksnetworking.org
Password: 8gHpw#45_mnb456Cv-plw@33:pw
Make this user an admin? yes

Step 19: Verification and Debugging Checks

Check Redis:

redis-cli ping
redis-cli keys "horizon:*"
sudo systemctl status redis-server
sudo systemctl status pixelfed.service
journalctl -u pixelfed.service -n 50

Verify queue config:

sudo -u www-data php artisan config:show queue | grep default

Check well-known / NodeInfo:

curl -s https://gnulinux.pics/.well-known/nodeinfo
curl -s https://gnulinux.pics/api/nodeinfo/2.0
sudo -u www-data php artisan route:list | grep -i nodeinfo

Federation test:

curl -I https://pixelfed.social/.well-known/nodeinfo
curl -I https://mastodon.social/.well-known/nodeinfo

Check logs:

tail -n 100 /var/www/pixelfed/storage/logs/laravel.log | grep -i "activitypub\|federat\|outbox\|inbox\|error\|fail\|exception"

Update Instructions

cd /var/www/pixelfed
git pull origin dev
sudo -u www-data composer install --no-dev --optimize-autoloader
sudo -u www-data php artisan migrate --force
sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo systemctl restart pixelfed.service apache2 php8.4-fpm redis-server

Always check GitHub for release notes before updating.

— oemb1905 2026/03/01 17:36

Haack's Wiki

User Tools

Site Tools

Complete Pixelfed Installation Tutorial: Fresh Setup or Full Rebuild

Prerequisites: Install PHP 8.4 and Dependencies

Step 1: Nuke the Old Database (If Exists)

Step 2: Create the New 'pixel' Database and User

Step 3: Nuke the Old Pixelfed Directory (If Exists)

Step 4: Clone Fresh Pixelfed from Git (Dev Branch)

Step 5: Set Permissions for the New Installation

Step 6: Install Dependencies with Composer

Step 7: Configure the .env File

Step 8: Run Database Migrations

Step 9: Create the Public Storage Symlink (Critical for Images)

Step 10: Generate Application Key

Step 11: Set Up Passport for OAuth

Step 12: Set Up Horizon for Queue Worker

Step 13: Cache Configurations, Routes, and Views

Step 14: Configure Apache Virtual Hosts

Step 15: Configure .htaccess for URL Rewrites

Step 16: Create and Enable Horizon Systemd Service

Step 17: Restart All Services

Step 18: Create Admin User

Step 19: Verification and Debugging Checks

Update Instructions

Page Tools