Start adding telemetry
[akkoma] / docs / docs / installation / gentoo_en.md
1 # Installing on Gentoo GNU/Linux
2
3 {! installation/otp_vs_from_source_source.include !}
4
5 ## Installation
6
7 This guide will assume that you have administrative rights, either as root or a user with [sudo permissions](https://wiki.gentoo.org/wiki/Sudo). Lines that begin with `#` indicate that they should be run as the superuser. Lines using `$` should be run as the indicated user, e.g. `akkoma$` should be run as the `akkoma` user.
8
9 {! installation/generic_dependencies.include !}
10
11 ### Your make.conf, package.use, and USE flags
12
13 The only specific USE flag you should need is the `uuid` flag for `dev-db/postgresql`. Add the following line to any new file in `/etc/portage/package.use`. If you would like a suggested name for the file, either `postgresql` or `akkoma` would do fine, depending on how you like to arrange your package.use flags.
14
15 ```text
16 dev-db/postgresql uuid
17 ```
18
19 You could opt to add `USE="uuid"` to `/etc/portage/make.conf` if you'd rather set this as a global USE flags, but this flags does unrelated things in other packages, so keep that in mind if you elect to do so.
20
21 If you are planning to use `nginx`, as this guide suggests, you should also add the following flag to the same file.
22
23 ```text
24 www-servers/nginx NGINX_MODULES_HTTP: slice
25 ```
26
27 Double check your compiler flags in `/etc/portage/make.conf`. If you require any special compilation flags or would like to set up remote builds, now is the time to do so. Be sure that your CFLAGS and MAKEOPTS make sense for the platform you are using. It is not recommended to use above `-O2` or risky optimization flags for a production server.
28
29 ### Installing a cron daemon
30
31 Gentoo quite pointedly does not come with a cron daemon installed, and as such it is recommended you install one to automate certbot renewals and to allow other system administration tasks to be run automatically. Gentoo has [a whole wide world of cron options](https://wiki.gentoo.org/wiki/Cron) but if you just want A Cron That Works, `emerge --ask virtual/cron` will install the default cron implementation (probably cronie) which will work just fine. For the purpouses of this guide, we will be doing just that.
32
33 ### Required ebuilds
34
35 * `dev-db/postgresql`
36 * `dev-lang/elixir`
37 * `dev-vcs/git`
38 * `dev-util/cmake`
39 * `sys-apps/file`
40
41 #### Optional ebuilds used in this guide
42
43 * `www-servers/nginx` (preferred, example configs for other reverse proxies can be found in the repo)
44 * `app-crypt/certbot` (or any other ACME client for Let’s Encrypt certificates)
45 * `app-crypt/certbot-nginx` (nginx certbot plugin that allows use of the all-powerful `--nginx` flag on certbot)
46 * `media-gfx/imagemagick`
47 * `media-video/ffmpeg`
48 * `media-libs/exiftool`
49
50 ### Prepare the system
51
52 * First ensure that you have the latest copy of the portage ebuilds if you have not synced them yet:
53
54 ```shell
55 # emaint sync -a
56 ```
57
58 * Emerge all required the required and suggested software in one go:
59
60 ```shell
61 # emerge --ask dev-db/postgresql dev-lang/elixir dev-vcs/git www-servers/nginx app-crypt/certbot app-crypt/certbot-nginx dev-util/cmake sys-apps/file
62 ```
63
64 If you would not like to install the optional packages, remove them from this line.
65
66 If you're running this from a low-powered virtual machine, it should work though it will take some time. There were no issues on a VPS with a single core and 1GB of RAM; if you are using an even more limited device and run into issues, you can try creating a swapfile or use a more powerful machine running Gentoo to [cross build](https://wiki.gentoo.org/wiki/Cross_build_environment). If you have a wait ahead of you, now would be a good time to take a break, strech a bit, refresh your beverage of choice and/or get a snack, and reply to Arch users' posts with "I use Gentoo btw" as we do.
67
68 ### Install PostgreSQL
69
70 [Gentoo Wiki article](https://wiki.gentoo.org/wiki/PostgreSQL) as well as [PostgreSQL QuickStart](https://wiki.gentoo.org/wiki/PostgreSQL/QuickStart) might be worth a quick glance, as the way Gentoo handles postgres is slightly unusual, with built in capability to have two different databases running for testing and live or whatever other purpouse. While it is still straightforward to install, it does mean that the version numbers used in this guide might change for future updates, so keep an eye out for the output you get from `emerge` to ensure you are using the correct ones.
71
72 * Install postgresql if you have not done so already:
73
74 ```shell
75 # emerge --ask dev-db/postgresql
76 ```
77
78 Ensure that `/etc/conf.d/postgresql-11` has the encoding you want (it defaults to UTF8 which is probably what you want) and make any adjustments to the data directory if you find it necessary. Be sure to adjust the number at the end depending on what version of postgres you actually installed.
79
80 * Initialize the database cluster
81
82 The output from emerging postgresql should give you a command for initializing the postgres database. The default slot should be indicated in this command, ensure that it matches the command below.
83
84 ```shell
85 # emerge --config dev-db/postgresql:11
86 ```
87
88 * Start postgres and enable the system service
89
90 ```shell
91 # /etc/init.d/postgresql-11 start
92 # rc-update add postgresql-11 default
93 ```
94
95 ### A note on licenses, the AGPL, and deployment procedures
96
97 If you do not plan to make any modifications to your Akkoma instance, cloning directly from the main repo will get you what you need. However, if you plan on doing any contributions to upstream development, making changes or modifications to your instance, making custom themes, or want to play around--and let's be honest here, if you're using Gentoo that is most likely you--you will save yourself a lot of headache later if you take the time right now to fork the Akkoma repo and use that in the following section.
98
99 Not only does this make it much easier to deploy changes you make, as you can commit and pull from upstream and all that good stuff from the comfort of your local machine then simply `git pull` on your instance server when you're ready to deploy, it also ensures you are compliant with the Affero General Public Licence that Akkoma is licenced under, which stipulates that all network services provided with modified AGPL code must publish their changes on a publicly available internet service and for free. It also makes it much easier to ask for help from and provide help to your fellow Akkoma admins if your public repo always reflects what you are running because it is part of your deployment procedure.
100
101 ### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md))
102
103 ```shell
104 # emerge --ask media-video/ffmpeg media-gfx/imagemagick media-libs/exiftool
105 ```
106
107 ### Install AkkomaBE
108
109 * Add a new system user for the Akkoma service and set up default directories:
110
111 Remove `,wheel` if you do not want this user to be able to use `sudo`, however note that being able to `sudo` as the `akkoma` user will make finishing the insallation and common maintenence tasks somewhat easier:
112
113 ```shell
114 # useradd -m -G users,wheel -s /bin/bash akkoma
115 ```
116
117 Optional: If you are using sudo, review your sudo setup to ensure it works for you. The `/etc/sudoers` file has a lot of options and examples to help you, and [the Gentoo sudo guide](https://wiki.gentoo.org/wiki/Sudo) has more information. Finishing this installation will be somewhat easier if you have a way to sudo from the `akkoma` user, but it might be best to not allow that user to sudo during normal operation, and as such there will be a reminder at the end of this guide to double check if you would like to lock down the `akkoma` user after initial setup.
118
119 **Note**: To execute a single command as the Akkoma system user, use `sudo -Hu akkoma command`. You can also switch to a shell by using `sudo -Hu akkoma $SHELL`. If you don't have or want `sudo` or would like to use the system as the `akkoma` user for instance maintenance tasks, you can simply use `su - akkoma` to switch to the `akkoma` user.
120
121 * Git clone the AkkomaBE repository and make the Akkoma user the owner of the directory:
122
123 It is highly recommended you use your own fork for the `https://path/to/repo` part below, however if you foolishly decide to forego using your own fork, the primary repo `https://akkoma.dev/AkkomaGang/akkoma.git` will work here.
124
125 ```shell
126 akkoma$ cd ~
127 akkoma$ git clone -b stable https://path/to/repo
128 ```
129
130 * Change to the new directory:
131
132 ```shell
133 akkoma$ cd ~/akkoma
134 ```
135
136 * Install the dependencies for Akkoma and answer with `yes` if it asks you to install `Hex`:
137
138 ```shell
139 akkoma$ mix deps.get
140 ```
141
142 * Generate the configuration:
143
144 ```shell
145 akkoma$ MIX_ENV=prod mix pleroma.instance gen
146 ```
147
148 * Answer with `yes` if it asks you to install `rebar3`.
149
150 * This part precompiles some parts of Akkoma, so it might take a few moments
151
152 * After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`.
153
154 * Spend some time with `generated_config.exs` to ensure that everything is in order. If you plan on using an S3-compatible service to store your local media, that can be done here. You will likely mostly be using `prod.secret.exs` for a production instance, however if you would like to set up a development environment, make a copy to `dev.secret.exs` and adjust settings as needed as well.
155
156 ```shell
157 akkoma$ mv config/generated_config.exs config/prod.secret.exs
158 ```
159
160 * The previous command creates also the file `config/setup_db.psql`, with which you can create the database. Ensure that it is using the correct database name on the `CREATE DATABASE` and the `\c` lines, then run the postgres script:
161
162 ```shell
163 akkoma$ sudo -Hu postgres psql -f config/setup_db.psql
164 ```
165
166 * Now run the database migration:
167
168 ```shell
169 akkoma$ MIX_ENV=prod mix ecto.migrate
170 ```
171
172 * Now you can start Akkoma already
173
174 ```shell
175 akkoma$ MIX_ENV=prod mix phx.server
176 ```
177
178 It probably won't work over the public internet quite yet, however, as we still need to set up a web servere to proxy to the akkoma application, as well as configure SSL.
179
180 ### Finalize installation
181
182 Assuming you want to open your newly installed federated social network to, well, the federation, you should run nginx or some other webserver/proxy in front of Akkoma. It is also a good idea to set up Akkoma to run as a system service.
183
184 #### Nginx
185
186 * Install nginx, if not already done:
187
188 ```shell
189 # emerge --ask www-servers/nginx
190 ```
191
192 * Create directories for available and enabled sites:
193
194 ```shell
195 # mkdir -p /etc/nginx/sites-{available,enabled}
196 ```
197
198 * Append the following line at the end of the `http` block in `/etc/nginx/nginx.conf`:
199
200 ```Nginx
201 include sites-enabled/*;
202 ```
203
204 * Setup your SSL cert, using your method of choice or certbot. If using certbot, install it if you haven't already:
205
206 ```shell
207 # emerge --ask app-crypt/certbot app-crypt/certbot-nginx
208 ```
209
210 and then set it up:
211
212 ```shell
213 # mkdir -p /var/lib/letsencrypt/
214 # certbot certonly --email <your@emailaddress> -d <yourdomain> --standalone
215 ```
216
217 If that doesn't work the first time, add `--dry-run` to further attempts to avoid being ratelimited as you identify the issue, and do not remove it until the dry run succeeds. If that doesn’t work, make sure, that nginx is not already running. If it still doesn’t work, try setting up nginx first (change ssl “on” to “off” and try again). Often the answer to issues with certbot is to use the `--nginx` flag once you have nginx up and running.
218
219 If you are using any additional subdomains, such as for a media proxy, you can re-run the same command with the subdomain in question. When it comes time to renew later, you will not need to run multiple times for each domain, one renew will handle it.
220
221 ---
222
223 * Copy the example nginx configuration and activate it:
224
225 ```shell
226 # cp /home/akkoma/akkoma/installation/nginx/akkoma.nginx /etc/nginx/sites-available/
227 # ln -s /etc/nginx/sites-available/akkoma.nginx /etc/nginx/sites-enabled/akkoma.nginx
228 ```
229
230 * Take some time to ensure that your nginx config is correct
231
232 Replace all instances of `example.tld` with your instance's public URL. If for whatever reason you made changes to the port that your akkoma app runs on, be sure that is reflected in your configuration.
233
234 Pay special attention to the line that begins with `ssl_ecdh_curve`. It is stongly advised to comment that line out so that OpenSSL will use its full capabilities, and it is also possible you are running OpenSSL 1.0.2 necessitating that you do this.
235
236 * Enable and start nginx:
237
238 ```shell
239 # rc-update add nginx default
240 # /etc/init.d/nginx start
241 ```
242
243 If you are using certbot, it is HIGHLY recommend you set up a cron job that renews your certificate, and that you install the suggested `certbot-nginx` plugin. If you don't do these things, you only have yourself to blame when your instance breaks suddenly because you forgot about it.
244
245 First, ensure that the command you will be installing into your crontab works.
246
247 ```shell
248 # /usr/bin/certbot renew --nginx
249 ```
250
251 Assuming not much time has passed since you got certbot working a few steps ago, you should get a message for all domains you installed certificates for saying `Cert not yet due for renewal`.
252
253 Now, run crontab as a superuser with `crontab -e` or `sudo crontab -e` as appropriate, and add the following line to your cron:
254
255 ```cron
256 0 0 1 * * /usr/bin/certbot renew --nginx
257 ```
258
259 This will run certbot on the first of the month at midnight. If you'd rather run more frequently, it's not a bad idea, feel free to go for it.
260
261 #### Other webserver/proxies
262
263 If you would like to use other webservers or proxies, there are example configurations for some popular alternatives in `/home/akkoma/akkoma/installation/`. You can, of course, check out [the Gentoo wiki](https://wiki.gentoo.org) for more information on installing and configuring said alternatives.
264
265 #### Create the uploads folder
266
267 Even if you are using S3, Akkoma needs someplace to store media posted on your instance. If you are using the `/home/akkoma/akkoma` root folder suggested by this guide, simply:
268
269 ```shell
270 akkoma$ mkdir -p ~/akkoma/uploads
271 ```
272
273 #### init.d service
274
275 * Copy example service file
276
277 ```shell
278 # cp /home/akkoma/akkoma/installation/init.d/akkoma /etc/init.d/
279 ```
280
281 * Change the `/opt/akkoma` path in this file to `/home/akkoma/akkoma`
282
283 * Be sure to take a look at this service file and make sure that all other paths fit your installation
284
285 * Enable and start `akkoma`:
286
287 ```shell
288 # rc-update add akkoma default
289 # /etc/init.d/akkoma start
290 ```
291
292 #### Create your first user
293
294 If your instance is up and running, you can create your first user with administrative rights with the following task:
295
296 ```shell
297 akkoma$ MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin
298 ```
299
300 #### Privilege cleanup
301
302 If you opted to allow sudo for the `akkoma` user but would like to remove the ability for greater security, now might be a good time to edit `/etc/sudoers` and/or change the groups the `akkoma` user belongs to. Be sure to restart the akkoma service afterwards to ensure it picks up on the changes.
303
304 {! installation/frontends.include !}
305
306 #### Further reading
307
308 {! installation/further_reading.include !}
309
310 {! support.include !}