Installing Pleroma on OpenBSD
(redirected from Pleroma.Install)
Pleroma is a microblogging server software that can federate (exchange messages with) other servers that support ActivityPub. What that means is that you can host a server for yourself or your friends and stay in control of your online identity, but still exchange messages with people on larger servers. Pleroma will federate with all servers that implement ActivityPub, like Friendica, GNU Social, Hubzilla, Mastodon, Misskey, Peertube, and Pixelfed.
This guide describes the installation and configuration of Pleroma (and the required software to run it) on a single OpenBSD 7.4 server.
Installation
First, We need to install the required dependencies
$ doas pkg_add elixir gmake git postgresql-server postgresql-contrib cmake ffmpeg ImageMagick p5-Image-ExifTool libmagic erlang-wx libvips gcc
Pick the latest version of erlang-wx when asked.
Create pleroma user to be run in dedicated user. Before creating it, Edit /etc/login.conf:
pleroma:\
:openfiles-cur=8182:\
:openfiles-max=8182:\
:openfiles=8182:\
:stacksize-cur=512M:\
:stacksize-max=512M:\
:maxproc-max=infinity:\
:maxproc-cur=8182:\
:tc=daemon:
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.
Reload the login.conf database:
# cap_mkdb /etc/login.conf
Create the _pleroma user, assign it the pleroma login class and create its home directory (/home/_pleroma/):
# useradd -m -L pleroma _pleroma
Enter a shell as the _pleroma user. As root, run
# su -l _pleroma
By default, OpenBSD did not set LANG environment variable. Edit ~/.profile, Then add this to the bottom of file:
export LC_ALL=en_US.UTF-8
Then save it.
Then clone the repository by doing:
$ git clone https://git.pleroma.social/pleroma/pleroma.git
Pleroma is now installed in /home/_pleroma/pleroma/, it will be configured and started at the end of this guide.
Setting up the database: postgresql
OpenBSD has low SEMMNS and SHMMAX by default, So increase the limit by editing the kernel state with sysctl
To increase the limit:
# sysctl kern.seminfo.semmns=2048 # sysctl kern.shminfo.shmmax=50331648
To apply this permanently, Edit /etc/sysctl.conf and put:
kern.seminfo.semmns=2048 kern.shminfo.shmmax=50331648
Now, start a shell as the _postgresql user. As root, run
# su -l _postgresql
Then run the initdb command to initialize postgresql. You will need to specify pgdata directory to the default (/var/postgresql/data) with the -D <path> and set the user to postgres with the -U <username> flag. This can be done as follows:
# initdb -D /var/postgresql/data -U postgres
If you are not using the default directory, you will have to update the datadir variable in the /etc/rc.d/postgresql script.
When this is done, enable postgresql so that it starts on boot and start it. As root, run:
$ doas rcctl enable postgresql $ doas rcctl start postgresql
To check that it started properly and didn't fail right after starting, you can run ps aux | grep postgres, there should be multiple lines of output.
Configuring httpd
httpd will have three fuctions:
- 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:
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/" }
location "/*" { block return 302 "https://$HTTP_HOST$REQUEST_URI" }
}
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.
Write the content of your robots.txt in /var/www/htdocs/robots.txt:
User-Agent: * Disallow:
Check the httpd configuration
$ doas httpd -n
If it's OK, enable and start httpd
$ doas rcctl enable httpd $ doas rcctl start httpd
acme-client
See https://wiki.ircnow.org/index.php?n=Acme-client.Configure
Configuring relayd
relayd will be used as the reverse proxy sitting in front of pleroma. Insert the following configuration in /etc/relayd.conf:
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 { keypair fedi.example.com }
# 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 set "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 set "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT"
http websockets
}
relay www {
listen on $ext_inet port https tls # Comment to disable listening on IPv4
protocol plerup
forward to <pleroma_server> port 4000
}
relay www6 {
listen on $ext_inet6 port https tls # Comment to disable listening on IPv6
protocol plerup
forward to <pleroma_server> port 4000
}
Change fedi.example.com with your instance domain.
Again, change <IPv4 address> and <IPv6 address> to your server's address(es) and comment one of the two listen options if needed.
Check the configuration with relayd -n, if it is OK enable and start relayd (as root):
$ doas rcctl enable relayd $ doas rcctl start relayd
Configuring 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.
Configuring and starting Pleroma
Enter a shell as _pleroma (as root do su -l _pleroma) and enter pleroma's installation directory:
$ cd ~/pleroma
In order for GNU make to work during deps compilation, Make a temporary folder for make command, then run the following command:
$ mkdir -p /home/_pleroma/.tmp && ln -s $(command -v gmake) /home/_pleroma/.tmp/make $ export PATH=/home/_pleroma/.tmp:$PATH $ export VIX_COMPILATION_MODE=PLATFORM_PROVIDED_LIBVIPS $ mix deps.get
When asked to install Hex dependencies, Press Y then RETURN/Enter.
Once dependencies succesfully retrieved, Run
$ MIX_PROD=prod mix pleroma.instance gen
When asked to install rebar3, Press Y then RETURN/Enter, and enter your instance information when asked.
Copy config/generated_config.exs to config/prod.secret.exs. The default values should be sufficient but you should edit it and check that everything seems OK.
$ cp config/generated_config.exs config/prod.secret.exs
Exit your current shell back to root one and run the following command to set up database:
# psql -U postgres -f /home/_pleroma/pleroma/config/setup_db.psql
Return to _pleroma shell into pleroma's installation directory (su -l _pleroma;cd ~/pleroma) and run
$ MIX_ENV=prod mix ecto.migrate
As _pleroma in /home/_pleroma/pleroma, You can now run the following command to start your instance:
$ MIX_ENV=prod mix phx.server
In another SSH session/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 uri's value is your instance's domain name.
Starting Pleroma at boot
Under _pleroma user, Edit ~/start.sh:
#!/bin/ksh export MIX_ENV=prod export LC_ALL=en_US.UTF-8 cd ~/pleroma while true; do mix phx.server done
Edit crontab by executing:
$ crontab -e
Then insert:
@reboot tmux new -d "ksh ~/start.sh"
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
Troubleshooting
Getting Internal Server Error repeatedly and got the following error in server side:
%DBConnection.ConnectionError{message: "tcp recv: closed (the connection was closed by the pool, possibly due to a timeout or because the pool has been terminated)", severity: :error, reason: :error}
Your database is likely corrupted.
To fix this, stop your Pleroma server, Do VACUUM and REINDEX to the database via psql:
~ $ psql -U postgres pleroma psql (15.3) Type "help" for help. pleroma=# VACUUM FULL; REINDEX DATABASE pleroma; VACUUM REINDEX pleroma=#
Depending on the database size, This will take some time to finish.
Once finished, You could safely exit from psql, Then start your Pleroma server.