1 # Installing on OpenBSD
3 This guide describes the installation and configuration of akkoma (and the required software to run it) on a single OpenBSD 7.2 server.
5 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.
7 {! installation/generic_dependencies.include !}
9 ### Preparing the system
10 #### Required software
12 To install them, run the following command (with doas or as root):
15 pkg_add elixir gmake git postgresql-server postgresql-contrib cmake ffmpeg erlang-wx libmagic
16 pkg_add erlang-wx # Choose the latest version as package version when promted
19 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.
21 #### Optional software
23 Per [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md):
31 pkg_add ffmpeg p5-Image-ExifTool
34 #### Creating the akkoma user
35 Akkoma will be run by a dedicated user, \_akkoma. Before creating it, insert the following lines in login.conf:
42 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.
44 Create the \_akkoma user, assign it the akkoma login class and create its home directory (/home/\_akkoma/): `useradd -m -L akkoma _akkoma`
46 #### Clone akkoma's directory
47 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.
50 Start a shell as the \_postgresql user (as root run `su _postgresql -` then run the `initdb` command to initialize postgresql:
51 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:
54 initdb -D /var/postgresql/data -U postgres
56 If you are not using the default directory, you will have to update the `datadir` variable in the /etc/rc.d/postgresql script.
58 When this is done, enable postgresql so that it starts on boot and start it. As root, run:
60 rcctl enable postgresql
61 rcctl start postgresql
63 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.
66 httpd will have three fuctions:
68 * redirect requests trying to reach the instance over http to the https URL
69 * serve a robots.txt file
70 * get Let's Encrypt certificates, with acme-client
72 Insert the following config in httpd.conf:
74 # $OpenBSD: httpd.conf,v 1.17 2017/04/16 08:50:49 ajacoutot Exp $
76 ext_inet="<IPv4 address>"
77 ext_inet6="<IPv6 address>"
80 listen on $ext_inet port 80 # Comment to disable listening on IPv4
81 listen on $ext_inet6 port 80 # Comment to disable listening on IPv6
82 listen on 127.0.0.1 port 80 # Do NOT comment this line
87 location "/.well-known/acme-challenge/*" {
92 location "/robots.txt" { root "/htdocs/local/" }
93 location "/*" { block return 302 "https://$HTTP_HOST$REQUEST_URI" }
99 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.
101 Create the /var/www/htdocs/local/ folder and write the content of your robots.txt in /var/www/htdocs/local/robots.txt.
102 Check the configuration with `httpd -n`, if it is OK enable and start httpd (as root):
109 acme-client is used to get SSL/TLS certificates from Let's Encrypt.
110 Insert the following configuration in /etc/acme-client.conf:
113 # $OpenBSD: acme-client.conf,v 1.4 2017/03/22 11:14:14 benno Exp $
116 authority letsencrypt-<domain name> {
117 #agreement url "https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf"
118 api url "https://acme-v02.api.letsencrypt.org/directory"
119 account key "/etc/acme/letsencrypt-privkey-<domain name>.pem"
122 domain <domain name> {
123 domain key "/etc/ssl/private/<domain name>.key"
124 domain certificate "/etc/ssl/<domain name>.crt"
125 domain full chain certificate "/etc/ssl/<domain name>.fullchain.pem"
126 sign with letsencrypt-<domain name>
127 challengedir "/var/www/acme/"
130 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.
131 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`.
133 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:
135 ln -s /etc/ssl/<domain name>.fullchain.pem /etc/ssl/<IP address>.crt
136 ln -s /etc/ssl/private/<domain name>.key /etc/ssl/private/<IP address>.key
138 This will have to be done for each IPv4 and IPv6 address relayd listens on.
141 relayd will be used as the reverse proxy sitting in front of akkoma.
142 Insert the following configuration in /etc/relayd.conf:
144 # $OpenBSD: relayd.conf,v 1.4 2018/03/23 09:55:06 claudio Exp $
146 ext_inet="<IPv4 address>"
147 ext_inet6="<IPv6 address>"
149 table <akkoma_server> { 127.0.0.1 }
150 table <httpd_server> { 127.0.0.1 }
152 http protocol plerup { # Protocol for upstream akkoma server
153 #tcp { nodelay, sack, socket buffer 65536, backlog 128 } # Uncomment and adjust as you see fit
154 tls ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
157 # Forward some paths to the local server (as akkoma won't respond to them as you might want)
158 pass request quick path "/robots.txt" forward to <httpd_server>
160 # Append a bunch of headers
161 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
162 match request header append "X-Forwarded-By" value "$SERVER_ADDR:$SERVER_PORT"
164 match response header append "X-XSS-Protection" value "0"
165 match response header append "X-Permitted-Cross-Domain-Policies" value "none"
166 match response header append "X-Frame-Options" value "DENY"
167 match response header append "X-Content-Type-Options" value "nosniff"
168 match response header append "Referrer-Policy" value "same-origin"
169 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
170 match request header append "Connection" value "upgrade"
171 #match response header append "Strict-Transport-Security" value "max-age=63072000; includeSubDomains; preload" # Uncomment this only after you get HTTPS working.
173 # If you do not want remote frontends to be able to access your Akkoma backend server, comment these lines
174 match response header append "Access-Control-Allow-Origin" value "*"
175 match response header append "Access-Control-Allow-Methods" value "POST, PUT, DELETE, GET, PATCH, OPTIONS"
176 match response header append "Access-Control-Allow-Headers" value "Authorization, Content-Type, Idempotency-Key"
177 match response header append "Access-Control-Expose-Headers" value "Link, X-RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-Request-Id"
178 # Stop commenting lines here
182 listen on $ext_inet port https tls # Comment to disable listening on IPv4
183 listen on $ext_inet6 port https tls # Comment to disable listening on IPv6
187 forward to <akkoma_server> port 4000 check http "/" code 200
188 forward to <httpd_server> port 80 check http "/robots.txt" code 200
191 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\>*.
192 Check the configuration with `relayd -n`, if it is OK enable and start relayd (as root):
199 Enabling and configuring pf is highly recommended.
200 In /etc/pf.conf, insert the following configuration:
203 if="<network interface>"
204 authorized_ssh_clients="any"
206 # Skip traffic on loopback interface
210 set block-policy drop
215 match in all scrub (no-df random-id)
216 block in log from urpf-failed
219 pass in quick on $if inet proto icmp to ($if) icmp-type { echoreq unreach paramprob trace } # ICMP
220 pass in quick on $if inet6 proto icmp6 to ($if) icmp6-type { echoreq unreach paramprob timex toobig } # ICMPv6
221 pass in quick on $if proto tcp to ($if) port { http https } # relayd/httpd
222 pass in quick on $if proto tcp from $authorized_ssh_clients to ($if) port ssh
224 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.
226 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`.
228 #### Configure and start akkoma
229 Enter a shell as \_akkoma (as root `su _akkoma -`) and enter akkoma's installation directory (`cd ~/akkoma/`).
231 Then follow the main installation guide:
234 * run `MIX_ENV=prod mix pleroma.instance gen` and enter your instance's information when asked
235 * 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.
236 * 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.
237 * return to a \_akkoma shell into akkoma's installation directory (`su _akkoma -;cd ~/akkoma`) and run `MIX_ENV=prod mix ecto.migrate`
239 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.
240 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.
242 ##### Starting akkoma at boot
243 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).
246 #### Create administrative user
248 If your instance is up and running, you can create your first user with administrative rights with the following command as the \_akkoma user.
250 LC_ALL=en_US.UTF-8 MIX_ENV=prod mix pleroma.user new <username> <your@emailaddress> --admin
253 {! installation/frontends.include !}
257 {! installation/further_reading.include !}
259 {! support.include !}