Merge branch 'freebsd-docs' into 'develop'

FreeBSD installation process

See merge request pleroma/pleroma!2887

docs/installation/freebsd_en.md

@@ -0,0 +1,210 @@
+# Installing on FreeBSD 
+
+This document was written for FreeBSD 12.1, but should be work on future releases.
+
+## 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
+```
+
+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 acme.sh
+
+We'll be using acme.sh in Stateless Mode for TLS certificate renewal.
+
+First, as root, allow the user `acme` to have access to the acme log file, as follows:
+
+```
+# touch /var/log/acme.sh.log
+# chown acme:acme /var/log/acme.sh.log
+# chmod 600 /var/log/acme.sh.log
+```
+
+Next, obtain 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
+```
+
+Let's add auto-renewal to `/etc/crontab`
+(replace `example.com` with your domain):
+
+```
+/usr/local/bin/sudo -Hu acme -g acme /usr/local/sbin/acme.sh -r -d example.com --stateless
+```
+
+### Configuring nginx
+
+FreeBSD'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 -p /usr/local/etc/nginx/sites-available
+```
+
+Next, add an `include` directive to `/usr/local/etc/nginx/nginx.conf`, within the `http {}`
+block, as follows:
+
+
+```
+http {
+...
+	include /usr/local/etc/nginx/sites-available/*;
+}
+```
+
+As root, copy `/home/pleroma/pleroma/installation/pleroma.nginx` to
+`/usr/local/etc/nginx/sites-available/pleroma.nginx`.
+
+Edit the defaults of `/usr/local/etc/nginx/sites-available/pleroma.nginx`:
+
+* Change `ssl_trusted_certificate` to `/var/db/acme/certs/example.tld/example.tld.cer`.
+* Change `ssl_certificate` to `/var/db/acme/certs/example.tld/fullchain.cer`.
+* Change `ssl_certificate_key` to `/var/db/acme/certs/example.tld/example.tld.key`.
+* Change all references of `example.tld` to your instance's domain name.
+
+## 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
+```
+
+#### Create your first user
+
+If your instance is up and running, you can create your first user with administrative rights with the following task:
+
+```shell
+sudo -Hu pleroma MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin
+```
+## 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**.

installation/freebsd/rc.d/pleroma

@@ -0,0 +1,28 @@
+#!/bin/sh
+# REQUIRE: DAEMON postgresql
+# PROVIDE: pleroma
+
+# sudo -u pleroma MIX_ENV=prod elixir --erl \"-detached\" -S mix phx.server
+
+. /etc/rc.subr
+
+name="pleroma"
+desc="Pleroma Social Media Platform"
+rcvar=${name}_enable
+command="/usr/local/bin/elixir"
+command_args="--erl \"-detached\" -S /usr/local/bin/mix phx.server"
+pidfile="/dev/null"
+
+pleroma_user="pleroma"
+pleroma_home="/home/pleroma"
+pleroma_chdir="${pleroma_home}/pleroma"
+pleroma_env="HOME=${pleroma_home} MIX_ENV=prod"
+
+check_pidfile()
+{
+	pid=$(pgrep beam.smp$)
+	echo -n "${pid}"
+}
+
+load_rc_config ${name}
+run_rc_command "$1"