Migrate the Docker-deployed Umami From One Server to Another.

Introduction

Nearly, I bought a new ARM server from netcup GmbH, and I need to migrate my umami server from the old server to the new one. But I installed umami with Docker.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: replace-me-with-a-random-string
    depends_on:
      db:
        condition: service_healthy
    restart: always
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

The most difficult and important part is exporting data in umami. To do that, we have several methods:

• Export the Docker volume (Very complex)
• Export the database (My choice)
• Copy the whole path (Not recommend)

Compare Methods

First, we need to know that umami’s data is in the volume. Since docker-compose.yml specify that:

1
2
3
4
5
6

services:
  db:
    volumes:
      - umami-db-data:/var/lib/postgresql/data
volumes:
  umami-db-data:

If I mounted a path into the container instead of a volume, I can simply copy the path to my new machine. For example,

1
2
3
4

services:
  db:
    volumes:
      - /root/umami/data:/var/lib/postgresql/data

Sadly I used a volume and made things complex. How to migrated Docker volume (in a right way) is welled discussed over the internet. For example, Move a Docker volume to another host. This is too complex for me. You may ask, the Docker volumes are stored in a fixed path like /var/lib/docker/volumes/*. Why not just copy the folder to another machine and start as normal? Well, this is applicable and I have done this before. But it may cause some potential issues, especially for different Docker container version.

Finally, I choice to just export the database and import to the new instance. Let’s do it step by step.

Migrate Database

FIrst, let’s attach to the old container.

1

docker exec -it umami-db-1 /bin/sh

Export the database as a .sql file.

1
2

cd /
pg_dump --username=umami umami > umami.sql

Now the database is in umami.sql, but it’s inside the container, so press Ctrl + D to disconnect from the container shell. Then, copy the file into host machine.

1

docker cp umami-db-1:/umami.sql /root

Then, you need transfer this backup file to your new host machine. After you docker compose up -d the umami-db-1 container will be created. Then, you can copy the database backup file into the container by:

1

docker cp /root/umami.sql umami-db-1:/

Then, we can attach to the umami-db-1 by:

1

docker exec -it umami-db-1 /bin/sh

To import the backup into the PostgreSQL, we need login psql as umami:

1

psql --username=umami -d postgres

In psql shell, we will drop the original database and create a blank one for preparing import.

1
2

DROP DATABASE umami;
CREATE DATABASE umami;

Then, quit psql shell and run:

1
2

cd /
psql --username=umami -f umami.sql umami

to import backup file. Finally, restart the umami instance:

1
2
3

cd /path/to/umami/docker-compose.yaml/
docker compose down
docker compose up -d

Check

Now, you may have a check to see the database is migrated or not. Open the URL of your new umami location and try to login with your original credentials. If you can login, the database is very likely migrated (credentials is stored in database).

To further confirm, you can go to the dashboard and check if all data is displaying properly.

If not, which mean the database didn’t migrated successfully. You may check the exported backup file (does it contain the right data?) and the way you import (see if the backup file is successfully imported to the new PostgreSQL).

Reference

• How To Migrate Umami From One Server To Another
• How to Backup and Restore a PostgreSQL Database in Linux