Akkoma on Ubuntu 24.04 on Azure User Guide

Overview

Akkoma is a lightweight, highly customisable open-source server for the fediverse: a self-hosted, federated microblogging platform that speaks ActivityPub, so your instance can interoperate with Mastodon, Pleroma and thousands of other servers. Akkoma is a community-maintained fork of Pleroma, written in Elixir on the Erlang/OTP runtime with PostgreSQL for storage, and it ships the pleroma-fe (web UI) and admin-fe (administration) front ends. The cloudimg image installs Akkoma from the official OTP release, binds the app to the loopback interface behind nginx, and generates every cryptographic secret plus the initial administrator account uniquely on the first boot of each VM. Backed by 24/7 cloudimg support.

What is included:

• Akkoma installed from the official OTP release (AGPL-3.0) - the release bundles the Erlang/OTP runtime and Elixir, so there is no source compile
• The akkoma service (the Phoenix app) bound to 127.0.0.1:4000 and PostgreSQL 16 bound to loopback, both under systemd, fronted by nginx on port 80 with an unauthenticated /healthz
• The pleroma-fe primary web UI and admin-fe administration dashboard installed into the static directory
• All per-VM secrets generated on first boot: secret_key_base, the signing and LiveView salts, the joken JWT signer and the web-push VAPID keypair - none are baked into the image
• A per-VM administrator account created on first boot and recorded in a root-only credentials file
• Open registration disabled by default (a locked-down appliance) and the Mastodon-compatible client API
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting size for evaluation; for a busy instance choose a larger size, since Akkoma runs the BEAM VM plus PostgreSQL. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web interface. The appliance serves the web UI over plain HTTP on port 80 on the VM's own IP as an evaluation placeholder; before you federate you set your own domain and a TLS certificate (see "Set your own domain").

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Akkoma by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size (Standard_B2s); under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name akkoma \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Then open the web port on the VM's NSG:

az vm open-port --resource-group <your-rg> --name akkoma --port 80 --priority 900

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

On first boot the image generates the per-VM secrets, sets the instance domain to the VM public IP, creates the administrator account and starts the stack. Confirm the services are active and that the app and database are bound to loopback only:

systemctl is-active postgresql nginx akkoma

sudo ss -tlnp | grep -E ':80 |:4000 |:5432 '

Step 5 - Check the health endpoints

The unauthenticated :80/healthz returns 200 for load-balancer probes, and the Mastodon-compatible /api/v1/instance returns your instance metadata:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/healthz

curl -s http://127.0.0.1/api/v1/instance | python3 -m json.tool | grep -E '"uri"|"title"|"version"|"registrations"'

Step 6 - Retrieve the per-VM administrator credentials

The administrator account and a strong password are generated on first boot and written to a root-only file. The secrets in /etc/akkoma/config.exs are unique to this VM and never leave it:

sudo cat /root/akkoma-credentials.txt

The file records the web URL, the administrator username, e-mail and password.

Step 7 - Sign in to the web interface

Browse to http://<vm-public-ip>/ and use the Log in panel on the left with the administrator username and password from the credentials file. After signing in you land on your home timeline with the compose box on the left.

Step 8 - Post to your timeline

Type a message in the compose box and select Post. Your status appears immediately in the home timeline - proof the full ActivityPub stack (Phoenix, PostgreSQL and the pleroma-fe front end) is working end to end.

Step 9 - Set your own domain (do this BEFORE federating)

This is the most important step. Akkoma bakes its instance domain into accounts, posts and federation identifiers at setup and cannot cleanly change it later. The appliance boots with the domain set to the VM IP over plain HTTP purely as an evaluation placeholder. Before you create real accounts or federate, set your own domain:

1. Point a DNS record (for example social.example.com) at the VM public IP.
2. Edit /etc/akkoma/config.exs and set the endpoint host, scheme and port, and the media base URL, to your domain:

config :pleroma, Pleroma.Web.Endpoint,
  url: [host: "social.example.com", scheme: "https", port: 443]

config :pleroma, Pleroma.Upload,
  base_url: "https://social.example.com/media"

1. Point the nginx server_name in /etc/nginx/sites-available/akkoma at your domain and install a real TLS certificate (for example with certbot --nginx), then reload nginx.
2. Restart Akkoma so the new configuration takes effect:

sudo systemctl restart akkoma nginx

Federation with the wider fediverse requires a real domain and a valid TLS certificate - a bare IP over HTTP is only suitable for evaluating the software.

Step 10 - Administration dashboard

The admin-fe dashboard manages users, statuses, reports, moderation, relays and instance settings. Open http://<vm-public-ip>/pleroma/admin/ and choose Log in via PleromaFE to authenticate with your existing session. The appliance ships no default credentials - every secret and the administrator account are generated uniquely per VM on first boot, and open registration is disabled by default.

Maintenance and production notes

• pleroma_ctl: manage the instance with /opt/akkoma/bin/pleroma_ctl (run as the akkoma user) - for example pleroma_ctl user new, pleroma_ctl user set, database migrations and frontend updates.
• Media and disk size: a real instance accumulates federated media under /var/lib/akkoma/uploads. Attach a larger disk or configure object storage for production, and back up the PostgreSQL akkoma database regularly.
• Updates: apply OS security updates with sudo apt update && sudo apt upgrade. Akkoma version upgrades follow the upstream release notes (pleroma_ctl update).
• Security: the appliance ships no default credentials - every secret and the administrator account are generated uniquely per VM on first boot. Keep /root/akkoma-credentials.txt protected and change the administrator password after first sign-in.

Akkoma is free software licensed under the AGPL-3.0. This image is produced by cloudimg and is not affiliated with, sponsored by, or endorsed by the Akkoma project.