commit: 8d70692abf64244e44ade5ef2055d1a586788dd1 parent: 83cef257942c42ae602308f5ce1a9d3d004791fc Author: lain <lain@soykaf.club> Date: Tue, 18 Aug 2020 12:56:28 +0000 Merge branch 'freebsd-docs' into 'develop' FreeBSD installation process See merge request pleroma/pleroma!2887Diffstat:
| A | docs/installation/freebsd_en.md | 210 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | installation/freebsd/rc.d/pleroma | 28 | ++++++++++++++++++++++++++++ |
2 files changed, 238 insertions(+), 0 deletions(-)
diff --git a/docs/installation/freebsd_en.md b/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**. diff --git a/installation/freebsd/rc.d/pleroma b/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"