Skip to content

Migrating to a Docker Installation

If you for any reason wish to migrate a source or OTP install to a docker one, this guide is for you.

You have a few options - your major one will be whether you want to keep your reverse-proxy setup from before.

You probably should, in the first instance.

Prepare the system

  • Install docker and docker compose
    • Docker
    • Docker-compose
    • This will usually just be a repository installation and a package manager invocation.
git pull

Clone the akkoma repository

git clone -b stable
cd akkoma

Back up your old database

Change the database name as needed

pg_dump -d akkoma_prod --format c > akkoma_backup.sql

Getting your static files in the right place

This will vary by every installation. Copy your instance directory to instance/ in the akkoma source directory - this is where the docker container will look for it.

For most from-source installs it'll already be there.

And the same with uploads, make sure your uploads (if you have them on disk) are located at uploads/ in the akkoma source directory.

If you have them on a different disk, you will need to mount that disk into the docker compose file, with an entry that looks like this:

  - .:/opt/akkoma # This should already be there
  - type: bind
    source: /path/to/your/uploads
    target: /opt/akkoma/uploads

Set up basic configuration

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

This probably won't need to be changed, it's only there to set basic environment variables for the docker compose file.

You probably won't need to change your config. Provided your config/prod.secret.exs file is still there, you're all good.

cp /etc/akkoma/config.exs config/prod.secret.exs


Set the following config in config/prod.secret.exs:

config :pleroma, Pleroma.Web.Endpoint,
   http: [ip: {0, 0, 0, 0}, port: 4000]

config :pleroma, Pleroma.Repo,
  username: "akkoma",
  password: "akkoma",
  database: "akkoma",
  hostname: "db"

Building the container

The container provided is a thin wrapper around akkoma's dependencies, it does not contain the code itself. This is to allow for easy updates and debugging if required.


This will generate a container called akkoma which we can use in our compose environment.

Setting up the docker resources

# These won't exist if you're migrating from OTP
rm -rf deps
rm -rf _build
mkdir pgdata
./docker-resources/ mix deps.get
./docker-resources/ mix compile

Setting up the database

Now we can import our database to the container.

docker compose run --rm --user akkoma -d db 
docker compose run --rm akkoma pg_restore -v -U akkoma -j $(grep -c ^processor /proc/cpuinfo) -d akkoma -h db akkoma_backup.sql

Reverse proxies

If you're just reusing your old proxy, you may have to uncomment the line in the docker compose file under ports. You'll find it.

Otherwise, you can use the same setup as the docker installation guide.

Let's go

docker compose up -d

You should now be at the same point as you were before, but with a docker install.

Installing Frontends

Once your backend server is functional, you'll also want to probably install frontends.

These are no longer bundled with the distribution and need an extra command to install.

For most installations, the following will suffice:

./bin/pleroma_ctl frontend install pleroma-fe --ref stable
# and also, if desired
./bin/pleroma_ctl frontend install admin-fe --ref stable
mix pleroma.frontend install pleroma-fe --ref stable
mix pleroma.frontend install admin-fe --ref stable
./docker-resources/ mix pleroma.frontend install pleroma-fe --ref stable
./docker-resources/ mix pleroma.frontend install admin-fe --ref stable

For more customised installations, refer to Frontend Management

See the docker installation guide for more information on how to update.

Further reading


If you encounter any issues or have questions regarding the install process, feel free to ask at

Or message via IRC on #akkoma at (port 6697, SSL)