# Akkoma

Akkoma is a fork of Pleroma project with additional features added.

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


## Installation

First, We need to install the required dependencies

    # pkg_add elixir gmake git postgresql-server postgresql-contrib cmake ffmpeg ImageMagick p5-Image-ExifTool libmagic erlang-wx


Pick the latest version of `erlang-wx` when asked.

Create `akkoma` user to be run in dedicated user. Before creating it, Edit `/etc/login.conf`:

    akkoma:\
        :openfiles-cur=8182:\
        :openfiles-max=8182:\
        :openfiles=8182:\
        :stacksize-cur=128M:\
        :stacksize-max=128M:\
        :maxproc-max=infinity:\
        :maxproc-cur=8182:\
        :tc=daemon:


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


Enter a shell as the _akkoma user. As root, run

    # su -l _akkoma


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://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.


## 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:

    # 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.


## Configuring httpd

httpd will have three fuctions:

1. Redirect requests trying to reach the instance over http to the https URL
2. Serve a robots.txt file
3. 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/" }
        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

    # httpd -n


If it's OK, enable and start httpd

    # rcctl enable httpd
    # rcctl start httpd


## acme-client

See [Acme-client Configure](/acme-client/configure)


## Configuring 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 { keypair fedi.example.com }
        # 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"
        http websockets
    }
    relay www {
        listen on $ext_inet port https tls # Comment to disable listening on IPv4
        protocol plerup
        forward to <akkoma_server> port 4000
    }
    relay www6 {
        listen on $ext_inet6 port https tls # Comment to disable listening on IPv6
        protocol plerup
        forward to <akkoma_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):

    # rcctl enable relayd
    # 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 akkoma

Enter a shell as _akkoma (as root do `su -l _akkoma`) and enter akkoma's installation directory:

    $ cd ~/akkoma




Now, Run the following command:

    $ 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/_akkoma/akkoma/config/setup_db.psql


Return to _akkoma shell into akkoma's installation directory (`su -l _akkoma;cd ~/akkoma`) and run

    $ MIX_ENV=prod mix ecto.migrate




As `_akkoma` in `/home/_akkoma/akkoma`, 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 akkoma at boot

Under `_akkoma` user, Edit `~/start.sh`:

    #!/bin/ksh
    export MIX_ENV=prod
    export LC_ALL=en_US.UTF-8
    cd ~/akkoma
    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 `_akkoma` user.

    $ 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.

For most installations, the following will suffice:

    $ export MIX_ENV=prod
    $ mix pleroma.frontend install pleroma-fe --ref stable
    $ mix pleroma.frontend install admin-fe --ref stable