How to Migrate to Docker

Introduction

This guide explains how to migrate your existing Easy8 installation to the official Docker-based environment, introduced in mid-2024. Docker brings many advantages like faster updates, simpler maintenance, and improved security. This guide provides a simplified overview of the migration process.

A detailed and always up-to-date manual is included in your application package: docker/README

Target Audience

• Administrator

Prerequisites

Before starting, ensure you have:

• Access to the Easy8 Client Zone
• Your Docker-compatible installation package
• Basic Docker knowledge (compose, containers, volumes)
• A migration plan including downtime and DNS/IP changes
• Backup of your current database and attachments

Block user access to the legacy app before migration to avoid data mismatch.

How to Migrate to Docker

Step 1: Prepare the Docker Application

1. Log in to the Client Zone
2. Download the official Docker package
   • Includes login credentials to Docker registry
   • Contains configuration files, templates, and the README manual
3. Set up your environment as described in the manual
4. Log in and download your Easy8 Docker image
5. Launch the container and verify it runs (e.g., try opening the login page)

Before continuing, stop the application:

docker compose down

Now you're ready to prepare the data.

Step 2: Prepare Data to Migrate

Ensure you have:

• A compatible database dump (e.g., restore.sql or restore.sql.gz)
• Backup of your attachments folder (files/) from the legacy instance

Database dumps must work with Percona 8 as of December 2024.

Step 3: Restore the Database

1. Place restore.sql into:

   ./docker-entrypoint-initdb.d/

2. Remove the old DB container and volume:

   docker compose down -v db

3. Start the DB container:

   docker compose up -d db

4. Monitor progress:

   docker compose logs -f db

Wait until restoration finishes.

Step 4: Migrate Attachments

1. Copy attachments from the old instance to the Docker files directory:

   cp -R /path/to/legacy/files/* ./files/

2. Set file permissions:

   sudo chown -R 5000:5000 ./files

3. Run database migrations only:

   docker compose run --rm app install

Step 5: Post-Migration Steps

1. Start the application:

   docker compose up -d

2. (Optional) Run other commands as needed:

   docker-compose run --rm app rails 'your command'

Conclusion

Migrating to Docker may seem like a challenge, but it's a smart move for long-term maintenance, security, and performance. You now benefit from a streamlined, modern architecture that is easier to update and scale.

A full and detailed guide is always available in your package: docker/README

Related Topics and Further Reading

• Easy8 Documentation
• Percona Docker Image
• Docker Official Documentation