Installing on OpenBSD

This guide describes the installation and configuration of akkoma (and the required software to run it) on a single OpenBSD 7.2 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.

Required dependencies

• PostgreSQL 12+
• Elixir 1.14+ (currently tested up to 1.16)
• Erlang OTP 25+ (currently tested up to OTP26)
• git
• file / libmagic
• gcc (clang might also work)
• GNU make
• CMake

Optional dependencies

• ImageMagick
• FFmpeg
• exiftool

Preparing the system

Required software

To install them, run the following command (with doas or as root):

pkg_add elixir gmake git postgresql-server postgresql-contrib cmake ffmpeg erlang-wx libmagic
pkg_add erlang-wx # Choose the latest version as package version when promted

Akkoma 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

Per docs/installation/optional/media_graphics_packages.md: * ImageMagick * ffmpeg * exiftool

To install the above:

pkg_add ffmpeg p5-Image-ExifTool

Creating the akkoma user

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

akkoma:\
    :datasize-max=1536M:\
    :datasize-cur=1536M:\
    :openfiles-max=4096

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

Create the _akkoma user, assign it the akkoma login class and create its home directory (/home/_akkoma/): useradd -m -L akkoma _akkoma

Clone akkoma's directory

Enter a shell as the _akkoma user. As root, run su _akkoma -;cd. Then clone the repository with git clone https://akkoma.dev/AkkomaGang/akkoma.git. Akkoma is now installed in /home/_akkoma/akkoma/, it will be configured and started at the end of this guide.

PostgreSQL

Create _postgresql's user directory (it hasn't been created yet): mdir var/postgresql/data. To set it as home directory for user _postgresql run usermod -d /var/postgresql/data _postgresql.

Start a shell as the _postgresql user (as root run su _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:

rcctl enable postgresql
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.

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 /etc/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" }
}

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

acme-client

acme-client is used to get SSL/TLS certificates from Let's Encrypt. Insert the following configuration in /etc/acme-client.conf:

#
# $OpenBSD: acme-client.conf,v 1.4 2017/03/22 11:14:14 benno Exp $
#

authority letsencrypt-<domain name> {
    #agreement url "https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf"
    api url "https://acme-v02.api.letsencrypt.org/directory"
    account key "/etc/acme/letsencrypt-privkey-<domain name>.pem"
}

domain <domain name> {
    domain key "/etc/ssl/private/<domain name>.key"
    domain certificate "/etc/ssl/<domain name>.crt"
    domain full chain certificate "/etc/ssl/<domain name>.fullchain.pem"
    sign with letsencrypt-<domain name>
    challengedir "/var/www/acme/"
}

Replace <domain name> by the domain name you'll use for your instance. As root, run acme-client -n to check the config, then acme-client -ADv <domain name> to create account and domain keys, and request a certificate for the first time. Make acme-client run everyday by adding it in /etc/daily.local. As root, run the following command: echo "acme-client <domain name>" >> /etc/daily.local.

Relayd will look for certificates and keys based on the address it listens on (see next part), the easiest way to make them available to relayd is to create a link, as root run:

ln -s /etc/ssl/<domain name>.fullchain.pem /etc/ssl/<IP address>.crt
ln -s /etc/ssl/private/<domain name>.key /etc/ssl/private/<IP address>.key

This will have to be done for each IPv4 and IPv6 address relayd listens on.

relayd

relayd will be used as the reverse proxy sitting in front of akkoma. 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 <akkoma_server> { 127.0.0.1 }
table <httpd_server> { 127.0.0.1 }

http protocol plerup { # Protocol for upstream akkoma 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 akkoma 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 akkoma 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 "0"
    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 "Content-Security-Policy" value "default-src 'none'; base-uri 'none'; 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=63072000; includeSubDomains; preload" # Uncomment this only after you get HTTPS working.

    # If you do not want remote frontends to be able to access your Akkoma 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 <akkoma_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

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.

Configure and start akkoma

Enter a shell as _akkoma (as root su _akkoma -) and enter akkoma's installation directory (cd ~/akkoma/).

Then follow the main installation guide:

• run mix deps.get
• run MIX_ENV=prod mix pleroma.instance gen and enter your instance's 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.
• exit your current shell back to a root one and run psql -U postgres -f /home/_akkoma/akkoma/config/setup_db.psql to setup the database.
• return to a _akkoma shell into akkoma's installation directory (su _akkoma -;cd ~/akkoma) and run MIX_ENV=prod mix ecto.migrate

As _akkoma in /home/_akkoma/akkoma, you can now run LC_ALL=en_US.UTF-8 MIX_ENV=prod mix phx.server to start your instance. 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 akkoma at boot

An rc script to automatically start akkoma at boot hasn't been written yet, it can be run in a tmux session (tmux is in base).

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 _akkoma user.

LC_ALL=en_US.UTF-8 MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin

Installing Frontends

Once your backend server is functional, you'll also want to probably install frontends.

These are no longer bundled with the distribution and need an extra command to install.

You must run frontend management tasks as the akkoma user, the same way you downloaded the build or cloned the git repo before. But otherwise, for most installations, the following will suffice:

OTPFrom SourceDocker

./bin/pleroma_ctl frontend install pleroma-fe --ref stable
# and also, if desired
./bin/pleroma_ctl frontend install admin-fe --ref stable

mix pleroma.frontend install pleroma-fe --ref stable
mix pleroma.frontend install admin-fe --ref stable

./docker-resources/manage.sh mix pleroma.frontend install pleroma-fe --ref stable
./docker-resources/manage.sh mix pleroma.frontend install admin-fe --ref stable

For more customised installations, refer to Frontend Management

Further reading

• How Federation Works/Why is my Federated Timeline empty?
• Backup your instance
• Updating your instance
• Hardening your instance
• How to activate mediaproxy

Support

If you encounter any issues or have questions regarding the install process, feel free to ask at meta.akkoma.dev.

Or message via IRC on #akkoma at irc.akkoma.dev (port 6697, SSL)