Introduction

This article explains the procedure for migrating an Omeka-S environment set up with Docker Compose, including volume data, to a different server. You can proceed with the migration safely while maintaining data integrity.

Environment

  • Source server: Ubuntu 22.04
  • Target server: Ubuntu 22.04 (fresh setup)
  • Stack: Omeka-S + MariaDB + phpMyAdmin + Traefik + Mailpit

Migration Flow

  1. Backup on the source server
  2. Download to local machine
  3. Set up Docker environment on the target server
  4. Restore data and start up

Step 1: Backup on the Source Server

1.1 Check Current Environment

# Check running containers
docker ps

# Check Docker volumes
docker volume ls

Example output:

DRIVER    VOLUME NAME
local     omeka-s-docker_mariadb
local     omeka-s-docker_omeka

1.2 Create Backup Files

# Move to /opt directory
cd /opt

# Backup configuration files etc. (approx. 60MB)
sudo tar -czf omeka-backup-$(date +%Y%m%d).tar.gz omeka-s-docker/

# Backup Docker volume data (approx. 1GB)
sudo docker run --rm \
  -v omeka-s-docker_omeka:/data/omeka \
  -v omeka-s-docker_mariadb:/data/mariadb \
  -v /opt:/backup \
  alpine tar -czf /backup/omeka-volumes-$(date +%Y%m%d).tar.gz -C /data .

# Verify backup files
ls -lh /opt/*.tar.gz

Example output:

-rw-r--r-- 1 root root  59M Oct 16 17:02 /opt/omeka-backup-20251016.tar.gz
-rw-r--r-- 1 root root 1.1G Oct 16 17:04 /opt/omeka-volumes-20251016.tar.gz

1.3 Change Backup File Permissions

Change ownership to the current user for downloading:

sudo chown $USER:$USER /opt/omeka-backup-20251016.tar.gz
sudo chown $USER:$USER /opt/omeka-volumes-20251016.tar.gz

Step 2: Download to Local Machine

Run on your local machine’s terminal:

# Move to download directory
cd ~/Downloads

# Download files via SCP
scp user@source-server-ip:/opt/omeka-backup-20251016.tar.gz ./
scp user@source-server-ip:/opt/omeka-volumes-20251016.tar.gz ./

# Verify download
ls -lh omeka-*.tar.gz

Note: The 1.1GB file will take some time to download.

Step 3: Set Up the Target Server

3.1 Update the System

sudo apt update
sudo apt upgrade -y

3.2 Remove Existing Docker Packages (Clean Install)

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
  sudo apt-get remove $pkg
done

3.3 Add Docker’s Official Repository

# Add GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

3.4 Install Docker Engine

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.5 Verify Installation

# Test run as root
sudo docker run hello-world

3.6 Configure Docker Execution Permissions for Regular Users

# Create docker group (error is OK if it already exists)
sudo groupadd docker

# Add current user to docker group
sudo usermod -aG docker $USER

# Apply group changes
newgrp docker

# Test run as regular user
docker run hello-world

Step 4: Transfer and Restore Data

4.1 Upload Backup Files

Run from your local machine:

# Upload to target server
scp omeka-backup-20251016.tar.gz user@target-server-ip:/tmp/
scp omeka-volumes-20251016.tar.gz user@target-server-ip:/tmp/

4.2 Extract on the Target Server

# Move to /opt directory
cd /opt

# Move backup files
sudo mv /tmp/omeka-backup-20251016.tar.gz /opt/
sudo mv /tmp/omeka-volumes-20251016.tar.gz /opt/

# Extract configuration files
sudo tar -xzf omeka-backup-20251016.tar.gz

# Change ownership
sudo chown -R $USER:$USER omeka-s-docker

# Move to project directory
cd omeka-s-docker

4.3 Restore Docker Volumes

First, create containers (without starting them) to prepare the volumes:

# If using docker-compose.yml
docker compose up --no-start

# If using specific compose file and env file
docker compose -f docker-compose-omeka-traefik.yml --env-file .env.omeka up --no-start

Next, restore data from the backup into the volumes:

docker run --rm \
  -v omeka-s-docker_omeka:/data/omeka \
  -v omeka-s-docker_mariadb:/data/mariadb \
  -v /opt:/backup \
  alpine tar -xzf /backup/omeka-volumes-20251016.tar.gz -C /data

What this command does:

  • -v omeka-s-docker_omeka:/data/omeka: Mount the Omeka volume
  • -v omeka-s-docker_mariadb:/data/mariadb: Mount the MariaDB volume
  • -v /opt:/backup: Mount the directory containing the backup file
  • alpine tar -xzf ...: Run the tar command in an Alpine Linux image to extract the data

4.4 Verify Volumes

docker volume ls

Example output:

DRIVER    VOLUME NAME
local     omeka-s-docker_mariadb
local     omeka-s-docker_omeka

Step 5: Start the Containers

5.1 Check Environment Variables

Before starting, check and configure the .env file (or .env.omeka, etc.):

# Edit .env file
nano .env.omeka

Minimum required settings:

OMEKA_HOST=your-domain.com  # or localhost
# Other environment variables...

5.2 Start the Containers

# If using the standard docker-compose.yml
docker compose up -d

# If using specific compose file and env file
docker compose -f docker-compose-omeka-traefik.yml --env-file .env.omeka up -d

5.3 Verify Startup

# Check container status
docker ps

# Check logs
docker compose logs -f

# Check logs for specific services
docker compose logs -f omeka
docker compose logs -f mariadb

Troubleshooting

Issue 1: Empty Hostname Error in Traefik

Error message:

error="error while adding rule Host(``): error while checking rule Host: empty args for matcher Host, []"

Solution: Check that OMEKA_HOST is set in the .env file.

# Check .env file
cat .env.omeka

# If OMEKA_HOST is not set, add it
echo "OMEKA_HOST=localhost" >> .env.omeka

# Restart
docker compose down
docker compose up -d

Issue 2: Database Connection Error

MariaDB may take some time to start. Check the following:

# Check MariaDB logs
docker compose logs mariadb

# Wait until you see the "ready for connections" message

Issue 3: Permission Error

# Check file ownership
ls -la /opt/omeka-s-docker

# Change ownership if necessary
sudo chown -R $USER:$USER /opt/omeka-s-docker

Security Considerations

Automated Scanning on Public Servers

Once a server is made public, automated scan bots will immediately attempt to access it. It is normal to see access logs like the following:

POST /graphql HTTP/1.1" 404
GET /.env HTTP/1.1" 404
GET /swagger-ui.html HTTP/1.1" 404

These are bots searching for vulnerabilities. As long as they all result in 404 (not found) or 403 (access denied), there is no issue.

  1. Firewall configuration
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable
  1. Install Fail2ban
sudo apt install fail2ban
  1. Regular updates
sudo apt update && sudo apt upgrade -y

Convenient Alias Configuration

When using specific compose files and environment variable files, setting up aliases is convenient:

# Add to ~/.bashrc
echo "alias omeka-compose='docker compose -f docker-compose-omeka-traefik.yml --env-file .env.omeka'" >> ~/.bashrc
source ~/.bashrc

# Usage examples
omeka-compose up -d
omeka-compose down
omeka-compose logs -f

Summary

With this procedure, you can safely migrate a Docker-based Omeka-S environment. Key points:

  1. Create two backups: One for configuration files and one for volume data
  2. Create containers before restoring volumes: Use up --no-start to prepare volumes
  3. Check environment variable files: Especially the hostname setting
  4. Security measures: Essential for public servers

This procedure can also be applied to migrating other Docker Compose environments.

Reference Information

Last updated: October 2025