pleroma/docs/installation/openbsd_en.md

Installing on OpenBSD

{! backend/installation/otp_vs_from_source_source.include !}

This guide describes the installation and configuration of Pleroma (and the required software to run it) on a single OpenBSD 7.6 server.

For any additional information regarding commands and configuration files mentioned here, check the man pages online or directly on your server with the man command.

{! backend/installation/generic_dependencies.include !}

Installation

Preparing the system

Required software

To install required packages, run the following command:

# pkg_add erlang%26 elixir gmake git postgresql-server postgresql-contrib cmake libmagic libvips

Pleroma requires a reverse proxy, OpenBSD has relayd in base (and is used in this guide) and packages/ports are available for nginx (www/nginx) and apache (www/apache-httpd). Independently of the reverse proxy, acme-client(1) can be used to get a certificate from Let's Encrypt.

Optional software

• ImageMagick
• ffmpeg
• exiftool

To install the above:

# pkg_add ImageMagick ffmpeg p5-Image-ExifTool

For more information read docs/installation/optional/media_graphics_packages.md:

PostgreSQL

Switch to the _postgresql user and initialize PostgreSQL:

# su _postgresql
$ initdb -D /var/postgresql/data -U postgres

Running PostgreSQL in a different directory than /var/postgresql/data requires changing the daemon_flags variable in the /etc/rc.d/postgresql script.

Enable and start the postgresql service:

# rcctl enable postgresql
# rcctl start postgresql

To check that PostgreSQL started properly and didn't fail right after starting, you can run ps aux | grep postgres, there should be multiple lines of output. Or alternatively run # rcctl check postgresql which should return postgresql(ok).

Configuring Pleroma

Pleroma will be run by a dedicated _pleroma user. Before creating it, insert the following lines in /etc/login.conf:

pleroma:\
	:datasize-max=1536M:\
	:datasize-cur=1536M:\
	:openfiles-max=4096:\
    :setenv=LC_ALL=en_US.UTF-8

This creates a "pleroma" login class and sets higher values than default for datasize and openfiles (see login.conf(5)), this is required to avoid having Pleroma crash some time after starting.

Create the _pleroma user, assign it the pleroma login class and create its home directory (/home/_pleroma/):

# useradd -m -L pleroma _pleroma
# echo 'export VIX_COMPILATION_MODE=PLATFORM_PROVIDED_LIBVIPS' >> /home/_pleroma/.profile

Switch to the _pleroma user:

# su _pleroma

Change to the home directory (/home/_pleroma) and clone the Pleroma repository:

$ cd
$ git clone -b stable https://git.pleroma.social/pleroma/pleroma.git
$ cd pleroma

Pleroma is now installed in /home/_pleroma/pleroma/. To configure it run:

$ mix deps.get
$ MIX_ENV=prod mix pleroma.instance gen # You will be asked a few questions here.
$ cp config/generated_config.exs config/prod.secret.exs

Note: Answer yes when asked to install Hex and rebar3. This step might take some time as Pleroma gets compiled first.

Create the Pleroma database:

# psql -U postgres -f /home/_pleroma/pleroma/config/setup_db.psql

Switch back to the _pleroma user and apply database migrations:

# su _pleroma
$ cd /home/_pleroma/pleroma
$ MIX_ENV=prod mix ecto.migrate

Note: You will need to run this step again when updating your instance to a newer version with git pull or git checkout tags/NEW_VERSION.

As _pleroma in /home/_pleroma/pleroma, you can now run MIX_ENV=prod mix phx.server to start your instance. In another SSH session or a tmux window, check that it is working properly by running ftp -MVo - http://127.0.0.1:4000/api/v1/instance, you should get json output. Double-check that the uri value near the bottom is your instance's domain name and the instance title are correct.

Configuring acme-client

acme-client is used to get SSL/TLS certificates from Let's Encrypt. Insert the following configuration in /etc/acme-client.conf and replace example.tld with your domain:

#
# $OpenBSD: acme-client.conf,v 1.5 2023/05/10 07:34:57 tb Exp $
#

authority letsencrypt {
        api url "https://acme-v02.api.letsencrypt.org/directory"
        account key "/etc/acme/letsencrypt-privkey.pem"
}

domain example.tld {
        # Adds alternative names to the certificate. Useful when serving media on another domain. Comma or space separated list.
        # alternative names {  }

        domain key "/etc/ssl/private/example.tld.key"
        domain certificate "/etc/ssl/example.tld_cert-only.crt"
        domain full chain certificate "/etc/ssl/example.tld.crt"
        sign with letsencrypt
}

Check the configuration:

# acme-client -n

Add auto-renewal by adding acme-client to /etc/weekly.local, replace example.tld with your domain:

echo "acme-client example.tld >> /etc/weekly.local

Configuring the Web server

Pleroma supports two Web servers:

• nginx (recommended for most users)
• OpenBSD's httpd and relayd (ONLY for advanced users, media proxy cache is NOT supported and will NOT work properly)

nginx

Since nginx is not installed by default, install it by running:

# pkg_add nginx

Add the following to /etc/nginx/nginx.conf, within the server {} block listening on port 80 and change server_name, as follows:

http {
    ...

    server {
        ...
        server_name example.tld; # Replace with your domain

        location ~ /.well-known/acme-challenge {
            root /var/www/acme;
        }
    }
}

Start the nginx service and acquire certificates:

# rcctl start nginx
# acme-client example.tld

OpenBSD's default nginx configuration does not contain an include directive, which is typically used for multiple sites. Therefore, you will need to first create the required directory as follows:

# mkdir /etc/nginx/sites-available
# mkdir /etc/nginx/sites-enabled

Next add the include directive to /etc/nginx/nginx.conf, within the http {} block, as follows:

http {
    ...

    server {
        ...
    }

    include /etc/nginx/sites-enabled/*;
}

As root, copy /home/_pleroma/pleroma/installation/pleroma.nginx to /etc/nginx/sites-available/pleroma.nginx.

Edit default /etc/nginx/sites-available/pleroma.nginx settings and replace example.tld with your domain:

• Change ssl_trusted_certificate to /etc/ssl/example.tld_cert-only.crt
• Change ssl_certificate to /etc/ssl/example.tld.crt
• Change ssl_certificate_key to /etc/ssl/private/example.tld.key

Symlink the Pleroma configuration to the enabled sites:

# ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled

Check nginx configuration syntax by running:

# nginx -t

If the configuration is correct, you can now enable and reload the nginx service:

# rcctl enable nginx
# rcctl reload nginx

httpd

httpd will have three functions:

• redirect requests trying to reach the instance over http to the https URL
• serve a robots.txt file
• get Let's Encrypt certificates, with acme-client

Insert the following config in httpd.conf:

# $OpenBSD: httpd.conf,v 1.17 2017/04/16 08:50:49 ajacoutot Exp $

ext_inet="<IPv4 address>"
ext_inet6="<IPv6 address>"

server "default" {
	listen on $ext_inet port 80 # Comment to disable listening on IPv4
	listen on $ext_inet6 port 80 # Comment to disable listening on IPv6
	listen on 127.0.0.1 port 80 # Do NOT comment this line

	log syslog
	directory no index

	location "/.well-known/acme-challenge/*" {
		root "/acme"
		request strip 2
	}

	location "/robots.txt" { root "/htdocs/local/" }
	location "/*" { block return 302 "https://$HTTP_HOST$REQUEST_URI" }
}

types {
}

Do not forget to change <IPv4/6 address> to your server's address(es). If httpd should only listen on one protocol family, comment one of the two first listen options.

Create the /var/www/htdocs/local/ folder and write the content of your robots.txt in /var/www/htdocs/local/robots.txt. Check the configuration with httpd -n, if it is OK enable and start httpd (as root):

# rcctl enable httpd
# rcctl start httpd

relayd

relayd will be used as the reverse proxy sitting in front of pleroma. Insert the following configuration in /etc/relayd.conf:

# $OpenBSD: relayd.conf,v 1.4 2018/03/23 09:55:06 claudio Exp $

ext_inet="<IPv4 address>"
ext_inet6="<IPv6 address>"

table <pleroma_server> { 127.0.0.1 }
table <httpd_server> { 127.0.0.1 }

http protocol plerup { # Protocol for upstream pleroma server
	#tcp { nodelay, sack, socket buffer 65536, backlog 128 } # Uncomment and adjust as you see fit
	tls ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
	tls ecdhe secp384r1

	# Forward some paths to the local server (as pleroma won't respond to them as you might want)
	pass request quick path "/robots.txt" forward to <httpd_server>

	# Append a bunch of headers
	match request header append "X-Forwarded-For" value "$REMOTE_ADDR" # This two header and the next one are not strictly required by pleroma but adding them won't hurt
	match request header append "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT"

	match response header append "X-XSS-Protection" value "1; mode=block"
	match response header append "X-Permitted-Cross-Domain-Policies" value "none"
	match response header append "X-Frame-Options" value "DENY"
	match response header append "X-Content-Type-Options" value "nosniff"
	match response header append "Referrer-Policy" value "same-origin"
	match response header append "X-Download-Options" value "noopen"
	match response header append "Content-Security-Policy" value "default-src 'none'; base-uri 'self'; form-action 'self'; img-src 'self' data: https:; media-src 'self' https:; style-src 'self' 'unsafe-inline'; font-src 'self'; script-src 'self'; connect-src 'self' wss://CHANGEME.tld; upgrade-insecure-requests;" # Modify "CHANGEME.tld" and set your instance's domain here
	match request header append "Connection" value "upgrade"
	#match response header append "Strict-Transport-Security" value "max-age=31536000; includeSubDomains" # Uncomment this only after you get HTTPS working.

	# If you do not want remote frontends to be able to access your Pleroma backend server, comment these lines
	match response header append "Access-Control-Allow-Origin" value "*"
	match response header append "Access-Control-Allow-Methods" value "POST, PUT, DELETE, GET, PATCH, OPTIONS"
	match response header append "Access-Control-Allow-Headers" value "Authorization, Content-Type, Idempotency-Key"
	match response header append "Access-Control-Expose-Headers" value "Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id"
	# Stop commenting lines here
}

relay wwwtls {
	listen on $ext_inet port https tls # Comment to disable listening on IPv4
	listen on $ext_inet6 port https tls # Comment to disable listening on IPv6

	protocol plerup

	forward to <pleroma_server> port 4000 check http "/" code 200
	forward to <httpd_server> port 80 check http "/robots.txt" code 200
}

Again, change <IPv4/6 address> to your server's address(es) and comment one of the two listen options if needed. Also change wss://CHANGEME.tld to wss://<your instance's domain name>. Check the configuration with relayd -n, if it is OK enable and start relayd (as root):

rcctl enable relayd
rcctl start relayd

(Strongly recommended) serve media on another domain

Refer to the Hardening your instance document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors.

pf

Enabling and configuring pf is highly recommended. In /etc/pf.conf, insert the following configuration:

# Macros
if="<network interface>"
authorized_ssh_clients="any"

# Skip traffic on loopback interface
set skip on lo

# Default behavior
set block-policy drop
block in log all
pass out quick

# Security features
match in all scrub (no-df random-id)
block in log from urpf-failed

# Rules
pass in quick on $if inet proto icmp to ($if) icmp-type { echoreq unreach paramprob trace } # ICMP
pass in quick on $if inet6 proto icmp6 to ($if) icmp6-type { echoreq unreach paramprob timex toobig } # ICMPv6
pass in quick on $if proto tcp to ($if) port { http https } # relayd/httpd
pass in quick on $if proto tcp from $authorized_ssh_clients to ($if) port ssh

Replace <network interface> by your server's network interface name (which you can get with ifconfig). Consider replacing the content of the authorized_ssh_clients macro by, for example, your home IP address, to avoid SSH connection attempts from bots.

Check pf's configuration by running pfctl -nf /etc/pf.conf, load it with pfctl -f /etc/pf.conf and enable pf at boot with rcctl enable pf.

Starting pleroma at boot

Copy the startup script and make sure it's executable:

# cp /home/_pleroma/pleroma/installation/openbsd/rc.d/pleroma /etc/rc.d/pleroma
# chmod +x /etc/rc.d/pleroma

Enable and start the pleroma service:

# rcctl enable pleroma
# rcctl start pleroma

Create administrative user

If your instance is up and running, you can create your first user with administrative rights with the following command as the _pleroma user:

$ MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin

Further reading

{! backend/installation/further_reading.include !}

Questions

Questions about the installation or didn’t it work as it should be, ask in #pleroma:libera.chat via Matrix or #pleroma on libera.chat via IRC.