Migrate to Docker

Intro

Since mid-2024, Easy Redmine has a native Docker solution (= officially supports deployment via Docker). It brings enormous advantages, as we list in environment requirements and in a specialized article.

Here you will find the guide to migrate from your existing (legacy) installation into a new Docker environment.

The principle

We are practically talking about data migration into a newly started Docker instance with Easy Redmine application.

Preparation

• Think about how and when you will be switching DNS and IP address(es) between existing and new application
• Adjust your plan based on the allowed downtime of production
• Try a test migration - at least to find out how long will the data transfer take (attachments copying is usually the longest part)
• You don't want new data in the old application after migration started => make sure that the existing application is not accessible by users before you start DB dump and files copying.

Steps

1. Log in Client zone
2. Download the Docker "package"
   
   
3. The package contains every explanation for every step that follows. It is maintained regularly, which is the reason why we are not listing it in this article.
   
   
1. Login credentials to docker registry, which contains an image with your purchased solution
2. A very detailed and precise README manual to prepare your environment
3. Configuration files and examples for an easier start
4. Prepare your environment with the help of the resources above
5. Log in to the source of your ER Docker image and run a few commands to download and launch it
6. Try to open the login page of the application just to make sure that it is able to run
   Here you can have a long pause - new app is ready, you can get to know the new environment and docker system before working with production data
7. Before the migration, stop the app
   

   docker compose down
   

8. Into the base folder of the application, i.e. the place where docker-compose.yml, .env are located (= from where you run docker compose commands) - copy the folder files from your existing application
   These are the attachments, documents, images, avatars and other objects that users upload into Easy Redmine.
   
9. Make sure to set necessary permissions for files folder
   

   chown -R 5000:5000 files
   chmod -R u+rwx files

10. Dump the database from your existing application
11. Replace the database in the new server

(echo -ne ‘drop database dummy;\ncreate database dummy;\n’; zcat dump.sql.gz) | docker compose run db mysql dummy


Important:


• The database name dummy must be taken from the .env MYSQL_DATABASE=
• dump.sql.gz is the name of your DB dump from the existing application
12. CTRL+C after finished
13. Run migrations
    

    docker compose run --rm app start

14. CTRL+C after finished
15. If there were no errors, we can start the application
    

    docker compose up -d
    

    Important:
    

    • files are mounted to the container based on docker-compose.yml and .env - please read them carefully and understand how it affects the steps and names you are working with
    • database identification is based .env as described in step 11

In summary, the parts which need the most careful attention are:

• consistent name of the actual database and in the .env configuration
• consistent location of the files folder with docker-compose.yml - by following steps above, you won't need to change anything in docker-compose.yml, which is our recommendation
• proper permissions for files folder - you can test by logging into the application, trying to upload/delete an attachment, your avatar for example. Insufficient permissions would most likely result in error 500

You are doing the right thing

While this whole operation may seem like an unnecessary obstacle (especially for admins less experienced with Docker mechanisms) it has undisputable value in the long run. Seamless updates and upgrades => regular security fixes => easier utilization of ever improving modern technologies.