How to Self-Host Akkoma with Docker Compose

What Is Akkoma?

Akkoma started as a community fork of Pleroma in late 2022, created by contributors who wanted faster development and better maintenance than the original project could provide. It’s a lightweight Fediverse microblogging platform written in Elixir that runs on a fraction of Mastodon’s resources — a single-user instance works on 200 MB of RAM. Akkoma supports ActivityPub federation, meaning users can interact with accounts on Mastodon, GoToSocial, Misskey, Pixelfed, Lemmy, and other Fediverse platforms.

Updated February 2026: Verified with latest Docker images and configurations.

As of v3.17.0 (December 2025), Akkoma has diverged significantly from Pleroma with improved Mastodon API compatibility, enhanced MRF (Message Rewrite Facility) policies, bubble timelines, Soapbox frontend support, and a quarterly release cadence with security patches.

Quick Verdict

Akkoma is the best lightweight Fediverse microblogging option for new deployments. It uses 5-10x less RAM than Mastodon while providing 90% of the features. If you want a personal or small-community Fediverse presence without dedicating 4+ GB of RAM to Mastodon, Akkoma is the right choice. The trade-off: fewer native mobile apps (though Mastodon clients work well) and a smaller ecosystem.

Spec	Value
Latest version	v3.17.0 (December 2025)
Backend	Elixir/OTP (BEAM VM)
Database	PostgreSQL
Default port	4000
RAM (single user)	200-400 MB
RAM (small instance)	500 MB - 1 GB
Federation	ActivityPub
License	AGPL-3.0
Official site	akkoma.dev

Use Cases

• Personal Fediverse presence — run your own microblogging instance for yourself and a few friends
• Small community — host a focused community (10-50 users) without Mastodon’s resource overhead
• Pleroma migration — replace a stalled Pleroma instance with actively maintained software
• Fediverse experimentation — explore the Fediverse with minimal infrastructure commitment

Prerequisites

• A Linux server (Ubuntu 22.04+ or Debian 12+ recommended)
• Docker and Docker Compose installed (guide)
• 1 GB RAM minimum (2 GB recommended for small communities)
• 10 GB disk space minimum
• A domain name pointed at your server
• A reverse proxy with SSL configured (guide)

Docker Compose Configuration

Akkoma’s official Docker setup uses a build-from-source approach. Clone the repository and build the image:

git clone https://akkoma.dev/AkkomaGang/akkoma.git
cd akkoma
git checkout v3.17.0

Build the Docker image:

./docker-resources/build.sh

Set up the environment:

cp docker-resources/env.example .env
echo "DOCKER_USER=$(id -u):$(id -g)" >> .env

The docker-compose.yml in the repository provides the base configuration. Here’s the complete setup:

services:
  akkoma:
    build: .
    user: "${DOCKER_USER}"
    volumes:
      - ./config:/opt/akkoma/config
      - ./uploads:/opt/akkoma/uploads
      - ./static:/opt/akkoma/instance/static
    ports:
      - "4000:4000"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: akkoma
      POSTGRES_PASSWORD: CHANGE_ME_STRONG_PASSWORD
      POSTGRES_DB: akkoma
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U akkoma"]
      interval: 10s
      timeout: 5s
      retries: 5
    shm_size: 256mb
    restart: unless-stopped

volumes:
  pgdata:

Generate the initial configuration:

docker compose run --rm akkoma bin/pleroma_ctl instance gen \
  --output config/prod.secret.exs \
  --output-psql config/setup_db.sql

This interactive wizard prompts for your domain, instance name, admin email, and database credentials. Set the database host to db (the Docker service name) and use the password matching POSTGRES_DB in your compose file.

Initialize the database:

docker compose run --rm akkoma bin/pleroma_ctl migrate

Start the stack:

docker compose up -d

Initial Setup

Create an admin account:

docker compose exec akkoma bin/pleroma_ctl user new admin [email protected] --admin

This outputs a password reset URL. Open it in your browser to set the admin password.

Access the web UI at http://your-server:4000. You’ll see the Pleroma-FE frontend by default. Log in with your admin account.

Instance Settings

Navigate to Admin → Settings to configure:

• Instance name and description — what appears in the Fediverse
• Registration — open, invite-only, or closed
• Upload limits — default 15 MB, increase if needed
• MRF policies — content filtering rules (see Advanced Configuration)
• Federation — which instances to block or restrict

Configuration

Akkoma’s configuration lives in config/prod.secret.exs (Elixir syntax). Key settings:

# Instance identity (CANNOT be changed after federation begins)
config :pleroma, :instance,
  name: "My Akkoma Instance",
  email: "[email protected]",
  description: "A cozy Fediverse corner",
  limit: 5000,                    # Character limit per post
  registrations_open: false,       # Closed by default
  invites_enabled: true           # Allow invite links

# Media upload configuration
config :pleroma, Pleroma.Upload,
  uploader: Pleroma.Uploaders.Local,
  base_url: "https://social.example.com/media"

# Email (required for account verification, password reset)
config :pleroma, Pleroma.Emails.Mailer,
  adapter: Swoosh.Adapters.SMTP,
  relay: "mail.example.com",
  port: 587,
  username: "[email protected]",
  password: "SMTP_PASSWORD",
  tls: :always

After changing configuration, restart:

docker compose restart akkoma

Advanced Configuration

MRF (Message Rewrite Facility)

MRF intercepts incoming and outgoing ActivityPub messages for filtering. Common policies:

# Block specific instances
config :pleroma, :mrf_simple,
  reject: ["spam-instance.example", "another-bad.example"],
  media_removal: ["media-heavy.example"]

# Enforce content warnings on posts from certain instances
config :pleroma, :mrf_keyword,
  reject: ["spam phrase"],
  replace: [{"badword", "****"}]

Bubble Timeline

Akkoma’s bubble timeline shows posts from a curated list of friendly instances — between your local timeline and the full federated timeline:

config :pleroma, :instance,
  bubble_instances: ["friend1.example", "friend2.example"]

Frontend Selection

Akkoma supports multiple frontends. Switch from the default Pleroma-FE to Soapbox (Twitter-like UI):

docker compose exec akkoma bin/pleroma_ctl frontend install soapbox --ref main

Set it as default in the admin panel or config:

config :pleroma, :frontends,
  primary: %{"name" => "soapbox", "ref" => "main"}

Reverse Proxy

Akkoma runs on port 4000 internally. Configure your reverse proxy to handle TLS and forward traffic.

Nginx configuration:

server {
    listen 443 ssl http2;
    server_name social.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support for streaming
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        client_max_body_size 16m;
    }
}

For Nginx Proxy Manager or Caddy, see the Reverse Proxy Setup guide.

Backup

Back up these three components:

1. PostgreSQL database:

docker compose exec db pg_dump -U akkoma akkoma > akkoma_backup_$(date +%F).sql

2. Uploaded media:

tar czf akkoma_uploads_$(date +%F).tar.gz uploads/

3. Configuration:

cp -r config/ config_backup_$(date +%F)/

Restore the database:

cat akkoma_backup_2026-03-06.sql | docker compose exec -T db psql -U akkoma akkoma

For automated backups, see the Backup Strategy guide.

Troubleshooting

Federation not working — posts don’t reach other instances

Symptom: Posts publish locally but never appear on Mastodon or other instances. Fix: Verify your reverse proxy forwards the Host header correctly and that /.well-known/webfinger is accessible from the public internet. Test: curl https://social.example.com/.well-known/webfinger?resource=acct:[email protected]. If this returns an error, your reverse proxy configuration needs adjustment.

Database connection refused on startup

Symptom: (DBConnection.ConnectionError) connection refused Fix: Ensure PostgreSQL is healthy before Akkoma starts. The compose file should include condition: service_healthy on the depends_on for the db service. Also verify the database host in prod.secret.exs matches the Docker service name (db, not localhost).

High memory usage after running for weeks

Symptom: Akkoma process gradually consumes more RAM over time. Fix: The BEAM VM can hold memory longer than expected due to its garbage collector. Restart the container weekly if this is a problem: docker compose restart akkoma. Also clean old remote media: docker compose exec akkoma bin/pleroma_ctl media prune --days 30.

Mastodon clients can’t log in

Symptom: Apps like Tusky or Ice Cubes fail to authenticate. Fix: Ensure PLEROMA_URL or base_url in config matches your public URL exactly (including https://). Some clients are strict about URL matching. Also check that your reverse proxy isn’t stripping the Authorization header.

Resource Requirements

Scenario	RAM	CPU	Disk
Single user	200-400 MB	1 core	5 GB
Small instance (10-50 users)	500 MB - 1 GB	2 cores	10-20 GB
Medium instance (50-200 users)	1-2 GB	2-4 cores	20-50 GB

PostgreSQL adds 100-300 MB depending on data size. Total stack footprint for a small instance: ~700 MB - 1.3 GB — roughly 3-4x less than an equivalent Mastodon deployment.

Verdict

Akkoma is the best option for self-hosters who want a Fediverse presence without Mastodon’s resource demands. The Elixir/OTP stack is rock-solid, the 200 MB single-user footprint means it fits alongside other services on a small VPS, and quarterly releases with security patches mean you’re running maintained software.

The build-from-source Docker approach is less convenient than pulling a pre-built image, but it gives you version control and reproducibility. If that bothers you, GoToSocial is even lighter and has pre-built images — but it lacks Akkoma’s richer feature set (bubble timelines, MRF, multiple frontends, custom reactions).

For single-user or small community instances, Akkoma hits the sweet spot between features and resource efficiency.

FAQ

Can I migrate from Pleroma to Akkoma?

Yes. Akkoma shares Pleroma’s database schema. The migration involves updating the code, running database migrations, and adjusting config file references. Full guide at docs.akkoma.dev/stable/administration/migrating_from_pleroma/.

Which Mastodon apps work with Akkoma?

Most of them: Tusky (Android), Megalodon (Android), Ice Cubes (iOS), Ivory (iOS), Moshidon (Android). Some Akkoma-specific features (emoji reactions, bubble timeline) may not be accessible through Mastodon clients — use the web UI or Soapbox for full feature access.

How does Akkoma compare to GoToSocial?

GoToSocial is even lighter (50-100 MB RAM) but has a smaller feature set — no web UI (headless, clients only), no MRF, no frontend choices, less mature federation. Akkoma offers more features at a moderate resource cost. See our Mastodon vs GoToSocial comparison for more on the lightweight Fediverse server landscape.

Is Akkoma production-ready?

Yes. Akkoma is used by numerous instances serving hundreds of users. The quarterly release cycle with security patches demonstrates active maintenance. The codebase inherits years of production testing from Pleroma.

Related

• Akkoma vs Pleroma
• Mastodon vs Pleroma
• Mastodon vs GoToSocial
• Misskey vs Mastodon
• Self-Hosted Alternatives to Twitter
• Best Self-Hosted Social Networks
• Best Fediverse Software to Self-Host
• Fediverse and ActivityPub Explained
• Docker Compose Basics