Skip to main content

Installing Akkoma

This page makes the following assumptions:

  • You have a running VPS, prepared according to the instructions in Preparing Your VPS.
  • You have a domain name that's pointed to your VPS.

If either of these aren't true, please read through the last three pages.

We're now going to download, install, and configure Akkoma, as well as some dependencies and a few other services we'll need to make this work: specifically, Caddy and PostgreSQL.

PostgreSQL is used to store information, such as account details, user posts, and the like. Caddy is something called a "reverse proxy" - think of it like opening a portal from the outside world into a specific application within your VPS. Caddy also does some other heavy lifting for us, such as getting SSL certificates (which allow folks and other servers to securely connect to your instance).

We are doing this install from source. Installing from OTP as broken, as a necessary dependency has been removed from Ubuntu 24.04. This guide is based off of, and uses much of the same commands as, the upstream documentation: Installing on Debian Based Distributions

Installing Dependencies

We have a few things we need to install - namely, PostgreSQL, Caddy, and a handful of dependencies - some required to build and run Akkoma, and a few required to enable useful features:

sudo apt install git build-essential postgresql postgresql-contrib cmake libmagic-dev elixir erlang-dev erlang-nox imagemagick ffmpeg libimage-exiftool-perl caddy

Before we continue, let's create the Akkoma system user - we'll need it eventually, but we may need it very soon:

sudo useradd -r -s /bin/false -m -d /var/lib/akkoma -U akkoma

Run the following command, and ensure you have at least OTP 25 and Elixir 1.14:

elixir --version

If you at least meet those versions, skip directly to Tuning Postgres. If not, uninstall Elixir and Erlang, then proceed with the next section, Installing asdf:

sudo apt remove elixir erlang-dev erlang-nox
sudo apt autoremove
Installing Elixir and Erlang with asdf

asdf is an application that effectively manages versions of different applications available to a given project. We will be using it to install a recent version of Erlang and Elixir.

You're first going to need a few more dependencies:

sudo apt install -y curl unzip build-essential autoconf m4 libncurses5-dev libssh-dev unixodbc-dev xsltproc libxml2-utils libncurses-dev

Next, let's change to the akkoma user, then download asdf.

sudo su -l akkoma -s $SHELL
git clone https://github.com/asdf-vm/asdf.git /var/lib/akkoma/.asdf --branch v0.11.3

From now until Tuning Postgres, you will run all of these commands as the akkoma user.

Next, we'll add a few lines to the end of .bashrc, and then restart your akkoma shell.

cat <<EOT >> ~/.bashrc
. "$HOME/.asdf/asdf.sh"
# asdf completions
. "$HOME/.asdf/completions/asdf.bash"
EOT
exec $SHELL

Let's start compiling and installing Erlang, and then installing Elixir. Compiling Erlang will take a few moments!

asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
export KERL_CONFIGURE_OPTIONS="--disable-debug --without-javac"
asdf install erlang 25.3.2.5
asdf global erlang 25.3.2.5
asdf plugin-add elixir https://github.com/asdf-vm/asdf-elixir.git
asdf install elixir 1.15.4-otp-25
asdf global elixir 1.15.4-otp-25

Finally, check the elixir version once again, to make sure you now have the right version:

elixir --version

If it is indeed correct, go ahead and exit your akkoma shell back into root.

exit

Tuning Postgres

We're going to take a slight detour from the install documentation to tune PostgreSQL a little bit. This will help tweak the performance to work better with our kind of setup - including the fact we are on an SSD and can use SSD speeds.

The following tune was created using PGTune, and was created assuming a VPS with 4 GB of memory and 2 CPU cores (and I told the tune to only use 3 GB of memory.) If your specs are different, you may want to create your own tune. If you create your own tune, I also selected "Web Application" for database type, 100 max connections, and SSD storage.

Open postgresql.conf in nano:

sudo nano /etc/postgresql/16/main/postgresql.conf

Find the following settings in the file, and change them to read the following (including un-commenting them if they're commented out):

max_connections = 20
shared_buffers = 768MB
effective_cache_size = 2304MB
maintenance_work_mem = 192MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 19660kB
huge_pages = off
min_wal_size = 1GB
max_wal_size = 4GB

You can press Ctrl+W in Nano to run a search.

Then, enable and restart postgresql:

sudo systemctl enable postgresql
sudo systemctl restart postgresql

Installing and Configuring Akkoma

Make the directory Akkoma's gonna live in, then clone the stable version of the Website League fork:

sudo mkdir -p /opt/akkoma
sudo chown -R akkoma:akkoma /opt/akkoma
sudo -Hu akkoma git clone https://akkoma.dev/srxl/akkoma.git -b wl-stable /opt/akkoma

Switch to a shell as the Akkoma user, go into the Akkoma directory, and install dependencies.

sudo su -l akkoma -s $SHELL
cd /opt/akkoma
mix deps.get

If it asks you to install Hex, answer Yes.

From now until further notice, you will be running these commands as the akkoma user. If you didn't need to use asdf, you may be able to run these using sudo -Hu akkoma instead. (The author of this guide ran into problems trying to use sudo with asdf.)

Run this command to begin configuring your instance (after it compiles a bunch of dependencies):

MIX_ENV=prod mix pleroma.instance gen

Consider the following during configuration:

  • Use the domain you set the A and AAAA records earlier for as your instance domain.
  • Use the domain you set the CNAME record earlier for as part of your base URL:
    • https://media.awesome.instance/media
  • Storing your configuration in the database will allow you to edit your configuration using a web frontend, and many settings won't require an instance restart this way. However, anything you've configured in the database will override what's in your config file, which may be confusing. In contrast, not storing your config in the database means your config file will always be perfectly accurate to how your instance is set up, but any changes (including adding an instance to the allowlist) will require editing the file and restarting the instance.
Back to top