This guide is a step-by-step installation guide for Alpine Linux.
Commands starting with `#` should be launched as root, with `$` they should be launched as the `pleroma` user, with `%` they can be launched with any user on the machine, in case they need a specific user they’ll be prefixed with `username $`. It is recommended to keep the session until it changes of user or tells you to exit. See [[unix session management]] if you do not know how to do it.
### Required packages
* `build-base`
* `elixir`
* `erlang`
* `erlang-eldap`: *optionnal*, used if you want LDAP
* `erlang-parsetools`
* `erlang-xmerl`
* `git`
* `postgresql`
* `postgresql-contrib`
#### Optional packages used in this guide
* `nginx` (preferred, example configs for other reverse proxies can be found in the repo)
* `certbot` (or any other ACME client for Let’s Encrypt certificates)
### Prepare the system
* First make sure to have the community repository enabled:
FIXME: Verify that tee(1) is in Alpine’s base, check if there is a mirror-agnostic way to add community repo
```shell
# echo "https://nl.alpinelinux.org/alpine/latest-stable/community" | tee -a /etc/apk/repository
* Install `erlang-eldap` if you want to enable ldap authenticator
```shell
# apk add erlang-eldap
```
### Install PostgreSQL
* Install Postgresql server:
```shell
# apk add postgresql postgresql-contrib
```
* Initialize database:
```shell
FIXME
```
* Enable and start postgresql server:
```shell
# rc-update add postgresql
# service postgresql start
```
### Finalize installation
If you want to open your newly installed instance to the world, you should run nginx or some other webserver/proxy in front of Pleroma and you should consider to create an OpenRC service file for Pleroma.
#### Nginx
* Install nginx, if not already done:
```shell
# apk add nginx
```
* Setup your SSL cert, using your method of choice or certbot. If using certbot, first install it:
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).
* Copy the example nginx configuration to the nginx folder
This guide is a step-by-step installation guide for Arch Linux.
Commands starting with `#` should be launched as root, with `$` they should be launched as the `pleroma` user, with `%` they can be launched with any user on the machine, in case they need a specific user they’ll be prefixed with `username $`. It is recommended to keep the session until it changes of user or tells you to exit. See [[unix session management]] if you do not know how to do it.
### Required packages
* `postgresql`
* `elixir`
* `git`
* `base-devel`
#### Optional packages used in this guide
* `nginx` (preferred, example configs for other reverse proxies can be found in the repo)
* `certbot` (or any other ACME client for Let’s Encrypt certificates)
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).
---
* Copy the example nginx configuration and activate it:
This guide is a step-by-step installation guide for CentOS 7.
Commands starting with `#` should be launched as root, with `$` they should be launched as the `pleroma` user, with `%` they can be launched with any user on the machine, in case they need a specific user they’ll be prefixed with `username $`. It is recommended to keep the session until it changes of user or tells you to exit. See [[unix session management]] if you do not know how to do it.
### Required packages
* `postgresql` (9,6+, CentOS 7 comes with 9.2, we will install version 11 in this guide)
* Download [latest Elixir release from Github](https://github.com/elixir-lang/elixir/releases/tag/v1.8.1) (Example for the newest version at the time when this manual was written)
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).
---
* Copy the example nginx configuration to the nginx folder
This guide is a step-by-step installation guide for Debian-based distributions, it assumes a setup similar to Debian Stretch.
Commands starting with `#` should be launched as root, with `$` they should be launched as the `pleroma` user, with `%` they can be launched with any user on the machine, in case they need a specific user they’ll be prefixed with `username $`. It is recommended to keep the session until it changes of user or tells you to exit. See [[unix session management]] if you do not know how to do it.
### Required packages
* `postgresql` (9.6+, Ubuntu 16.04 comes with 9.5, you can get a newer version from <https://www.postgresql.org/download/linux/ubuntu/>
* `postgresql-contrib` (9.6+, same situtation as above)
* `elixir` (1.7+, Debian and Ubuntu ships old versions, install from <https://elixir-lang.org/install.html#unix-and-unix-like> or use [asdf](https://github.com/asdf-vm/asdf) as the pleroma user)
* `erlang-dev`
* `erlang-tools`
* `erlang-parsetools`
* `erlang-eldap`, if you want to enable ldap authenticator
* `erlang-xmerl`
* `git`
* `build-essential`
#### Optional packages used in this guide
* `nginx` (preferred, example configs for other reverse proxies can be found in the repo)
* `certbot` (or any other ACME client for Let’s Encrypt certificates)
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).
---
* Copy the example nginx configuration and activate it:
Commands starting with `#` should be launched as root, with `$` they should be launched as the `pleroma` user, with `%` they can be launched with any user on the machine, in case they need a specific user they’ll be prefixed with `username $`. It is recommended to keep the session until it changes of user or tells you to exit. See [[unix session management]] if you do not know how to do it.
This part assumes:
- You have installed and configured the system dependencies required for pleroma
- You have added a system `pleroma` user with an existent home (it is assumed to be `/opt/pleroma`)
And you'll get:
- Pleroma installed and configured in `~pleroma/pleroma`.
Note: The `master` branch was selected, you can switch to another one with `git checkout`.
## Install Elixir dependencies
* Install the dependencies for Pleroma and answer with `yes` if it asks you to install `Hex`:
```shell
pleroma $ mix deps.get
```
## Configuration
* Generate the configuration: ``mix pleroma.instance gen``
* Answer with `yes` if it asks you to install `rebar3`.
* This may take some time, because parts of pleroma get compiled first.
* After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`.
* Check the configuration and if all looks right, copy it, so Pleroma will load it (`prod.secret.exs` for production instances, `dev.secret.exs` for development instances):
* The configuration generator also creates the file `config/setup_db.psql`, with which you can create the database:
```shell
% psql -U postgres -f config/setup_db.psql
```
* Change to production mode and make the next `pleroma` sessions default to it:
```shell
pleroma $ export MIX_ENV=prod
pleroma $ echo MIX_ENV=prod > ~/.profile
```
* Now run the database migration:
```shell
pleroma $ mix ecto.migrate
```
* Create the admin account:
```shell
pleroma $ mix pleroma.user new <username> <your@emailaddress> --admin
```
* Now you can start Pleroma manually for tests:
```shell
pleroma $ mix phx.server
```
-Pleroma is now installed and configured, you can now start pleroma as a daemon (depends on your system, a de-facto generic way is ``service pleroma start`` as root.
+## Daemonize
+Pick a sub-section depending on your system.
+
+### OpenRC
+This one is for systems using OpenRC or compatible, such as: Alpine, Gentoo by default
+* Edit the service file and make sure that all paths fit your installation
+
+* Enable and start `pleroma`:
+```shell
+# rcctl enable pleroma
+# rcctl start pleroma
+```
## Support & Questions
For support or questions please ask in the chatroom, available via IRC at `#pleroma` on [Freenode](https://freenode.net/) and via [Matrix on `#freenode_#pleroma:matrix.org`](https://matrix.heldscal.la/#/room/#freenode_#pleroma:matrix.org).
This guide is a step-by-step installation guide for Gentoo Linux.
Commands starting with `#` should be launched as root, with `$` they should be launched as the `pleroma` user, with `%` they can be launched with any user on the machine, in case they need a specific user they’ll be prefixed with `username $`. It is recommended to keep the session until it changes of user or tells you to exit. See [[unix session management]] if you do not know how to do it.
### USE flags
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 `pleroma` would do fine, depending on how you like to arrange your package.use flags.
```text
dev-db/postgresql uuid
```
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.
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.
### Installing a cron daemon
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.
### Required ebuilds
* `dev-db/postgresql`
* `dev-lang/elixir`
* `dev-vcs/git`
#### Optional ebuilds used in this guide
* `www-servers/nginx` (preferred, example configs for other reverse proxies can be found in the repo)
* `app-crypt/certbot` (or any other ACME client for Let’s Encrypt certificates)
* `app-crypt/certbot-nginx` (nginx certbot plugin that allows use of the all-powerful `--nginx` flag on certbot)
### Prepare the system
* First ensure that you have the latest copy of the portage ebuilds if you have not synced them yet:
```shell
# emaint sync -a
```
* Emerge all required the required and suggested software in one go:
If you would not like to install the optional packages, remove them from this line.
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.
### Install PostgreSQL
[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.
Important Note: This guide will assume that `dev-db/postgresql:11` is the latest stable slot on your architecture, feel free to change it to something else, just note that pleroma require PostgreSQL 9.6+.
* Make sure you have installed PostgreSQL:
```shell
# emerge --ask --noreplace dev-db/postgresql:11
```
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.
* Initialize the database cluster:
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.
```shell
# emerge --config dev-db/postgresql:11
```
* Start postgres and enable the system service
```shell
# /etc/init.d/postgresql-11 start
# rc-update add postgresql-11 default
```
#### Nginx
* Make sure you have installed nginx:
```shell
# emerge --ask --noreplace www-servers/nginx
```
* Create directories for available and enabled sites:
```shell
# mkdir -p /etc/nginx/sites-{available,enabled}
```
* Append the following line at the end of the `http` block in `/etc/nginx/nginx.conf`:
```Nginx
include sites-enabled/*;
```
* Setup your SSL cert, using your method of choice or certbot. If using certbot, install it if you haven't already:
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.
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.
---
* Copy the example nginx configuration and activate it:
* Take some time to ensure that your nginx config is correct
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.
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.
* Enable and start nginx:
if you use OpenRC (default on gentoo):
```shell
# rc-update add nginx default
# /etc/init.d/nginx start
```
if you use SystemD:
```shell
# systemctl enable --now nginx.service
```
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.
First, ensure that the command you will be installing into your crontab works.
```shell
# /usr/bin/certbot renew --nginx
```
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`.
Now, run crontab as a superuser with `crontab -e` or `sudo crontab -e` as appropriate, and add the following line to your cron:
```cron
0 0 1 * * /usr/bin/certbot renew --nginx
```
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.
#### Other webserver/proxies
If you would like to use other webservers or proxies, there are example configurations for some popular alternatives in `/home/pleroma/pleroma/installation/`. You can, of course, check out [the Gentoo wiki](https://wiki.gentoo.org) for more information on installing and configuring said alternatives.
-* Edit the service file and make sure that all paths fit your installation
-* Enable and start `pleroma.service`:
-
-```shell
-# systemctl enable --now pleroma.service
-```
-
#### Privilege cleanup
If you opted to allow sudo for the `pleroma` 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 `pleroma` user belongs to. Be sure to restart the pleroma service afterwards to ensure it picks up on the changes.
### Install and Configure Pleroma
You can now follow [Generic Pleroma Installation](generic_pleroma_en.html).
This guide is a step-by-step installation guide for NetBSD.
Commands starting with `#` should be launched as root, with `$` they should be launched as the `pleroma` user, with `%` they can be launched with any user on the machine, in case they need a specific user they’ll be prefixed with `username $`. It is recommended to keep the session until it changes of user or tells you to exit. See [[unix session management]] if you do not know how to do it.
## Required software
pkgin should have been installed by the NetBSD installer if you selected
the right options. If it isn't installed, install it using pkg_add.
Note that `postgresql11-contrib` is needed for the Postgres extensions
Pleroma uses.
The `mksh` shell is needed to run the Elixir `mix` script.
This guide is a step-by-step installation guide for OpenBSD.
Commands starting with `#` should be launched as root, with `$` they should be launched as the `pleroma` user, with `%` they can be launched with any user on the machine, in case they need a specific user they’ll be prefixed with `username $`. It is recommended to keep the session until it changes of user or tells you to exit. See [[unix session management]] if you do not know how to do it.
Pleroma requires a reverse proxy, OpenBSD has relayd in base (and is used in this guide), ports are available for nginx (`www/nginx`) and apache (`www/apache-httpd`). Independently of the reverse proxy, [acme-client(1)](https://man.openbsd.org/acme-client) can be used to get a certificate from Let's Encrypt.
### Prepare the system
Pleroma will be run by a dedicated user, `pleroma`. Before creating it, insert the following lines in `login.conf`:
```plain
pleroma:\
:datasize-max=1536M:\
:datasize-cur=1536M:\
:openfiles-max=4096
```
This creates a "pleroma" login class and sets higher values than default for datasize and openfiles (see [login.conf(5)](https://man.openbsd.org/login.conf)), this is required to avoid having pleroma crash some time after starting.
To check that it started properly and didn't fail right after starting, you can run `ps aux | grep postgres`, there should be multiple lines of output.
#### Install httpd
httpd will have three fuctions:
* redirect requests trying to reach the instance over http to the https URL
* get Let's Encrypt certificates, with acme-client
Do not forget to change `<IPv4/6 address>` to your server's addresses. If httpd should only listen on one protocol family, comment one of the two first `listen` options.
Check the configuration with `httpd -n`, if it is OK enable and start httpd (as root):
```shell
# rcctl enable httpd
# rcctl start httpd
```
#### acme-client
acme-client is used to get SSL/TLS certificates from Let's Encrypt.
Insert the following configuration in `/etc/acme-client.conf`:
domain full chain certificate "/etc/ssl/<domain name>.fullchain.pem"
sign with letsencrypt-<domain name>
challengedir "/var/www/acme/"
}
```
Replace *\<domain name\>* by the domain name you'll use for your instance. As root, run `acme-client -n` to check the config, then `acme-client -ADv <domain name>` to create account and domain keys, and request a certificate for the first time.
Make acme-client run everyday by adding it in /etc/daily.local. As root, run the following command: `echo "acme-client <domain name>" >> /etc/daily.local`.
Relayd will look for certificates and keys based on the address it listens on (see relayd section), the easiest way to make them available to relayd is to create a link:
match request header append "X-Forwarded-For" value "$REMOTE_ADDR" # This two header and the next one are not strictly required by pleroma but adding them won't hurt
match request header append "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT"
match response header append "X-XSS-Protection" value "1; mode=block"
match response header append "X-Permitted-Cross-Domain-Policies" value "none"
match response header append "X-Frame-Options" value "DENY"
match response header append "X-Content-Type-Options" value "nosniff"
match response header append "Referrer-Policy" value "same-origin"
match response header append "X-Download-Options" value "noopen"
match response header append "Content-Security-Policy" value "default-src 'none'; base-uri 'self'; form-action 'self'; img-src 'self' data: https:; media-src 'self' https:; style-src 'self' 'unsafe-inline'; font-src 'self'; script-src 'self'; connect-src 'self' wss://CHANGEME.tld; upgrade-insecure-requests;" # Modify "CHANGEME.tld" and set your instance's domain here
match request header append "Connection" value "upgrade"
#match response header append "Strict-Transport-Security" value "max-age=31536000; includeSubDomains" # Uncomment this only after you get HTTPS working.
# If you do not want remote frontends to be able to access your Pleroma backend server, comment these lines
match response header append "Access-Control-Allow-Origin" value "*"
match response header append "Access-Control-Allow-Methods" value "POST, PUT, DELETE, GET, PATCH, OPTIONS"
match response header append "Access-Control-Allow-Headers" value "Authorization, Content-Type, Idempotency-Key"
match response header append "Access-Control-Expose-Headers" value "Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id"
# Stop commenting lines here
}
relay wwwtls {
listen on $ext_inet port https tls # Comment to disable listening on IPv4
listen on $ext_inet6 port https tls # Comment to disable listening on IPv6
protocol plerup
forward to <pleroma_server> port 4000 check http "/" code 200
}
```
Again, change *\<IPv4/6 address\>* to your server's address(es) and comment one of the two *listen* options if needed. Also change *wss://CHANGEME.tld* to *wss://\<your instance's domain name\>*.
Check the configuration with `relayd -n`, if it is OK enable and start relayd (as root):
```shell
# rcctl enable relayd
# rcctl start relayd
```
#### pf
Enabling and configuring pf is highly recommended.
In /etc/pf.conf, insert the following configuration:
```
# Macros
if="<network interface>"
authorized_ssh_clients="any"
# Skip traffic on loopback interface
set skip on lo
# Default behavior
set block-policy drop
block in log all
pass out quick
# Security features
match in all scrub (no-df random-id)
block in log from urpf-failed
# Rules
pass in quick on $if inet proto icmp to ($if) icmp-type { echoreq unreach paramprob trace } # ICMP
pass in quick on $if inet6 proto icmp6 to ($if) icmp6-type { echoreq unreach paramprob timex toobig } # ICMPv6
pass in quick on $if proto tcp to ($if) port { http https } # relayd/httpd
pass in quick on $if proto tcp from $authorized_ssh_clients to ($if) port ssh
```
Replace `<network interface>` by your server's network interface name (which you can get with ifconfig). Consider replacing the content of the authorized\_ssh\_clients macro by, for exemple, your home IP address, to avoid SSH connection attempts from bots.
Check pf's configuration by running `pfctl -nf /etc/pf.conf`, load it with `pfctl -f /etc/pf.conf` and enable pf at boot with `rcctl enable pf`.
-##### Starting pleroma at boot
-An rc script to automatically start pleroma at boot hasn't been written yet, it can be run in a tmux session (tmux is in base).
-FIXME: AFAIK it has been done.
-
### Install and Configure Pleroma
You can now follow [Generic Pleroma Installation](generic_pleroma_en.html).