Migrating from a regular Linux host to a Docker host: insanely difficult, or did I do it the hard way?

General
,
1

This past week I migrated a relatively mature Checkmk site from a regular Linux host under Ubuntu 22.04 to a new, more powerful virtualization server hosting about a dozen Docker containers, including Checkmk.

Standing up the Docker container was far more complex than I thought it would by, by far!

I’m not all that new to Docker or Docker Compose. I’m running under the Arcane management UI and, among other containers, I already have UNMS, Unifi Controller, Technitium, NTFY, httpd, and NPM up, running, configured and in production. None of them took more than an hour or so to configure, run, test, and fix a few mistakes. In stark contrast, it took me probably a dozen hours or so, spread out over a few days, to get my site migrated over to Checkmk under Docker.

To be fair, standing up a brand new Checkmk container was easy. Maybe 30 minutes, if that. But getting it to use the site backup from the old Linux machine was just crazy difficult!

After the quite normal steps of running OMD on the old machine to create a backup, and then moving that file to the persistent Docker volume on the Docker machine, things became “interesting”. In the hope of helping someone else down the road, here is what I did, for better or worse:

- Bring up the from-scratch Checkmk Raw container, which causes an empty site
  called "cmk" to be created.

     I also added into the compose file an extra tmpfs entry for the soon to
     be created new site.

- Shell into the Checkmk container and use OMD to

     Stop the cmk site
     Change the cmk site ports to something non-standard
     Disable the cmk site
     Restore the migrated site
     Copy the "special" cmk_docker.conf apache conf file from the cmk site to the new site 

        The new site doesn't have that file. I could not get the website to function without
        it and this single issue caused me many hours of debugging and research.
        That file is apparently only for Docker instances and the migrated site was coming
        from a regular instance of Ubuntu, not a Docker instance.

      Use OMD config to change the internal OMD site IP from [127.0.0.1] (appropriate
      for the regular Ubuntu environment) to [0.0.0.0] (for the Docker evironment.

- Stop the container, change the site name in the compose file from cmk to the migrated
  site name, then start the container and start the migrated site.

As far as I can see, these steps to migrate from a regular instance to a Docker instance are nowhere to be found on Checkmk web site. And it ought to be easier. Maybe it is. Maybe there are some environment variables I could have used to point the container at the site backup file and it would have automagically restored it and fixed the Apache configuration.

At any rate, I hope this helps someone in the future. If I did do it the hard way, please let me know!

2 Likes
Problems starting apache2 in Docker container
2

Hi,

You didn’t do it the hard way by mistake — you hit a real documentation gap. @martin.hirschvogel

Your approach was essentially correct, but there is a cleaner path that avoids most of the pain, particularly the cmk_docker.conf issue that cost you the most time.

The Core Problem

When you restore a backup from a native Linux installation into a Docker container, the Docker-specific Apache configuration file cmk_docker.conf is missing. This file tells Apache to listen on 0.0.0.0 instead of 127.0.0.1, which is required for the web interface to be reachable from outside the container. This is nowhere documented in the official Checkmk docs for this migration path — so your hours of debugging were not your fault.

The Cleaner Migration Path

Step 1 — Backup on the old Linux host

bash

omd stop mysite
omd backup /tmp/mysite_backup.tar.gz
scp /tmp/mysite_backup.tar.gz newserver:/opt/cmk-data/

Step 2 — Start the container with the correct Site ID from the beginning

You can set the site ID directly using the -e CMK_SITE_ID=mysite environment variable Checkmk — this avoids the whole rename/disable dance with the default cmk site entirely.

docker-compose.yml 
# docker-compose.yml
version: "3.7"
services:
  checkmk:
    image: checkmk/check-mk-raw:2.4.0-latest
    container_name: monitoring
    restart: always
    environment:
      CMK_SITE_ID: "mysite"       # must match your backup's site name!
      CMK_PASSWORD: "changeme"
      TZ: "Europe/Berlin"
    ports:
      - "8080:5000"
      - "8000:8000"
    volumes:
      - /opt/cmk-data:/omd/sites
      - /etc/localtime:/etc/localtime:ro
    tmpfs:
      - /opt/omd/sites/mysite/tmp:uid=1000,gid=1000

Step 3 — Restore inside the container

bash

# Shell into the container
docker exec -it monitoring bash

# Stop the freshly created empty site
omd stop mysite

# Restore from backup (--reuse overwrites the existing empty site)
omd restore --reuse --kill /omd/sites/mysite_backup.tar.gz

Step 4 — Fix the missing Docker Apache config

This is the step that cost you the most time. After restoring a native Linux backup, you need to either copy or recreate the Docker-specific Apache config:

bash

# Option A: copy from the default cmk site if it still exists
cp /omd/sites/cmk/etc/apache/conf.d/cmk_docker.conf \
   /omd/sites/mysite/etc/apache/conf.d/

# Option B: set it via omd config directly
omd config mysite set APACHE_TCP_ADDR 0.0.0.0
omd config mysite set APACHE_TCP_PORT 5000

# Then start the site
omd start mysite

Your workaround of manually copying cmk_docker.conf was exactly the right fix !!!

Greetz Bernd

4 Likes
Migration depuis une machine à une image docker
3

Hi Bernd,

Thank you very much for the comprehensive response! :slightly_smiling_face: I am relieved that I did not make this harder than it needed to be, other than the learning process.

I did try this early on, and it did seem to make the process more streamlined, but at that point I had yet to discover the issue with missing cmk_docker.conf file, hence I did not think to return to that approach. But, yes, that is completely logical.

With regard to:

If I understand things correctly, you can’t pick one option over the other. Both steps are necessary. The cmk_docker.conf file, shown below in its entirety, provides the necessary code for the website redirects that the Docker environment requires.

# Created for Checkmk docker container

UseCanonicalName Off
ServerName 127.0.0.1

# Redirect top level requests to the sites base url
RedirectMatch 302 ^/$ /mysite/

Where “mysite” is replaced with the name of the actual site, of course.

It’s also very important for any future documentation to specifically point out that this directory, and file, can only be found at the path specified when executing a shell inside the container (e.g. using “docker exec”).

It would be great if the Docker-related documentation pages could be updated to point out these steps to those who might migrate from a regular Linux installation to a Docker container.

Cheers!

aa

1 Like