2019-03-28 16:46:30 +00:00
# Installing on OpenBSD
2019-11-13 11:48:53 +00:00
2023-01-02 11:50:30 +00:00
This guide describes the installation and configuration of akkoma (and the required software to run it) on a single OpenBSD 7.2 server.
2019-11-13 11:48:53 +00:00
2019-03-28 16:46:30 +00:00
For any additional information regarding commands and configuration files mentioned here, check the man pages [online ](https://man.openbsd.org/ ) or directly on your server with the man command.
2022-07-15 12:27:16 +00:00
{! installation/generic_dependencies.include !}
2019-11-13 11:48:53 +00:00
2021-06-11 06:43:36 +00:00
### Preparing the system
#### Required software
2019-03-28 16:46:30 +00:00
2019-11-13 11:48:53 +00:00
To install them, run the following command (with doas or as root):
```
2023-01-02 11:56:49 +00:00
pkg_add elixir gmake git postgresql-server postgresql-contrib cmake ffmpeg erlang-wx libmagic
pkg_add erlang-wx # Choose the latest version as package version when promted
2019-11-13 11:48:53 +00:00
```
2019-03-28 16:46:30 +00:00
2022-07-02 21:00:01 +00:00
Akkoma requires a reverse proxy, OpenBSD has relayd in base (and is used in this guide) and packages/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.
2019-03-28 16:46:30 +00:00
2020-09-26 16:32:16 +00:00
#### Optional software
2021-01-10 08:25:36 +00:00
Per [`docs/installation/optional/media_graphics_packages.md` ](../installation/optional/media_graphics_packages.md ):
2020-09-26 16:32:16 +00:00
* ImageMagick
* ffmpeg
* exiftool
To install the above:
```
2023-01-02 11:56:49 +00:00
pkg_add ffmpeg p5-Image-ExifTool
2020-09-26 16:32:16 +00:00
```
2022-07-02 21:00:01 +00:00
#### Creating the akkoma user
2023-01-02 11:59:46 +00:00
Akkoma will be run by a dedicated user, `_akkoma` . Before creating it, insert the following lines in `/etc/login.conf` :
2019-03-28 16:46:30 +00:00
```
2022-07-02 21:00:01 +00:00
akkoma:\
2019-03-28 16:46:30 +00:00
:datasize-max=1536M:\
:datasize-cur=1536M:\
:openfiles-max=4096
```
2023-01-02 11:59:46 +00:00
This creates a `akkoma` 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 akkoma crash some time after starting.
2019-03-28 16:46:30 +00:00
2023-01-02 11:59:46 +00:00
Create the `_akkoma` user, assign it the akkoma login class and create its home directory (`/home/_akkoma/`): `useradd -m -L akkoma _akkoma`
2019-03-28 16:46:30 +00:00
2022-07-02 21:00:01 +00:00
#### Clone akkoma's directory
2023-01-02 11:59:46 +00:00
Enter a shell as the `_akkoma` user. As root, run `su _akkoma -;cd` . Then clone the repository with `git clone https://akkoma.dev/AkkomaGang/akkoma.git` . Akkoma is now installed in `/home/_akkoma/akkoma/` , it will be configured and started at the end of this guide.
2019-03-28 16:46:30 +00:00
2019-11-13 11:48:53 +00:00
#### PostgreSQL
2023-01-02 11:59:46 +00:00
Start a shell as the `_postgresql` user (as root run `su _postgresql -` then run the `initdb` command to initialize postgresql.
You will need to specify pgdata directory to the default (`/var/postgresql/data`) with the `-D <path>` and set the user to postgres with the `-U <username>` flag. This can be done as follows:
2020-01-22 22:33:10 +00:00
```
initdb -D /var/postgresql/data -U postgres
```
2023-01-02 11:59:46 +00:00
If you are not using the default directory, you will have to update the `datadir` variable in the `/etc/rc.d/postgresql` script.
2019-03-28 16:46:30 +00:00
When this is done, enable postgresql so that it starts on boot and start it. As root, run:
```
rcctl enable postgresql
rcctl start postgresql
```
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.
#### httpd
httpd will have three fuctions:
2019-11-13 11:48:53 +00:00
2019-03-28 16:46:30 +00:00
* redirect requests trying to reach the instance over http to the https URL
* serve a robots.txt file
* get Let's Encrypt certificates, with acme-client
2023-01-02 11:59:46 +00:00
Insert the following config in `/etc/httpd.conf` :
2019-03-28 16:46:30 +00:00
```
# $OpenBSD: httpd.conf,v 1.17 2017/04/16 08:50:49 ajacoutot Exp $
ext_inet="< IPv4 address > "
ext_inet6="< IPv6 address > "
server "default" {
listen on $ext_inet port 80 # Comment to disable listening on IPv4
listen on $ext_inet6 port 80 # Comment to disable listening on IPv6
listen on 127.0.0.1 port 80 # Do NOT comment this line
log syslog
directory no index
location "/.well-known/acme-challenge/*" {
root "/acme"
request strip 2
}
location "/robots.txt" { root "/htdocs/local/" }
location "/*" { block return 302 "https://$HTTP_HOST$REQUEST_URI" }
}
```
2019-11-13 11:48:53 +00:00
Do not forget to change *<IPv4/6 address\>* to your server's address(es). If httpd should only listen on one protocol family, comment one of the two first *listen* options.
2019-03-28 16:46:30 +00:00
2023-01-02 11:59:46 +00:00
Create the `/var/www/htdocs/local/` folder and write the content of your robots.txt in `/var/www/htdocs/local/robots.txt` .
2019-03-28 16:46:30 +00:00
Check the configuration with `httpd -n` , if it is OK enable and start httpd (as root):
```
rcctl enable httpd
rcctl start httpd
```
#### acme-client
2019-11-13 11:48:53 +00:00
acme-client is used to get SSL/TLS certificates from Let's Encrypt.
2023-01-02 11:59:46 +00:00
Insert the following configuration in `/etc/acme-client.conf` :
2019-03-28 16:46:30 +00:00
```
#
# $OpenBSD: acme-client.conf,v 1.4 2017/03/22 11:14:14 benno Exp $
#
authority letsencrypt-< domain name > {
#agreement url "https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf"
2020-01-22 22:33:10 +00:00
api url "https://acme-v02.api.letsencrypt.org/directory"
2019-03-28 16:46:30 +00:00
account key "/etc/acme/letsencrypt-privkey-< domain name > .pem"
}
domain < domain name > {
domain key "/etc/ssl/private/< domain name > .key"
domain certificate "/etc/ssl/< domain name > .crt"
domain full chain certificate "/etc/ssl/< domain name > .fullchain.pem"
sign with letsencrypt-< domain name >
challengedir "/var/www/acme/"
}
```
2019-11-13 11:48:53 +00:00
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.
2023-01-02 11:59:46 +00:00
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` .
2019-03-28 16:46:30 +00:00
Relayd will look for certificates and keys based on the address it listens on (see next part), the easiest way to make them available to relayd is to create a link, as root run:
```
ln -s /etc/ssl/< domain name > .fullchain.pem /etc/ssl/< IP address > .crt
ln -s /etc/ssl/private/< domain name > .key /etc/ssl/private/< IP address > .key
```
This will have to be done for each IPv4 and IPv6 address relayd listens on.
#### relayd
2022-07-02 21:00:01 +00:00
relayd will be used as the reverse proxy sitting in front of akkoma.
2023-01-02 11:59:46 +00:00
Insert the following configuration in `/etc/relayd.conf` :
2019-03-28 16:46:30 +00:00
```
# $OpenBSD: relayd.conf,v 1.4 2018/03/23 09:55:06 claudio Exp $
ext_inet="< IPv4 address > "
ext_inet6="< IPv6 address > "
2022-07-02 21:00:01 +00:00
table < akkoma_server > { 127.0.0.1 }
2019-03-28 16:46:30 +00:00
table < httpd_server > { 127.0.0.1 }
2022-07-02 21:00:01 +00:00
http protocol plerup { # Protocol for upstream akkoma server
2019-03-28 16:46:30 +00:00
#tcp { nodelay, sack, socket buffer 65536, backlog 128 } # Uncomment and adjust as you see fit
tls ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
tls ecdhe secp384r1
2022-07-02 21:00:01 +00:00
# Forward some paths to the local server (as akkoma won't respond to them as you might want)
2019-03-28 16:46:30 +00:00
pass request quick path "/robots.txt" forward to < httpd_server >
# Append a bunch of headers
2022-07-02 21:00:01 +00:00
match request header append "X-Forwarded-For" value "$REMOTE_ADDR" # This two header and the next one are not strictly required by akkoma but adding them won't hurt
2019-03-28 16:46:30 +00:00
match request header append "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT"
2022-11-20 01:40:20 +00:00
match response header append "X-XSS-Protection" value "0"
2019-03-28 16:46:30 +00:00
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"
2022-11-20 21:20:06 +00:00
match response header append "Content-Security-Policy" value "default-src 'none'; base-uri 'none'; 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
2019-03-28 16:46:30 +00:00
match request header append "Connection" value "upgrade"
2022-11-20 21:20:06 +00:00
#match response header append "Strict-Transport-Security" value "max-age=63072000; includeSubDomains; preload" # Uncomment this only after you get HTTPS working.
2019-03-28 16:46:30 +00:00
2022-07-02 21:00:01 +00:00
# If you do not want remote frontends to be able to access your Akkoma backend server, comment these lines
2019-03-28 16:46:30 +00:00
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
2022-07-02 21:00:01 +00:00
forward to < akkoma_server > port 4000 check http "/" code 200
2019-03-28 16:46:30 +00:00
forward to < httpd_server > port 80 check http "/robots.txt" code 200
}
```
2019-11-13 11:48:53 +00:00
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\>* .
2019-03-28 16:46:30 +00:00
Check the configuration with `relayd -n` , if it is OK enable and start relayd (as root):
```
rcctl enable relayd
rcctl start relayd
```
#### pf
2019-11-13 11:48:53 +00:00
Enabling and configuring pf is highly recommended.
2023-01-02 11:59:46 +00:00
In `/etc/pf.conf` , insert the following configuration:
2019-03-28 16:46:30 +00:00
```
# 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
```
2023-01-02 11:59:46 +00:00
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 example, your home IP address, to avoid SSH connection attempts from bots.
2019-03-28 16:46:30 +00:00
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` .
2022-07-02 21:00:01 +00:00
#### Configure and start akkoma
2023-01-02 11:59:46 +00:00
Enter a shell as `_akkoma` (as root `su _akkoma -` ) and enter akkoma's installation directory (`cd ~/akkoma/`).
2019-11-13 11:48:53 +00:00
2019-03-28 16:46:30 +00:00
Then follow the main installation guide:
2019-11-13 11:48:53 +00:00
2019-03-28 16:46:30 +00:00
* run `mix deps.get`
2021-05-16 17:20:20 +00:00
* run `MIX_ENV=prod mix pleroma.instance gen` and enter your instance's information when asked
2023-01-02 11:59:46 +00:00
* copy `config/generated_config.exs` to `config/prod.secret.exs` . The default values should be sufficient but you should edit it and check that everything seems OK.
2022-07-02 21:00:01 +00:00
* exit your current shell back to a root one and run `psql -U postgres -f /home/_akkoma/akkoma/config/setup_db.psql` to setup the database.
2023-01-02 11:59:46 +00:00
* return to a `_akkoma` shell into akkoma's installation directory (`su _akkoma -;cd ~/akkoma`) and run `MIX_ENV=prod mix ecto.migrate`
2019-03-28 16:46:30 +00:00
2023-01-02 11:59:46 +00:00
As `_akkoma` in `/home/_akkoma/akkoma` , you can now run `LC_ALL=en_US.UTF-8 MIX_ENV=prod mix phx.server` to start your instance.
2019-03-28 16:46:30 +00:00
In another SSH session/tmux window, check that it is working properly by running `ftp -MVo - http://127.0.0.1:4000/api/v1/instance` , you should get json output. Double-check that *uri* 's value is your instance's domain name.
2022-07-02 21:00:01 +00:00
##### Starting akkoma at boot
An rc script to automatically start akkoma at boot hasn't been written yet, it can be run in a tmux session (tmux is in base).
2020-01-22 22:33:10 +00:00
#### Create administrative user
2023-01-02 11:59:46 +00:00
If your instance is up and running, you can create your first user with administrative rights with the following command as the `_akkoma` user.
2020-01-22 22:33:10 +00:00
```
LC_ALL=en_US.UTF-8 MIX_ENV=prod mix pleroma.user new < username > < your @ emailaddress > --admin
```
2020-06-22 09:41:22 +00:00
2022-08-30 09:56:33 +00:00
{! installation/frontends.include !}
2020-06-22 09:41:22 +00:00
#### Further reading
2022-07-15 12:27:16 +00:00
{! installation/further_reading.include !}
2020-06-22 09:41:22 +00:00
2022-07-15 12:27:16 +00:00
{! support.include !}