Home Akkoma

Akkoma

A Huge Thanks To Teabag Ninja Whose Original Akkoma Tute Got Me Started

Original OTP Akkoma Docs – Should you be interested. These have errors in code below the vertical rectangle in which that code does work. I sometimes used the code (choose Debian) if you try it.

8 minutes

Installing Akkoma on your host

Before starting, have a read over https://docs.akkoma.dev/stable/installation/otp_en/ to familiarize yourself with the process. This guide is mostly a copy of that, with some adjustments for clarity. Hopefully. Be sure to watch for the “exit” user when there!

OTP releases are the closest that Elixer has to a binary release.

Prepare your system

This guide assumes a Debian 11 install on Linode, but should work the same for any install of Debian 11 on amd64. It works also on Linux Ubuntu 22.04 Jammy on a server with only 2 GB.

Ssh into your server and drop to root if not already with su - and enter the root password.

Update your server:

apt update

Bash

apt full-upgrade -y

Sh

Then install the packages we need for the installation and setup:

apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot libmagic-dev

Sh

Optional packages

There are optional packages for media/processing: https://docs.akkoma.dev/stable/installation/optional/media_graphics_packages/ I installed them all as it’s not much space, and I wasn’t sure which features I would be needing down the road. The base installation doesn’t need them, but if you want to strip geolocation from images then you’d need exiftool for example.

To install:

apt install imagemagick ffmpeg libimage-exiftool-perl

Sh

If you feel the urge to configure PosgresSQL you can do so here

I don’t bother, I run basically a single user instance, therefore I don’t have to learn. This is a basic guide to get an instance up. Don’t do crap here then complain to me that my guide screwed up your install. It didn’t: YOU DID.

The Installation

Create the Akkoma user

adduser --system --shell  /bin/false --home /opt/akkoma akkoma

Sh

Set the flavour environment variable to the string you got in Detecting flavour section. For example if the flavour is amd64 the command will be (which for our Linode, it is):

export FLAVOUR="amd64"

Sh

Clone the release build into a temporary directory and unpack it

su akkoma -s $SHELL -lc "
curl 'https://akkoma-updates.s3-website.fr-par.scw.cloud/stable/akkoma-$FLAVOUR.zip' -o /tmp/akkoma.zip
unzip /tmp/akkoma.zip -d /tmp/
"

Sh

Move the release to the home directory and delete temporary files

su akkoma -s $SHELL -lc "
mv /tmp/release/* /opt/akkoma
rmdir /tmp/release
rm /tmp/akkoma.zip
"

Sh

Create uploads directory and set proper permissions (skip if planning to use a remote uploader)

Note: It does not have to be /var/lib/akkoma/uploads, the config generator will ask about the upload directory later (I just did this though as I did not see a reason not to)

mkdir -p /var/lib/akkoma/uploads

Sh

chown -R akkoma /var/lib/akkoma

Sh

Create custom public files directory (custom emojis, frontend bundle overrides, robots.txt, etc.)

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

Sh

chown -R akkoma /var/lib/akkoma

Sh

Create a config directory

mkdir -p /etc/akkoma

Sh

chown -R akkoma /etc/akkoma

Sh

Run the config generator

su akkoma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/akkoma/config.exs --output-psql /tmp/setup_db.psql"

Sh

This will ask a bunch of questions to set up the instance, like instance name and domain name etc. Pressing enter to use the defaults where it makes sense isn’t a silly idea. 😉

Once that is done, create the postgres database

su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"

Sh

Create the database schema

su akkoma -s $SHELL -lc "./bin/pleroma_ctl migrate"

Sh

Start the instance to verify that everything is working as expected

su akkoma -s $SHELL -lc "./bin/pleroma daemon"

Sh

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

Sh

Stop the instance

su akkoma -s $SHELL -lc "./bin/pleroma stop"

Sh

Set up Let’s Encrypt SSL Certificates and nginx config

First, stop nginx so it won’t hijack the connection

systemctl stop nginx

Sh

Then you can run the standalone certbot challenge which stands up it’s own webserver. Replace yourinstance.tld with the domain you are using.

certbot certonly --standalone --preferred-challenges http -d yourinstance.tld

Sh

If you enabled ngingx again now you should see the default nginx landing page – but we’ll wait until we’ve edited the nginx config.

The official guide source path is incorrect for the nginx config, below has the correct one at time of writing:

cp /opt/akkoma/installation/akkoma.nginx /etc/nginx/sites-available/akkoma.conf

Sh

Then enable the config

ln -s /etc/nginx/sites-available/akkoma.conf /etc/nginx/sites-enabled/akkoma.conf

Sh

Edit the nginx config for your domain using nano

nano /etc/nginx/sites-available/akkoma.conf

Sh

Press Ctrl+\ to search, type in example.tld then press Enter, then enter your (sub)domain for your instance, and Enter again. It will prompt, pres A for all occurances of example.tld to be replaced with your (sub)domain Ctrl+X to exit, Y to save, Enter to confirm filename (which remains the same). Clear as mud? Good.

Verify that the config is valid:

nginx -t

Sh

Now that certbot has run and the config has been set up for your instance, you can start nginx again

systemctl start nginx

Sh

Set up the system service for Akkoma

Copy the supplied service file into the proper directory

cp /opt/akkoma/installation/akkoma.service /etc/systemd/system/akkoma.service

Sh

Start Akkoma and enable it on boot

systemctl start akkoma

Sh

systemctl enable akkoma

Sh

Install a Front-End!

If you go to your instance in the browser now, you should see a page saying Akkoma is installed but there is no FE. As we are on a small VPS, we want a lightweight one, and PleromaFE fits the bill:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl frontend install pleroma-fe --ref stable"

Sh

Unless you’re a command line wizard, you’ll probably want to install AdminFE also:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl frontend install admin-fe --ref stable"

Sh

Post Installation

We’re not done yet… but we’re so close, keep going!

Set up auto-renew of Let’s Encrypt certificate

Create the directory for webroot challenges

mkdir -p /var/lib/letsencrypt

Sh

Uncomment the webroot method in the nginx config (read the text inside akkoma.conf, it explains: remove the # from in front of those lines below the description)

nano /etc/nginx/sites-available/akkoma.conf

Sh

Then verify the config is still valid after your uncommenting that section:

nginx -t

Sh

If it isn’t, go work out what you did wrong and fix it 😉

Restart nginx to load with the changes

systemctl restart nginx

Sh

Do a dry run to confirm the webroot method and post hook is working

certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'systemctl reload nginx'

Sh

Add it to daily cron. Make sure you replace example.tld with the domain of your instance, or it won’t renew (don’t ask how I realised that)…

echo '#!/bin/sh
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
' > /etc/cron.daily/renew-akkoma-cert

Sh

chmod +x /etc/cron.daily/renew-akkoma-cert

Sh

If everything worked the output should contain /etc/cron.daily/renew-akkoma-cert run-parts –test /etc/cron.daily

Create your Admin User

Now we are getting to the fun stuff!

cd /opt/akkoma

Sh

The command:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl user new <nickname> <email> [option ...]"

Sh

    --name <name> - the user's display name
    --bio <bio> - the user's bio
    --password <password> - the user's password
    --moderator/--no-moderator - whether the user should be a moderator
    --admin/--no-admin - whether the user should be an admin
    -y, --assume-yes/--no-assume-yes - whether to assume yes to all questions

So as an example:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl user new joeuser joeuser@sld.tld --admin"

Sh

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 writen in the terminal that you can copy and paste into the browser, which logs you in and enables you to set the password. Once you have done that, you’re logged and it all works!

Just a last couple of things though… almost done. I promise.

Add email capability

You know, for email verification, or notices of reports etc. Now, this can probably all be added in AdminFE after the settings migration to DB… but I did it this way, so here we go.

I had an issue of this not actually working. I ended up asking some folks with more experience than me who looked at a screenshot of the email settings in ADminFE and told me to turn off STARTTLS.

And then it all just worked.

I will update this when I work out the way to make it work first time.

nano /etc/akkoma/config.exs

Sh

Paste in below the other entries:

config :pleroma, Pleroma.Emails.Mailer,
  enabled: true,
  adapter: Swoosh.Adapters.SMTP,
  relay: "smtp.emailprovider.com",
  username: "YOUR_USERNAME@emailprovider.com",
  password: "YOUR_SMTP_PASSWORD",
  port: 465,
  ssl: true,
  auth: :always

Sh

Send Test email:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl email test --to root@example.org"

Sh

Send confirmation emails to all unconfirmed user accounts:

su akkoma -s $SHELL -lc " ./bin/pleroma_ctl email resend_confirmation_emails"

Sh

see: https://docs.akkoma.dev/stable/configuration/cheatsheet/#email

Migrate settings to DB…

…to enable changing settings in AdminFE instead of command line or files like some freakn wizard.

su akkoma -s $SHELL -lc "./bin/pleroma_ctl config migrate_to_db"

Sh

see: https://docs.akkoma.dev/stable/administration/CLI_tasks/config/

Useful notes:

Adding relays

Can be done in AdminFE, but have left here as it may be useful. Perhaps. If you import follows exported from another account, you probably don’t need to add one.

Follow a relay:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl relay follow <relay_url>"

Sh

Unfollow a relay:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl relay unfollow <relay_url>"

Sh

List relay subscriptions:

su akkoma -s $SHELL -lc "./bin/pleroma_ctl relay list"

Sh

Static Directory

This is where you store themes, emoji etc, that don’t get overwritten during upgrades. as we are using the OTP version, it is: /var/lib/akkoma/static/

akkoma linux

1516 Words

2022-11-26 13:00

© 2023 abcro

Powered by WP Made with ❤ by abcro

Hits: 4

Comments are closed.

Close Search Window
↑