2019-06-21 02:48:13 +00:00
# Installing on Linux using OTP releases
2022-07-15 12:27:16 +00:00
{! installation/otp_vs_from_source.include !}
2021-08-10 06:09:31 +00:00
2022-07-02 21:00:01 +00:00
This guide covers a installation using an OTP release. To install Akkoma from source, please check out the corresponding guide for your distro.
2021-08-10 06:09:31 +00:00
2019-06-21 02:48:13 +00:00
## Pre-requisites
2023-08-05 14:39:03 +00:00
* A machine running Linux with GNU (e.g. Debian, Ubuntu) or musl (e.g. Alpine) libc and an `x86_64` or `arm64` CPU you have root access to. If you are not sure if it's compatible see [Detecting flavour section ](#detecting-flavour ) below
2022-07-28 10:19:32 +00:00
* For installing OTP releases on RedHat-based distros like Fedora and Centos Stream, please follow [this guide ](./otp_redhat_en.md ) instead.
2019-06-21 02:48:13 +00:00
* A (sub)domain pointed to the machine
You will be running commands as root. If you aren't root already, please elevate your priviledges by executing `sudo su` /`su`.
2019-12-09 17:09:47 +00:00
While in theory OTP releases are possbile to install on any compatible machine, for the sake of simplicity this guide focuses only on Debian/Ubuntu and Alpine.
2019-06-21 02:48:13 +00:00
### Detecting flavour
2022-07-28 10:36:51 +00:00
Use the following mapping to figure out your flavour:
2023-07-20 16:45:53 +00:00
| distribution | architecture | flavour | available branches |
| --------------- | ------------------ | ------------------- | ------------------- |
2023-08-04 19:37:17 +00:00
| debian bookworm | amd64 | amd64 | develop, stable |
| debian bookworm | arm64 | arm64 | stable |
| ubuntu jammy | amd64 | amd64 | develop, stable |
| ubuntu jammy | arm64 | arm64 | develop, stable |
2023-07-20 16:45:53 +00:00
| alpine | amd64 | amd64-musl | stable |
| alpine | arm64 | arm64-musl | stable |
2022-07-28 10:36:51 +00:00
Other similar distributions will _probably_ work, but if it is not listed above, there is no official
support.
2019-06-21 02:48:13 +00:00
### Installing the required packages
2022-07-02 21:00:01 +00:00
Other than things bundled in the OTP release Akkoma depends on:
2019-12-09 17:09:47 +00:00
2019-06-21 02:48:13 +00:00
* curl (to download the release build)
* unzip (needed to unpack release builds)
* ncurses (ERTS won't run without it)
* PostgreSQL (also utilizes extensions in postgresql-contrib)
2019-06-21 16:59:56 +00:00
* nginx (could be swapped with another reverse proxy but this guide covers only it)
2019-06-21 02:48:13 +00:00
* certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it)
2020-05-14 19:36:31 +00:00
* libmagic/file
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
2021-06-11 06:46:38 +00:00
awk 'NR==2' /etc/apk/repositories | sed 's/main/community/' | tee -a /etc/apk/repositories
2020-08-15 06:49:12 +00:00
apk update
2020-09-10 21:02:11 +00:00
apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot file-dev
2020-08-15 06:49:12 +00:00
```
=== "Debian/Ubuntu"
```
2020-09-10 21:02:11 +00:00
apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot libmagic-dev
2020-08-15 06:49:12 +00:00
```
2019-12-09 17:09:47 +00:00
2020-09-26 16:32:16 +00:00
### Installing optional packages
2020-10-25 08:28:17 +00:00
Per [`docs/installation/optional/media_graphics_packages.md` ](optional/media_graphics_packages.md ):
2020-09-26 16:32:16 +00:00
* ImageMagick
* ffmpeg
* exiftool
=== "Alpine"
```
apk update
apk add imagemagick ffmpeg exiftool
```
=== "Debian/Ubuntu"
```
apt install imagemagick ffmpeg libimage-exiftool-perl
2020-08-15 06:49:12 +00:00
```
2019-12-09 17:09:47 +00:00
2019-06-21 02:48:13 +00:00
## Setup
### Configuring PostgreSQL
#### (Optional) Installing RUM indexes
2019-11-11 12:13:07 +00:00
!!! warning
It is recommended to use PostgreSQL v11 or newer. We have seen some minor issues with lower PostgreSQL versions.
2019-10-02 21:22:14 +00:00
RUM indexes are an alternative indexing scheme that is not included in PostgreSQL by default. You can read more about them on the [Configuration page ](../configuration/cheatsheet.md#rum-indexing-for-full-text-search ). They are completely optional and most of the time are not worth it, especially if you are running a single user instance (unless you absolutely need ordered search results).
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
apk add git build-base postgresql-dev
git clone https://github.com/postgrespro/rum /tmp/rum
cd /tmp/rum
make USE_PGXS=1
make USE_PGXS=1 install
cd
rm -r /tmp/rum
```
=== "Debian/Ubuntu"
```
# Available only on Buster/19.04
apt install postgresql-11-rum
```
2019-12-09 17:09:47 +00:00
2019-06-21 02:48:13 +00:00
#### (Optional) Performance configuration
2020-05-25 17:26:07 +00:00
It is encouraged to check [Optimizing your PostgreSQL performance ](../configuration/postgresql.md ) document, for tips on PostgreSQL tuning.
2019-06-21 02:48:13 +00:00
2021-01-19 11:15:55 +00:00
Restart PostgreSQL to apply configuration changes:
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
rc-service postgresql restart
```
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
systemctl restart postgresql
```
2019-12-09 17:09:47 +00:00
2022-07-02 21:00:01 +00:00
### Installing Akkoma
2019-06-21 02:48:13 +00:00
```sh
2022-07-02 21:00:01 +00:00
# Create a Akkoma user
adduser --system --shell /bin/false --home /opt/akkoma akkoma
2019-06-21 02:48:13 +00:00
2019-11-11 12:13:07 +00:00
# Set the flavour environment variable to the string you got in Detecting flavour section.
2023-07-31 13:56:39 +00:00
# For example if the flavour is `amd64-musl` the command will be
# export FLAVOUR="amd64-musl"
export FLAVOUR="< replace-this-with-the-correct-flavour-string > "
# Make sure the SHELL variable is set
export SHELL="${SHELL:-/bin/sh}"
2019-06-21 02:48:13 +00:00
# Clone the release build into a temporary directory and unpack it
2022-07-02 21:00:01 +00:00
su akkoma -s $SHELL -lc "
2022-11-09 13:22:44 +00:00
curl 'https://akkoma-updates.s3-website.fr-par.scw.cloud/stable/akkoma-$FLAVOUR.zip' -o /tmp/akkoma.zip
2022-07-02 21:00:01 +00:00
unzip /tmp/akkoma.zip -d /tmp/
2019-06-21 02:48:13 +00:00
"
# Move the release to the home directory and delete temporary files
2022-07-02 21:00:01 +00:00
su akkoma -s $SHELL -lc "
mv /tmp/release/* /opt/akkoma
2019-06-21 02:48:13 +00:00
rmdir /tmp/release
2022-07-02 21:00:01 +00:00
rm /tmp/akkoma.zip
2019-06-21 02:48:13 +00:00
"
# Create uploads directory and set proper permissions (skip if planning to use a remote uploader)
2022-07-02 21:00:01 +00:00
# Note: It does not have to be `/var/lib/akkoma/uploads`, the config generator will ask about the upload directory later
2019-06-21 02:48:13 +00:00
2022-07-02 21:00:01 +00:00
mkdir -p /var/lib/akkoma/uploads
chown -R akkoma /var/lib/akkoma
2019-06-21 02:48:13 +00:00
# Create custom public files directory (custom emojis, frontend bundle overrides, robots.txt, etc.)
2022-07-02 21:00:01 +00:00
# Note: It does not have to be `/var/lib/akkoma/static`, the config generator will ask about the custom public files directory later
mkdir -p /var/lib/akkoma/static
chown -R akkoma /var/lib/akkoma
2019-06-21 02:48:13 +00:00
# Create a config directory
2022-07-02 21:00:01 +00:00
mkdir -p /etc/akkoma
chown -R akkoma /etc/akkoma
2019-06-21 02:48:13 +00:00
# Run the config generator
2022-07-02 21:00:01 +00:00
su akkoma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/akkoma/config.exs --output-psql /tmp/setup_db.psql"
2019-06-21 02:48:13 +00:00
# Create the postgres database
2019-06-21 23:09:45 +00:00
su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"
2019-06-21 02:48:13 +00:00
# Create the database schema
2022-07-02 21:00:01 +00:00
su akkoma -s $SHELL -lc "./bin/pleroma_ctl migrate"
2019-06-21 02:48:13 +00:00
2019-06-21 23:20:55 +00:00
# If you have installed RUM indexes uncommend and run
2022-07-02 21:00:01 +00:00
# su akkoma -s $SHELL -lc "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/"
2019-06-21 03:22:34 +00:00
2019-06-21 02:48:13 +00:00
# Start the instance to verify that everything is working as expected
2022-07-02 21:00:01 +00:00
su akkoma -s $SHELL -lc "./bin/pleroma daemon"
2019-06-21 02:48:13 +00:00
# Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly
sleep 20 & & curl http://localhost:4000/api/v1/instance
# Stop the instance
2022-07-02 21:00:01 +00:00
su akkoma -s $SHELL -lc "./bin/pleroma stop"
2019-06-21 02:48:13 +00:00
```
### Setting up nginx and getting Let's Encrypt SSL certificaties
2019-12-09 17:09:47 +00:00
#### Get a Let's Encrypt certificate
2019-06-21 02:48:13 +00:00
```sh
certbot certonly --standalone --preferred-challenges http -d yourinstance.tld
2019-12-09 17:09:47 +00:00
```
2022-07-02 21:00:01 +00:00
#### Copy Akkoma nginx configuration to the nginx folder
2019-06-21 02:48:13 +00:00
2019-12-09 17:09:47 +00:00
The location of nginx configs is dependent on the distro
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
2023-08-12 21:59:30 +00:00
cp /opt/akkoma/installation/akkoma.nginx /etc/nginx/conf.d/akkoma.conf
2020-08-15 06:49:12 +00:00
```
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
2023-08-12 21:59:30 +00:00
cp /opt/akkoma/installation/akkoma.nginx /etc/nginx/sites-available/akkoma.conf
2022-07-02 21:00:01 +00:00
ln -s /etc/nginx/sites-available/akkoma.conf /etc/nginx/sites-enabled/akkoma.conf
2020-08-15 06:49:12 +00:00
```
2019-12-09 17:09:47 +00:00
2022-07-02 21:00:01 +00:00
If your distro does not have either of those you can append `include /etc/nginx/akkoma.conf` to the end of the http section in /etc/nginx/nginx.conf and
2019-12-09 17:09:47 +00:00
```sh
2023-08-12 21:59:30 +00:00
cp /opt/akkoma/installation/akkoma.nginx /etc/nginx/akkoma.conf
2019-12-09 17:09:47 +00:00
```
2019-06-21 02:48:13 +00:00
2019-12-09 17:09:47 +00:00
#### Edit the nginx config
```sh
# Replace example.tld with your (sub)domain
2019-06-22 10:40:37 +00:00
$EDITOR path-to-nginx-config
2019-06-21 02:48:13 +00:00
# Verify that the config is valid
nginx -t
2019-12-09 17:09:47 +00:00
```
#### Start nginx
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
rc-service nginx start
```
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
systemctl start nginx
```
2019-12-09 17:09:47 +00:00
2022-07-02 21:00:01 +00:00
At this point if you open your (sub)domain in a browser you should see a 502 error, that's because Akkoma is not started yet.
2019-06-21 02:48:13 +00:00
### Setting up a system service
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
# Copy the service into a proper directory
2022-07-02 21:00:01 +00:00
cp /opt/akkoma/installation/init.d/akkoma /etc/init.d/akkoma
2019-06-21 02:48:13 +00:00
2022-07-02 21:00:01 +00:00
# Start akkoma and enable it on boot
rc-service akkoma start
rc-update add akkoma
2020-08-15 06:49:12 +00:00
```
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
# Copy the service into a proper directory
2022-07-02 21:00:01 +00:00
cp /opt/akkoma/installation/akkoma.service /etc/systemd/system/akkoma.service
2019-12-09 17:09:47 +00:00
2022-07-02 21:00:01 +00:00
# Start akkoma and enable it on boot
systemctl start akkoma
systemctl enable akkoma
2020-08-15 06:49:12 +00:00
```
2019-12-09 17:09:47 +00:00
2022-07-02 21:00:01 +00:00
If everything worked, you should see Akkoma-FE when visiting your domain. If that didn't happen, try reviewing the installation steps, starting Akkoma in the foreground and seeing if there are any errrors.
2019-06-21 02:48:13 +00:00
2022-07-15 12:27:16 +00:00
{! support.include !}
2019-06-21 02:48:13 +00:00
## Post installation
2019-12-09 17:09:47 +00:00
### Setting up auto-renew of the Let's Encrypt certificate
2019-06-22 23:42:47 +00:00
```sh
# Create the directory for webroot challenges
mkdir -p /var/lib/letsencrypt
# Uncomment the webroot method
$EDITOR path-to-nginx-config
# Verify that the config is valid
nginx -t
```
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
# Restart nginx
rc-service nginx restart
2019-06-22 23:42:47 +00:00
2020-08-15 06:49:12 +00:00
# Start the cron daemon and make it start on boot
rc-service crond start
rc-update add crond
2019-06-22 23:42:47 +00:00
2020-08-15 06:49:12 +00:00
# Ensure the webroot menthod and post hook is working
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'rc-service nginx reload'
2019-06-22 23:42:47 +00:00
2020-08-15 06:49:12 +00:00
# Add it to the daily cron
echo '#!/bin/sh
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "rc-service nginx reload"
2022-07-02 21:00:01 +00:00
' > /etc/periodic/daily/renew-akkoma-cert
chmod +x /etc/periodic/daily/renew-akkoma-cert
2019-06-22 23:42:47 +00:00
2022-07-02 21:00:01 +00:00
# If everything worked the output should contain /etc/cron.daily/renew-akkoma-cert
2020-08-15 06:49:12 +00:00
run-parts --test /etc/periodic/daily
```
2019-06-23 00:05:02 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
# Restart nginx
systemctl restart nginx
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
# Ensure the webroot menthod and post hook is working
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'systemctl reload nginx'
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
# Add it to the daily cron
echo '#!/bin/sh
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
2022-07-02 21:00:01 +00:00
' > /etc/cron.daily/renew-akkoma-cert
chmod +x /etc/cron.daily/renew-akkoma-cert
2019-12-09 17:09:47 +00:00
2022-07-02 21:00:01 +00:00
# If everything worked the output should contain /etc/cron.daily/renew-akkoma-cert
2020-08-15 06:49:12 +00:00
run-parts --test /etc/cron.daily
```
2019-07-17 22:35:16 +00:00
## Create your first user and set as admin
```sh
2022-07-02 21:00:01 +00:00
cd /opt/akkoma
su akkoma -s $SHELL -lc "./bin/pleroma_ctl user new joeuser joeuser@sld.tld --admin"
2019-07-17 22:35:16 +00:00
```
This will create an account withe the username of 'joeuser' with the email address of joeuser@sld.tld, and set that user's account as an admin. This will result in a link that you can paste into the browser, which logs you in and enables you to set the password.
2022-08-30 09:56:33 +00:00
{! installation/frontends.include !}
2019-06-23 04:43:45 +00:00
## Further reading
2019-10-02 21:18:32 +00:00
2022-07-15 12:27:16 +00:00
{! installation/further_reading.include !}
2020-01-15 08:12:24 +00:00
2022-07-15 12:27:16 +00:00
{! support.include !}