Commit 8d70692a authored by lain's avatar lain
Browse files

Merge branch 'freebsd-docs' into 'develop'

FreeBSD installation process

See merge request !2887
parents 83cef257 e8c20c42
Pipeline #29925 passed with stages
in 17 minutes and 29 seconds
# 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
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
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
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
We'll be using 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/
# chown acme:acme /var/log/
# chmod 600 /var/log/
Next, obtain your account fingerprint:
# sudo -Hu acme -g acme --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 ``
with your domain name):
# sudo -Hu acme -g acme --issue -d --stateless
Let's add auto-renewal to `/etc/crontab`
(replace `` with your domain):
/usr/local/bin/sudo -Hu acme -g acme /usr/local/sbin/ -r -d --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
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:
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 []( or IRC Channel **#pleroma** on **Freenode**.
# REQUIRE: DAEMON postgresql
# PROVIDE: pleroma
# sudo -u pleroma MIX_ENV=prod elixir --erl \"-detached\" -S mix phx.server
. /etc/rc.subr
desc="Pleroma Social Media Platform"
command_args="--erl \"-detached\" -S /usr/local/bin/mix phx.server"
pleroma_env="HOME=${pleroma_home} MIX_ENV=prod"
pid=$(pgrep beam.smp$)
echo -n "${pid}"
load_rc_config ${name}
run_rc_command "$1"
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment