1 # Installing on FreeBSD
3 This document was written for FreeBSD 12.1, but should be work on future releases.
5 {! backend/installation/generic_dependencies.include !}
7 ## Installing software used in this guide
9 This assumes the target system has `pkg(8)`.
12 # pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh cmake vips
15 Copy the rc.d scripts to the right directory:
17 Setup the required services to automatically start at boot, using `sysrc(8)`.
20 # sysrc nginx_enable=YES
21 # sysrc postgresql_enable=YES
24 ## Initialize postgres
27 # service postgresql initdb
28 # service postgresql start
31 ### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md))
34 # pkg install imagemagick ffmpeg p5-Image-ExifTool
37 ## Configuring Pleroma
39 Create a user for Pleroma:
42 # pw add user pleroma -m
43 # echo 'export LC_ALL="en_US.UTF-8"' >> /home/pleroma/.profile
44 # echo 'export VIX_COMPILATION_MODE=PLATFORM_PROVIDED_LIBVIPS' >> /home/pleroma/.profile
51 $ cd $HOME # Should be the same as /home/pleroma
52 $ git clone -b stable https://git.pleroma.social/pleroma/pleroma.git
55 Configure Pleroma. Note that you need a domain name at this point:
58 $ cd /home/pleroma/pleroma
59 $ mix deps.get # Enter "y" when asked to install Hex
60 $ MIX_ENV=prod mix pleroma.instance gen # You will be asked a few questions here.
61 $ cp config/generated_config.exs config/prod.secret.exs
64 Since Postgres is configured, we can now initialize the database. There should
65 now be a file in `config/setup_db.psql` that makes this easier. Edit it, and
66 *change the password* to a password of your choice. Make sure it is secure, since
67 it'll be protecting your database. As root, you can now initialize the database:
70 # cd /home/pleroma/pleroma
71 # sudo -Hu postgres -g postgres psql -f config/setup_db.psql
74 Postgres allows connections from all users without a password by default. To
75 fix this, edit `/var/db/postgres/data12/pg_hba.conf`. Change every `trust` to
78 Once this is done, restart Postgres with:
80 # service postgresql restart
83 Run the database migrations.
85 Back as the pleroma user, run the following to implement any database migrations.
89 $ cd /home/pleroma/pleroma
90 $ MIX_ENV=prod mix ecto.migrate
93 You will need to do this whenever you update with `git pull`:
95 ## Configuring acme.sh
97 We'll be using acme.sh in Stateless Mode for TLS certificate renewal.
99 First, as root, allow the user `acme` to have access to the acme log file, as follows:
102 # touch /var/log/acme.sh.log
103 # chown acme:acme /var/log/acme.sh.log
104 # chmod 600 /var/log/acme.sh.log
107 Next, obtain your account fingerprint:
110 # sudo -Hu acme -g acme acme.sh --register-account
113 You need to add the following to your nginx configuration for the server
117 location ~ ^/\.well-known/acme-challenge/([-_a-zA-Z0-9]+)$ {
118 default_type text/plain;
119 return 200 "$1.6fXAG9VyG0IahirPEU2ZerUtItW2DHzDzD9wZaEKpqd";
123 Replace the string after after `$1.` with your fingerprint.
128 # service nginx start
131 It should now be possible to issue a cert (replace `example.com`
132 with your domain name):
135 # sudo -Hu acme -g acme acme.sh --issue -d example.com --stateless
138 Let's add auto-renewal to `/etc/crontab`
139 (replace `example.com` with your domain):
142 /usr/local/bin/sudo -Hu acme -g acme /usr/local/sbin/acme.sh -r -d example.com --stateless
145 ### Configuring nginx
147 FreeBSD's default nginx configuration does not contain an include directive, which is
148 typically used for multiple sites. Therefore, you will need to first create the required
149 directory as follows:
153 # mkdir -p /usr/local/etc/nginx/sites-available
156 Next, add an `include` directive to `/usr/local/etc/nginx/nginx.conf`, within the `http {}`
163 include /usr/local/etc/nginx/sites-available/*;
167 As root, copy `/home/pleroma/pleroma/installation/pleroma.nginx` to
168 `/usr/local/etc/nginx/sites-available/pleroma.nginx`.
170 Edit the defaults of `/usr/local/etc/nginx/sites-available/pleroma.nginx`:
172 * Change `ssl_trusted_certificate` to `/var/db/acme/certs/example.tld/example.tld.cer`.
173 * Change `ssl_certificate` to `/var/db/acme/certs/example.tld/fullchain.cer`.
174 * Change `ssl_certificate_key` to `/var/db/acme/certs/example.tld/example.tld.key`.
175 * Change all references of `example.tld` to your instance's domain name.
177 #### (Strongly recommended) serve media on another domain
179 Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors.
181 ## Creating a startup script for Pleroma
183 Pleroma will need to compile when it initially starts, which typically takes a longer
184 period of time. Therefore, it is good practice to initially run pleroma from the
185 command-line before utilizing the rc.d script. That is done as follows:
190 $ MIX_ENV=prod mix phx.server
193 Copy the startup script to the correct location and make sure it's executable:
196 # cp /home/pleroma/pleroma/installation/freebsd/rc.d/pleroma /usr/local/etc/rc.d/pleroma
197 # chmod +x /usr/local/etc/rc.d/pleroma
200 Update the `/etc/rc.conf` and start pleroma with the following commands:
203 # sysrc pleroma_enable=YES
204 # service pleroma start
207 #### Create your first user
209 If your instance is up and running, you can create your first user with administrative rights with the following task:
212 sudo -Hu pleroma MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin
216 Restart nginx with `# service nginx restart` and you should be up and running.
218 Make sure your time is in sync, or other instances will receive your posts with
219 incorrect timestamps. You should have ntpd running.
223 Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC.