Pixelfed is an open-source, decentralized image-sharing platform designed as a privacy-focused alternative to Instagram. Built on the ActivityPub protocol, it enables federation with other platforms (like Mastodon) while giving users complete control over their data. This guide will walk you through deploying, configuring, and managing Pixelfed on your self-hosted server, covering installation, Nginx setup, logging, backups, updates, and its unique features.
Installing Pixelfed
📦 Docker/Docker Compose Setup
Here’s how to deploy Pixelfed using Docker Compose for a quick and efficient containerized setup. Create a docker-compose.yml file with the following content:
version: '3.8'
services:
pixelfed:
image: pixelfed/pixelfed:latest
container_name: pixelfed
restart: unless-stopped
ports:
- "8080:80"
environment:
APP_NAME: "Pixelfed"
APP_ENV: "production"
APP_KEY: "base64:GENERATE_YOUR_SECRET_KEY"
APP_DEBUG: "false"
DB_CONNECTION: "mysql"
DB_HOST: "db"
DB_PORT: "3306"
DB_DATABASE: "pixelfed"
DB_USERNAME: "pixelfed_user"
DB_PASSWORD: "strongpassword"
db:
image: mysql:5.7
container_name: pixelfed_db
restart: unless-stopped
environment:
MYSQL_ROOT_PASSWORD: "rootpassword"
MYSQL_DATABASE: "pixelfed"
MYSQL_USER: "pixelfed_user"
MYSQL_PASSWORD: "strongpassword"
volumes:
- pixelfed_db:/var/lib/mysql
volumes:
pixelfed_db:
After saving the file, run the following commands to deploy and start Pixelfed:
docker-compose up -d
## View running services
docker ps
🚀 Manual Installation
For those who prefer manual installation on a Linux server, follow these steps:
- Install necessary dependencies:
sudo apt update
sudo apt install -y php-cli php-mbstring php-xml php-curl php-bcmath composer git curl unzip nginx mysql-server
- Clone the Pixelfed repository:
git clone https://github.com/pixelfed/pixelfed.git
cd pixelfed
- Configure environment variables:
cp .env.example .env
nano .env
## Set database credentials, domain, and other settings
- Install dependencies and set up the application:
composer install --no-dev
php artisan key:generate
php artisan storage:link
php artisan migrate --force
- Serve the application:
php artisan serve --host=0.0.0.0 --port=8080
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
Set up Nginx to route traffic to Pixelfed. Create an Nginx server block configuration:
server {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff|woff2|ttf|svg|eot|otf)$ {
expires max;
log_not_found off;
}
}
Save the file under /etc/nginx/sites-available/pixelfed and enable it:
sudo ln -s /etc/nginx/sites-available/pixelfed /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure your site with Let's Encrypt by installing Certbot and obtaining a certificate:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
## Test automatic renewal
sudo certbot renew --dry-run
🛠️ Testing and Reloading Nginx
Ensure the configuration is valid and reload Nginx to apply changes:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging Pixelfed
🗃️ Enabling Debug Logs
To enable debug-level logging, edit the .env file in your Pixelfed directory:
nano .env
## Change:
APP_DEBUG=true
📄 Viewing Logs
For Docker-based deployments, view logs with:
docker logs -f pixelfed
For manual installations, logs are typically in the storage/logs/ directory:
tail -f storage/logs/laravel.log
🛠️ Troubleshooting Common Issues
Check for issues like database connection errors or misconfigured environment variables. Use the logs to identify and resolve the problem:
grep "error" storage/logs/laravel.log
📤 Exporting Logs
Export logs for advanced analysis using tools like ELK Stack:
docker logs pixelfed > pixelfed_logs.txt
Backup and Restore
🗂️ File-Based Backups
Backup critical files and directories:
tar -czvf pixelfed_backup.tar.gz pixelfed/.env pixelfed/storage
🔄 Database Backups
Export the database:
docker exec pixelfed_db mysqldump -u pixelfed_user -p pixelfed > pixelfed_db_backup.sql
Restore the database:
docker exec -i pixelfed_db mysql -u pixelfed_user -p pixelfed < pixelfed_db_backup.sql
📅 Automated Backup Scripts
Schedule periodic backups using a cron job. Edit your crontab:
crontab -e
## Add the following line for nightly backups:
0 2 * * * tar -czvf /backups/pixelfed_backup_$(date +\%F).tar.gz /path/to/pixelfed && docker exec pixelfed_db mysqldump -u pixelfed_user -p pixelfed > /backups/pixelfed_db_$(date +\%F).sql
Updating and Upgrading Pixelfed
⬆️ Updating Docker Images
Pull the latest Docker image and redeploy:
docker-compose pull
docker-compose down
docker-compose up -d
🛠️ Manual Updates
For manual installations, pull the latest code and update dependencies:
cd pixelfed
git pull origin main
composer install --no-dev
php artisan migrate --force
🔍 Checking for Updates
Check Pixelfed's GitHub repository for new releases or version tags: Pixelfed GitHub.
Leveraging Pixelfed’s Unique Features
🔧 Enabling APIs
Enable Pixelfed’s API for integration with other services. In the .env file, set:
ACTIVITYPUB=true
API_ENABLED=true
Then restart the application:
docker-compose restart
🌟 Advanced Configurations
Adjust Pixelfed’s advanced features, like federation settings, by editing the .env file. Example:
INSTANCES_ALLOWED="instance1.com,instance2.com"
Wrapping Up
Self-hosting Pixelfed empowers you with full control over your image-sharing platform, ensuring privacy and customization to suit your needs. This guide covered everything from installation and configuration to advanced features and backups. Start implementing the examples above to fully harness Pixelfed’s capabilities, and enjoy the benefits of decentralized social media!
