techne/pixelfed.org

#+title: Pixelfed

** Install Pixelfed on Debian (Bookworm)

*** Prerequisites

Install dependencies.

#+BEGIN_SRC shell
apt install -y php-bcmath php-curl exif php-gd php8.2-common php-intl php-json php-mbstring libcurl4-openssl-dev php-redis php-tokenizer php-xml php-zip php-pgsql php-fpm composer
#+END_SRC

Set the following upload limits for PHP processes.

#+BEGIN_SRC ini
post_max_size = 2G
file_uploads = On
upload_max_filesize = 2G
max_file_uploads = 20
max_execution_time = 1000
#+END_SRC

Create the PostgreSQL database:

#+BEGIN_SRC shell
sudo -u postgres psql
#+END_SRC

#+BEGIN_SRC sql
CREATE USER pixelfed CREATEDB;
CREATE DATABASE pixelfed;
GRANT ALL PRIVILEGES ON DATABASE pixelfed TO pixelfed;
\q
#+END_SRC

Create dedicated pixelfed user.

#+BEGIN_SRC shell
useradd -rU -s /bin/bash pixelfed
#+END_SRC

Configure PHP-FPM pool and socket.

#+BEGIN_SRC shell
cd /etc/php/8.2/fpm/pool.d/
cp www.conf pixelfed.conf
#+END_SRC

Edit ~/etc/php/8.2/fpm/pool.d/pixelfed.conf~.

#+BEGIN_SRC ini
; use the username of the app-user as the pool name, e.g. pixelfed
[pixelfed]
user = pixelfed
group = pixelfed
; to use a tcp socket, e.g. if running php-fpm on a different machine than your app:
;    (note that the port 9001 is used, since php-fpm defaults to running on port 9000;)
;    (however, the port can be whatever you want)
; listen = 127.0.0.1:9001;
;    but it's better to use a socket if you're running locally on the same machine:
listen = /run/php-fpm/pixelfed.sock
listen.owner = caddy
listen.group = caddy
listen.mode = 0660
; [...]
#+END_SRC

*** Installation

**** Setup Pixelfed files

Download the source from GitHub.

#+BEGIN_SRC shell
cd /usr/share/caddy
git clone -b dev https://github.com/pixelfed/pixelfed.git pixelfed
#+END_SRC

Set correct permissions.

#+BEGIN_SRC shell
cd pixelfed
chown -R pixelfed:pixelfed .
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
#+END_SRC

Become the pixelfed user.

#+BEGIN_SRC shell
su - pixelfed
#+END_SRC

Initialize PHP dependencies.

#+BEGIN_SRC shell
composer update
composer install --no-ansi --no-interaction --optimize-autoloader
#+END_SRC

**** Configure environment variables

#+BEGIN_SRC shell
cp .env.example .env
#+END_SRC

Edit ~/usr/share/caddy/pixelfed/.env~.

#+BEGIN_SRC shell
APP_NAME="hyperreal's Pixelfed"
APP_DEBUG="false"
APP_URL="https://pixelfed.hyperreal.coffee"
APP_DOMAIN="pixelfed.hyperreal.coffee"
ADMIN_DOMAIN="pixelfed.hyperreal.coffee"
SESSION_DOMAIN="pixelfed.hyperreal.coffee"
DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=pixelfed
DB_USERNAME=pixelfed
DB_PASSWORD=<password>
REDIS_HOST=localhost
REDIS_PORT=6379
MAIL_FROM_ADDRESS=onboarding@resend.dev
MAIL_FROM_NAME=Pixelfed
MAIL_ENCRYPTION=tls
MAIL_DRIVER=smtp
MAIL_HOST=smtp.resend.com
MAIL_PORT=465
MAIL_USERNAME=resend
MAIL_PASSWORD=<resend API key>
ACTIVITY_PUB=true
AP_REMOTE_FOLLOW=true
#+END_SRC

**** Setting up services

These commands should only be run one time.

#+BEGIN_SRC shell
php artisan key:generate
#+END_SRC

Link the ~storage/~ directory to the application.

#+BEGIN_SRC shell
php artisan storage:link
#+END_SRC

Run database migrations.

#+BEGIN_SRC shell
php artisan migrate --force
#+END_SRC

#+BEGIN_QUOTE
If the above command fails due to insufficient privileges, then the pixelfed database user needs permission to create tables in the public schema. When we created the database, we ran ~GRANT ALL PRIVILEGES ON DATABASE pixelfed TO pixelfed;~ in the psql shell. This granted the pixelfed database user privileges on the database /itself/, not on things within the database. To fix this, the pixelfed database user needs to /own/ the database and all within it, so go back to the psql shell and run ~ALTER DATABASE pixelfed OWNER TO pixelfed;~

See [[https://anonoverflow.hyperreal.coffee/questions/74110708/postgres-15-permission-denied-for-schema-public]]
#+END_QUOTE

To enable ActivityPub federation:

#+BEGIN_SRC shell
php artisan instance:actor
#+END_SRC

To have routes cached, run the following commands now, and whenever the source code changes or if you change routes.
#+BEGIN_SRC shell
php artisan route:cache
php artisan view:cache
#+END_SRC

Run this command whenever you change the ~.env~ file for the changes to take effect.

#+BEGIN_SRC shell
php artisan config:cache
#+END_SRC

Use Laravel Horizon for job queueing.

#+BEGIN_SRC shell
php artisan horizon:install
php artisan horizon:publish
#+END_SRC

Create a systemd service unit for Pixelfed task queueing.

#+BEGIN_SRC systemd
[Unit]
Description=Pixelfed task queueing via Laravel Horizon
After=network.target
Requires=postgresql
Requires=php8.2-fpm
Requires=redis-server
Requires=caddy

[Service]
Type=simple
ExecStart=/usr/bin/php /usr/share/caddy/pixelfed/artisan horizon
User=pixelfed
Restart=on-failure

[Install]
WantedBy=multi-user.target
#+END_SRC

Use Cron to schedule periodic tasks. As the pixelfed user, run ~crontab -e~.

#+BEGIN_SRC shell
 * * * * * /usr/bin/php /usr/share/caddy/pixelfed/artisan schedule:run >> /dev/null 2>&1
#+END_SRC

Create a Caddyfile that translates HTTP web requests to PHP workers.

#+BEGIN_SRC caddy
pixelfed.hyperreal.coffee {
    root * /usr/share/caddy/pixelfed/public

    header {
        X-Frame-Options "SAMEORIGIN"
        X-XSS-Protection "1; mode=block"
        X-Content-Type-Options "nosniff"
    }

    php_fastcgi unix//run/php/php-fpm.sock
    file_server
}
#+END_SRC

** Updating Pixelfed

#+BEGIN_SRC shell
sudo su - pixelfed
cd /usr/share/caddy/pixelfed
git reset --hard
git pull origin dev
composer install
php artisan config:cache
php artisan route:cache
php artisan migrate --force
#+END_SRC