akkoma/docs/installation/freebsd_en.md

# Installing on FreeBSD 

This document was written for FreeBSD 12.1, but should be trivially trailerable to future releases.
Additionally, this guide document can be modified to 

## Required software 

This assumes the target system has `pkg(8)`.

`# pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh`

Copy the rc.d scripts to the right directory:

Setup the required services to automatically start at boot, using `sysrc(8)`.

```
# sysrc nginx_enable=YES
# sysrc postgresql_enable=YES
```

## Initialize postgres

```
# service postgresql initdb
# service postgresql start
```

## Configuring Pleroma

Create a user for Pleroma:

```
# pw add user pleroma -m
# echo 'export LC_ALL="en_US.UTF-8"' >> /home/pleroma/.profile
# su -l pleroma
```

Clone the repository:

```
$ cd $HOME # Should be the same as /home/pleroma
$ git clone -b stable https://git.pleroma.social/pleroma/pleroma.git
```

Configure Pleroma. Note that you need a domain name at this point:

```
$ cd /home/pleroma/pleroma
$ mix deps.get # Enter "y" when asked to install Hex
$ mix pleroma.instance gen # You will be asked a few questions here.
$ cp config/generated_config.exs config/prod.secret.exs # The default values should be sufficient but you should edit it and check that everything seems OK.
```

Since Postgres is configured, we can now initialize the database. There should
now be a file in `config/setup_db.psql` that makes this easier. Edit it, and
*change the password* to a password of your choice. Make sure it is secure, since
it'll be protecting your database. As root, you can now initialize the database:

```
# cd /home/pleroma/pleroma
# sudo -Hu postgres -g postgres psql -f config/setup_db.psql
```

Postgres allows connections from all users without a password by default. To
fix this, edit `/var/db/postgres/data12/pg_hba.conf`. Change every `trust` to
`password`.

Once this is done, restart Postgres with `# service postgresql restart`.

Run the database migrations.

Back as the pleroma user, run the following to implement any database migrations.

```
# su -l pleroma
$ cd /home/pleroma/pleroma
$ MIX_ENV=prod mix ecto.migrate
```

You will need to do this whenever you update with `git pull`:

## Configuring nginx

As root, install the example configuration file
`/home/pleroma/pleroma/installation/pleroma.nginx` to
`/usr/local/etc/nginx/nginx.conf`.

Note that it will need to be wrapped in a `http {}` block. You should add
settings for the nginx daemon outside of the http block, for example:

```
user                    nginx  nginx;
error_log               /var/log/nginx/error.log;
worker_processes        4;

events {
}
```

Edit the defaults of `/usr/local/etc/nginx/nginx.conf`:

* Change `ssl_trusted_certificate` to `/etc/ssl/example.tld/chain.pem`.
* Change `ssl_certificate` to `/etc/ssl/example.tld/fullchain.pem`.
* Change `ssl_certificate_key` to `/etc/ssl/example.tld/privkey.pem`.
* Change all references of `example.tld` to your instance's domain name.

## Configuring acme.sh

We'll be using acme.sh in Stateless Mode for TLS certificate renewal.

First, as root, get your account fingerprint:

```
# sudo -Hu acme -g acme acme.sh --register-account
```

You need to add the following to your nginx configuration for the server
running on port 80:

```
  location ~ ^/\.well-known/acme-challenge/([-_a-zA-Z0-9]+)$ {
    default_type text/plain;
    return 200 "$1.6fXAG9VyG0IahirPEU2ZerUtItW2DHzDzD9wZaEKpqd";
  }
```

Replace the string after after `$1.` with your fingerprint.

Start nginx:

```
# service nginx start
```

It should now be possible to issue a cert (replace `example.com`
with your domain name):

```
$ sudo -Hu acme -g acme acme.sh --issue -d example.com --stateless
$ acme.sh --install-cert -d example.com \
	--key-file       /path/to/keyfile/in/nginx/key.pem  \
	--fullchain-file /path/to/fullchain/nginx/cert.pem \
```

Let's add auto-renewal to `/etc/daily.local`
(replace `example.com` with your domain):

```
/usr/local/bin/sudo -Hu acme -g acme \
    /usr/local/sbin/acme.sh -r \
    -d example.com \
    --cert-file /etc/nginx/tls/cert \
    --key-file /etc/nginx/tls/key \
    --ca-file /etc/nginx/tls/ca \
    --fullchain-file /etc/nginx/tls/fullchain \
    --stateless
```

## Creating a startup script for Pleroma

Pleroma will need to compile when it initially starts, which typically takes a longer
period of time. Therefore, it is good practice to initially run pleroma from the
command-line before utilizing the rc.d script. That is done as follows:

```
# su -l pleroma
$ cd $HOME/pleroma
$ MIX_ENV=prod mix phx.server
```

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

```
# cp /home/pleroma/pleroma/installation/freebsd/rc.d/pleroma /usr/local/etc/rc.d/pleroma
# chmod +x /usr/local/etc/rc.d/pleroma
```

Update the `/etc/rc.conf` and start pleroma with the following commands:

```
# sysrc pleroma_enable=YES
# service pleroma start
```

Now you can start pleroma with `# service pleroma start`.

## Conclusion

Restart nginx with `# service nginx restart` and you should be up and running.

Make sure your time is in sync, or other instances will receive your posts with
incorrect timestamps. You should have ntpd running.

## Questions

Questions about the installation or didn’t it work as it should be, ask in [#pleroma:matrix.org](https://matrix.heldscal.la/#/room/#freenode_#pleroma:matrix.org) or IRC Channel **#pleroma** on **Freenode**.