total rebase
[anni] / docs / installation / freebsd_en.md
1 # Installing on FreeBSD
2
3 This document was written for FreeBSD 12.1, but should be work on future releases.
4
5 {! backend/installation/generic_dependencies.include !}
6
7 ## Installing software used in this guide
8
9 This assumes the target system has `pkg(8)`.
10
11 ```
12 # pkg install elixir postgresql12-server postgresql12-client postgresql12-contrib git-lite sudo nginx gmake acme.sh cmake vips
13 ```
14
15 Copy the rc.d scripts to the right directory:
16
17 Setup the required services to automatically start at boot, using `sysrc(8)`.
18
19 ```
20 # sysrc nginx_enable=YES
21 # sysrc postgresql_enable=YES
22 ```
23
24 ## Initialize postgres
25
26 ```
27 # service postgresql initdb
28 # service postgresql start
29 ```
30
31 ### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md))
32
33 ```shell
34 # pkg install imagemagick ffmpeg p5-Image-ExifTool
35 ```
36
37 ## Configuring Pleroma
38
39 Create a user for Pleroma:
40
41 ```
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
45 # su -l pleroma
46 ```
47
48 Clone the repository:
49
50 ```
51 $ cd $HOME # Should be the same as /home/pleroma
52 $ git clone -b stable https://git.pleroma.social/pleroma/pleroma.git
53 ```
54
55 Configure Pleroma. Note that you need a domain name at this point:
56
57 ```
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
62 ```
63
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:
68
69 ```
70 # cd /home/pleroma/pleroma
71 # sudo -Hu postgres -g postgres psql -f config/setup_db.psql
72 ```
73
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
76 `password`.
77
78 Once this is done, restart Postgres with:
79 ```
80 # service postgresql restart
81 ```
82
83 Run the database migrations.
84
85 Back as the pleroma user, run the following to implement any database migrations.
86
87 ```
88 # su -l pleroma
89 $ cd /home/pleroma/pleroma
90 $ MIX_ENV=prod mix ecto.migrate
91 ```
92
93 You will need to do this whenever you update with `git pull`:
94
95 ## Configuring acme.sh
96
97 We'll be using acme.sh in Stateless Mode for TLS certificate renewal.
98
99 First, as root, allow the user `acme` to have access to the acme log file, as follows:
100
101 ```
102 # touch /var/log/acme.sh.log
103 # chown acme:acme /var/log/acme.sh.log
104 # chmod 600 /var/log/acme.sh.log
105 ```
106
107 Next, obtain your account fingerprint:
108
109 ```
110 # sudo -Hu acme -g acme acme.sh --register-account
111 ```
112
113 You need to add the following to your nginx configuration for the server
114 running on port 80:
115
116 ```
117   location ~ ^/\.well-known/acme-challenge/([-_a-zA-Z0-9]+)$ {
118     default_type text/plain;
119     return 200 "$1.6fXAG9VyG0IahirPEU2ZerUtItW2DHzDzD9wZaEKpqd";
120   }
121 ```
122
123 Replace the string after after `$1.` with your fingerprint.
124
125 Start nginx:
126
127 ```
128 # service nginx start
129 ```
130
131 It should now be possible to issue a cert (replace `example.com`
132 with your domain name):
133
134 ```
135 # sudo -Hu acme -g acme acme.sh --issue -d example.com --stateless
136 ```
137
138 Let's add auto-renewal to `/etc/crontab`
139 (replace `example.com` with your domain):
140
141 ```
142 /usr/local/bin/sudo -Hu acme -g acme /usr/local/sbin/acme.sh -r -d example.com --stateless
143 ```
144
145 ### Configuring nginx
146
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:
150
151
152 ```
153 # mkdir -p /usr/local/etc/nginx/sites-available
154 ```
155
156 Next, add an `include` directive to `/usr/local/etc/nginx/nginx.conf`, within the `http {}`
157 block, as follows:
158
159
160 ```
161 http {
162 ...
163         include /usr/local/etc/nginx/sites-available/*;
164 }
165 ```
166
167 As root, copy `/home/pleroma/pleroma/installation/pleroma.nginx` to
168 `/usr/local/etc/nginx/sites-available/pleroma.nginx`.
169
170 Edit the defaults of `/usr/local/etc/nginx/sites-available/pleroma.nginx`:
171
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.
176
177 #### (Strongly recommended) serve media on another domain
178
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.
180
181 ## Creating a startup script for Pleroma
182
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:
186
187 ```
188 # su -l pleroma
189 $ cd $HOME/pleroma
190 $ MIX_ENV=prod mix phx.server
191 ```
192
193 Copy the startup script to the correct location and make sure it's executable:
194
195 ```
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
198 ```
199
200 Update the `/etc/rc.conf` and start pleroma with the following commands:
201
202 ```
203 # sysrc pleroma_enable=YES
204 # service pleroma start
205 ```
206
207 #### Create your first user
208
209 If your instance is up and running, you can create your first user with administrative rights with the following task:
210
211 ```shell
212 sudo -Hu pleroma MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin
213 ```
214 ## Conclusion
215
216 Restart nginx with `# service nginx restart` and you should be up and running.
217
218 Make sure your time is in sync, or other instances will receive your posts with
219 incorrect timestamps. You should have ntpd running.
220
221 ## Questions
222
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.