clean-up docs to avoid mismatches in BE and FE. Clearly state that stable-versions...
[akkoma] / docs / docs / installation / otp_redhat_en.md
1 # Installing on RedHat using OTP releases
2
3 ## OTP releases and Fedora/RedHat
4
5 The current OTP builds available for Linux are unfortunately incompatible with RedHat Linux distributions, like Fedora and Centos Stream. This is due to RedHat maintaining patched versions of certain Erlang libraries, making them incompatible with other Linux distributions.
6
7 However, you may compile your own OTP release from scratch. This is particularly useful if you wish to quickly distribute your OTP build onto multiple systems, without having to worry about compiling code on every system. However, if your goal is to simply set up a single instance for yourself, installing from-source might be a simpler option. To install from-source, please follow [this guide](./fedora_based_en.md).
8
9
10 ## Pre-requisites
11
12 In order to compile a RedHat-compatible OTP release, you will need to run a RedHat Linux distribution. This guide will assume you run Fedora 36, though it should also work on older Fedora releases and other RedHat distributions. It also assumes that you have administrative rights and sufficient knowledge on how to perform common CLI tasks in Linux. If you want to run this guide with root, ignore the `sudo` at the beginning of the lines.
13
14 Important: keep in mind that you must build your OTP release for the specific RedHat distribution you wish to use it on. A build on Fedora will only be compatible with a specific Fedora release version.
15
16
17 ## Building an OTP release for Fedora 36
18
19 ### Installing required packages
20
21 * First, update your system, if not already done:
22
23 ```shell
24 sudo dnf upgrade --refresh
25 ```
26
27 * Then install the required packages to build your OTP release:
28
29 ```shell
30 sudo dnf install git gcc g++ erlang elixir erlang-os_mon erlang-eldap erlang-xmerl erlang-erl_interface erlang-syntax_tools make cmake file-devel
31 ```
32
33
34 ### Preparing the project files
35
36 * Git clone the AkkomaBE repository. This can be done anywhere:
37
38 ```shell
39 cd ~
40 git clone https://akkoma.dev/AkkomaGang/akkoma.git -b stable
41 ```
42
43 * Change to the new directory:
44
45 ```shell
46 cd ./akkoma
47 ```
48
49
50 ### Building the OTP release
51
52 * Run the following commands:
53
54 ```shell
55 export MIX_ENV=prod
56 echo "import Config" > config/prod.secret.exs
57 mix local.hex --force
58 mix local.rebar --force
59 mix deps.get --only prod
60 mkdir release
61 mix release --path release
62 ```
63
64 Note that compiling the OTP release will take some time. Once it completes, you will find the OTP files in the directory `release`.
65
66 If all went well, you will have built your very own Fedora-compatible OTP release! You can now pack up the files in the `release` directory and deploy them to your other Fedora servers.
67
68
69 ## Installing the OTP release
70
71 Installing the OTP release from this point onward will be very similar to the regular OTP release. This guide assumes you will want to install your OTP package on other systems, so additional pre-requisites will be listed below.
72
73 Please note that running your own OTP release has some minor caveats that you should be aware of. They will be listed below as well.
74
75
76 ### Installing required packages
77
78 Other than things bundled in the OTP release Akkoma depends on:
79
80 * curl (to download the release build)
81 * ncurses (ERTS won't run without it)
82 * PostgreSQL (also utilizes extensions in postgresql-contrib)
83 * nginx (could be swapped with another reverse proxy but this guide covers only it)
84 * certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it)
85 * libmagic/file
86
87 First, update your system, if not already done:
88
89 ```shell
90 sudo dnf upgrade --refresh
91 ```
92
93 Then install the required packages:
94
95 ```shell
96 sudo dnf install curl ncurses postgresql postgresql-contrib nginx certbot file-devel
97 ```
98
99
100 ### Optional packages: [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md)
101
102 * Install ffmpeg (requires setting up the RPM-fusion repositories):
103
104 ```shell
105 sudo dnf -y install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
106 sudo dnf -y install https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
107 sudo dnf install ffmpeg
108 ```
109
110 * Install ImageMagick and ExifTool for image manipulation:
111
112 ```shell
113 sudo dnf install Imagemagick perl-Image-ExifTool
114 ```
115
116
117 ### Configuring PostgreSQL
118 #### (Optional) Performance configuration
119 It is encouraged to check [Optimizing your PostgreSQL performance](../configuration/postgresql.md) document, for tips on PostgreSQL tuning.
120
121 Restart PostgreSQL to apply configuration changes:
122
123 ```shell
124 sudo systemctl restart postgresql
125 ```
126
127 ### Installing Akkoma
128 ```sh
129 # Create a Akkoma user
130 adduser --system --shell /bin/false --home /opt/akkoma akkoma
131
132 # Move your custom OTP release to the home directory
133 sudo -Hu akkoma mv /your/custom/otp/release /opt/akkoma
134
135 # Create uploads directory and set proper permissions (skip if planning to use a remote uploader)
136 # Note: It does not have to be `/var/lib/akkoma/uploads`, the config generator will ask about the upload directory later
137
138 sudo mkdir -p /var/lib/akkoma/uploads
139 sudo chown -R akkoma /var/lib/akkoma
140
141 # Create custom public files directory (custom emojis, frontend bundle overrides, robots.txt, etc.)
142 # Note: It does not have to be `/var/lib/akkoma/static`, the config generator will ask about the custom public files directory later
143 sudo mkdir -p /var/lib/akkoma/static
144 sudo chown -R akkoma /var/lib/akkoma
145
146 # Create a config directory
147 sudo mkdir -p /etc/akkoma
148 sudo chown -R akkoma /etc/akkoma
149
150 # Run the config generator
151 sudo -Hu akkoma ./bin/pleroma_ctl instance gen --output /etc/akkoma/config.exs --output-psql /tmp/setup_db.psql
152
153 # Create the postgres database
154 sudo -Hu postgres psql -f /tmp/setup_db.psql
155
156 # Create the database schema
157 sudo -Hu akkoma ./bin/pleroma_ctl migrate
158
159 # Start the instance to verify that everything is working as expected
160 sudo -Hu akkoma ./bin/pleroma daemon
161
162 # Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly
163 sleep 20 && curl http://localhost:4000/api/v1/instance
164
165 # Stop the instance
166 sudo -Hu akkoma ./bin/pleroma stop
167 ```
168
169
170 ### Setting up nginx and getting Let's Encrypt SSL certificaties
171
172 #### Get a Let's Encrypt certificate
173
174 ```shell
175 certbot certonly --standalone --preferred-challenges http -d yourinstance.tld
176 ```
177
178 #### Copy Akkoma nginx configuration to the nginx folder
179
180 ```shell
181 cp /opt/akkoma/installation/nginx/akkoma.nginx /etc/nginx/conf.d/akkoma.conf
182 ```
183
184 #### Edit the nginx config
185 ```shell
186 # Replace example.tld with your (sub)domain (replace $EDITOR with your editor of choice)
187 sudo $EDITOR /etc/nginx/conf.d/akkoma.conf
188
189 # Verify that the config is valid
190 sudo nginx -t
191 ```
192 #### Start nginx
193
194 ```shell
195 sudo systemctl start nginx
196 ```
197
198 At this point if you open your (sub)domain in a browser you should see a 502 error, that's because Akkoma is not started yet.
199
200
201 ### Setting up a system service
202
203 ```shell
204 # Copy the service into a proper directory
205 cp /opt/akkoma/installation/akkoma.service /etc/systemd/system/akkoma.service
206
207 # Edit the service file and make any neccesary changes
208 sudo $EDITOR /etc/systemd/system/akkoma.service
209
210 # If you use SELinux, set the correct file context on the pleroma binary
211 sudo semanage fcontext -a -t init_t /opt/akkoma/bin/pleroma
212 sudo restorecon -v /opt/akkoma/bin/pleroma
213
214 # Start akkoma and enable it on boot
215 sudo systemctl start akkoma
216 sudo systemctl enable akkoma
217 ```
218
219 If everything worked, you should see a response from Akkoma-BE when visiting your domain. You may need to install frontends like Akkoma-FE and Admin-FE; refer to [this guide](../administration/CLI_tasks/frontend.md) on how to install them.
220
221 If that didn't happen, try reviewing the installation steps, starting Akkoma in the foreground and seeing if there are any errrors.
222
223 {! support.include !}
224
225 ## Post installation
226
227 ### Setting up auto-renew of the Let's Encrypt certificate
228
229 ```shell
230 # Create the directory for webroot challenges
231 sudo mkdir -p /var/lib/letsencrypt
232
233 # Uncomment the webroot method
234 sudo $EDITOR /etc/nginx/conf.d/akkoma.conf
235
236 # Verify that the config is valid
237 sudo nginx -t
238
239 # Restart nginx
240 sudo systemctl restart nginx
241
242 # Ensure the webroot menthod and post hook is working
243 sudo certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'systemctl reload nginx'
244
245 # Add it to the daily cron
246 echo '#!/bin/sh
247 certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
248 ' > /etc/cron.daily/renew-akkoma-cert
249 sudo chmod +x /etc/cron.daily/renew-akkoma-cert
250
251 # If everything worked the output should contain /etc/cron.daily/renew-akkoma-cert
252 sudo run-parts --test /etc/cron.daily
253 ```
254
255
256 ## Create your first user and set as admin
257 ```shell
258 cd /opt/akkoma
259 sudo -Hu akkoma ./bin/pleroma_ctl user new joeuser joeuser@sld.tld --admin
260 ```
261 This will create an account withe the username of 'joeuser' with the email address of joeuser@sld.tld, and set that user's account as an admin. This will result in a link that you can paste into the browser, which logs you in and enables you to set the password.
262
263 ## Further reading
264
265 ### Caveats of building your own OTP release
266
267 There are some things to take note of when your are running your own OTP builds.
268
269 #### Updating your OTP builds
270
271 Using your custom OTP build, you will not be able to update the installation using the `pleroma_ctl update` command. Running this command would overwrite your install with an OTP release from the main Akkoma repository, which will break your install.
272
273 Instead, you will have to rebuild your OTP release every time there are updates, then manually move it to where your Akkoma installation is running, overwriting the old OTP release files. Make sure to stop the Akkoma-BE server before overwriting any files!
274
275 After that, run the `pleroma_ctl migrate` command as usual to perform database migrations.
276
277
278 #### Cross-compatibility between RedHat distributions
279
280 As it currently stands, your OTP build will only be compatible for the specific RedHat distribution you've built it on. Fedora builds only work on Fedora, Centos builds only on Centos, RedHat builds only on RedHat. Secondly, for Fedora, they will also be bound to the specific Fedora release. This is because different releases of Fedora may have significant changes made in some of the required packages and libraries.
281
282 {! installation/frontends.include !}
283
284 {! installation/further_reading.include !}
285
286 {! support.include !}