logo

pleroma

My custom branche(s) on git.pleroma.social/pleroma/pleroma git clone https://hacktivis.me/git/pleroma.git

gentoo_otp_en.md (9175B)

    

  1. # Packaged install on Gentoo Linux
  3. {! backend/installation/otp_vs_from_source.include !}
  5. This guide covers installation via Gentoo provided packaging. A [manual installation guide for gentoo](./gentoo_en.md) is also available.
  7. ## Installation
  9. 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. `pleroma$` should be run as the `pleroma` user.
  11. {! backend/installation/generic_dependencies.include !}
  13. ### Installing a cron daemon
  15. 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.
  17. ### Required ebuilds
  19. * `www-apps/pleroma`
  21. #### Optional ebuilds used in this guide
  23. * `www-servers/nginx` (preferred, example configs for other reverse proxies can be found in the repo)
  24. * `app-crypt/certbot` (or any other ACME client for Let’s Encrypt certificates)
  25. * `app-crypt/certbot-nginx` (nginx certbot plugin that allows use of the all-powerful `--nginx` flag on certbot)
  26. * `media-gfx/imagemagick`
  27. * `media-video/ffmpeg`
  28. * `media-libs/exiftool`
  30. ### Prepare the system
  32. * If you haven't yet done so, add the [Gentoo User Repository (GURU)](https://wiki.gentoo.org/wiki/Project:GURU), where the `www-apps/pleroma` ebuild currently lives at:
  33. ```shell
  34.  # eselect repository enable guru
  35. ```
  37. * Ensure that you have the latest copy of the Gentoo and GURU ebuilds if you have not synced them yet:
  39. ```shell
  40.  # emaint sync -a
  41. ```
  44. * Emerge all required the required and suggested software in one go:
  46. ```shell
  47.  # emerge --ask www-apps/pleroma www-servers/nginx app-crypt/certbot app-crypt/certbot-nginx
  48. ```
  50. If you would not like to install the optional packages, remove them from this line.
  52. 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, stretch 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.
  54. ### Setup PostgreSQL
  56. [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.
  58. * Initialize the database cluster
  60. 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.
  62. ```shell
  63.  # emerge --config dev-db/postgresql:11
  64. ```
  66. ### Install media / graphics packages (optional)
  68. See [Optional software packages needed for specific functionality](optional/media_graphics_packages.md) for details.
  70. ```shell
  71. # emerge --ask media-video/ffmpeg media-gfx/imagemagick media-libs/exiftool
  72. ```
  74. ### Setup PleromaBE
  76. * Generate the configuration:
  78. ```shell
  79.  # pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql"
  80. ```
  82. * Create the PostgreSQL database
  84. ```shell
  85.  # sudo -u postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"
  86. ```
  88. * Now run the database migration:
  90. ```shell
  91.  # pleroma_ctl migrate
  92. ```
  94. * Optional: If you have installed RUM indexes (`dev-db/rum`) you also need to run:
  95. ```
  96.  # sudo -Hu pleroma "pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/"
  97. ```
  99. * Now you can start Pleroma already and add it in the default runlevel
  101. ```shell
  102.  # rc-service pleroma start
  103.  # rc-update add pleroma default
  104. ```
  106. It probably won't work over the public internet quite yet, however, as we still need to set up a web server to proxy to the pleroma application, as well as configure SSL.
  108. ### Finalize installation
  110. 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 Pleroma. It is also a good idea to set up Pleroma to run as a system service.
  112. #### Nginx
  114. * Install nginx, if not already done:
  116. ```shell
  117.  # emerge --ask www-servers/nginx
  118. ```
  120. * Create directories for available and enabled sites:
  122. ```shell
  123.  # mkdir -p /etc/nginx/sites-{available,enabled}
  124. ```
  126. * Append the following line at the end of the `http` block in `/etc/nginx/nginx.conf`:
  128. ```Nginx
  129. include sites-enabled/*;
  130. ```
  132. * Setup your SSL cert, using your method of choice or certbot. If using certbot, install it if you haven't already:
  134. ```shell
  135.  # emerge --ask app-crypt/certbot app-crypt/certbot-nginx
  136. ```
  138. and then set it up:
  140. ```shell
  141.  # mkdir -p /var/lib/letsencrypt/
  142.  # certbot certonly --email <your@emailaddress> -d <yourdomain> --standalone
  143. ```
  145. 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.
  147. 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.
  149. ---
  151. * Copy the example nginx configuration and activate it:
  153. ```shell
  154.  # cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/
  155.  # ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx
  156. ```
  158. * Take some time to ensure that your nginx config is correct
  160. Replace all instances of `example.tld` with your instance's public URL. If for whatever reason you made changes to the port that your pleroma app runs on, be sure that is reflected in your configuration.
  162. 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.
  164. * Enable and start nginx:
  166. ```shell
  167.  # rc-update add nginx default
  168.  # /etc/init.d/nginx start
  169. ```
  171. 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.
  173. First, ensure that the command you will be installing into your crontab works.
  175. ```shell
  176.  # /usr/bin/certbot renew --nginx
  177. ```
  179. 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`.
  181. Now, run crontab as a superuser with `crontab -e` or `sudo crontab -e` as appropriate, and add the following line to your cron:
  183. ```cron
  184. 0 0 1 * * /usr/bin/certbot renew --nginx
  185. ```
  187. 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.
  189. #### Other webserver/proxies
  191. If you would like to use other webservers or proxies, there are example configurations for some popular alternatives in `/opt/pleroma/installation/`. You can, of course, check out [the Gentoo wiki](https://wiki.gentoo.org) for more information on installing and configuring said alternatives.
  193. #### Create your first user
  195. If your instance is up and running, you can create your first user with administrative rights with the following task:
  197. ```shell
  198. pleroma$ pleroma_ctl user new <username> <your@emailaddress> --admin
  199. ```
  201. #### Further reading
  203. {! backend/installation/further_reading.include !}
  205. ## Questions
  207. 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.