Octeth Training Center
Octeth Training Center
Version Upgrade

Version Upgrade

Version Upgrade

How to Upgrade Octeth v5.5.5 (or Older) to v5.6.0

⚠️

Important: This upgrade requires a detailed manual process due to the MySQL 5.7 to MySQL 8.0 transition. Future Octeth upgrades will be much more straightforward after completing this upgrade.

Why This Upgrade Requires Manual Steps

  • Database Engine Change: Octeth v5.6.0 requires MySQL 8.0 or higher.
  • Environment Configuration Update: Some environment files and service definitions have been updated.
  • Structural Improvements: This lays the foundation for easier upgrades in the future.

Step-by-Step Upgrade Instructions

1. Backup Your Octeth v5.5.5 Installation

cd /path/to/octeth
docker compose down
cd ..
tar -czvf octeth_backup_$(date +%Y%m%d).tar.gz octeth/

Note: Always back up both your files and your database before proceeding.

2. Download and Prepare Octeth v5.6.0 Package

  • Download oempro-rel-v5.6.0.zip.
  • Extract it into a separate directory, e.g., /path/to/octeth_v560/.
cd /path/to/
unzip oempro-rel-v5.6.0.zip -d octeth_v560/

3. Sync Files (Excluding Runtime and Config Files)

Create an exclude file octeth-upgrade-exclude-list.txt with the following contents:

echo "_dockerfiles/clickhouse/data/*
_dockerfiles/elasticsearch/data/*
_dockerfiles/inbound-smtp-server/config.json
_dockerfiles/letsencrypt/*
_dockerfiles/mysql/*
_dockerfiles/rabbitmq/data/*
_dockerfiles/redis/data/*
_dockerfiles/haproxy.cfg
_dockerfiles/*-prod
_dockerfiles/*-prod.*
_dockerfiles/*-staging
_dockerfiles/*-staging.*
k8s-cluster-prod/
k8s-cluster-staging/
data/attachments/*
data/eg_spool/*
data/email_templates/*
data/exports/*
data/imports/*
data/incoming_emails/*
data/logs/*
data/maintenance_cache/*
data/screenshots/*
data/tmp/*
data/config.inc.php
data/license.dat
system/storage/
.oempro_clickhouse_env
.oempro_mysql_env
.oempro_rabbitmq_env
.oempro_redis_env
.oempro_supervisor_env
docker-compose.yml
docker-compose-*.yml
system/.env
system/storage/framework/sessions/*
system/bootstrap/cache" > octeth-upgrade-exclude-list.txt

Then sync:

rsync -avz --exclude-from "octeth-upgrade-exclude-list.txt" ./octeth_v560/ ./octeth/

4. Update and Verify Environment Files

Check and copy missing .env files if necessary:

diff <(ls -1 octeth_v560/_dockerfiles/examples/.*_env.example | sort) <(ls -1 octeth/.*_env | sort)

# If missing, copy:
cp octeth_v560/_dockerfiles/examples/.oempro_env.example octeth/.oempro_env

Edit .oempro_env manually if needed (e.g., set passwords).

5. Upgrade MySQL from 5.7 to 8.0

Create a temporary Docker Compose override file to run MySQL 5.7 alongside MySQL 8:

cat << 'EOF' > octeth/docker-compose.override.yml
services:
  mysql_v57:
    build:
      context: .
      dockerfile: ./_dockerfiles/dockerfiles/Dockerfile-mysql
    container_name: oempro_mysql_v57
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    env_file:
      - ./.oempro_mysql_env
    restart: always
    hostname: oempro_mysql_v57
    ports:
      - "33007:3306"
    volumes:
      - ./_dockerfiles/mysql/log:/var/log/mysql
      - ./_dockerfiles/mysql/conf.d:/etc/mysql/conf.d
      - ./_dockerfiles/mysql/data:/var/lib/mysql
    networks:
      public_net:
        ipv4_address: 192.168.99.248
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
EOF

Start services:

cd /path/to/octeth
docker compose up -d

Export the old database:

OCTETH_MYSQL_ROOT_PASSWORD=$(grep MYSQL_ROOT_PASSWORD .oempro_mysql_env | cut -d '=' -f2)
docker exec oempro_mysql_v57 mysqldump -u root -p"$OCTETH_MYSQL_ROOT_PASSWORD" --databases oempro --add-drop-database --routines --triggers --events --single-transaction --set-gtid-purged=OFF > /tmp/oempro_dump.sql

Import into MySQL 8.0:

docker exec -i oempro_mysql mysql -u root -p"$OCTETH_MYSQL_ROOT_PASSWORD" < /tmp/oempro_dump.sql

Recreate users:

docker exec -i oempro_mysql mysql -u root -p"$OCTETH_MYSQL_ROOT_PASSWORD" -e "DROP USER IF EXISTS 'oempro'@'%';"
docker exec -i oempro_mysql mysql -u root -p"$OCTETH_MYSQL_ROOT_PASSWORD" -e "CREATE USER 'oempro'@'%' IDENTIFIED BY '$OCTETH_MYSQL_ROOT_PASSWORD';"
docker exec -i oempro_mysql mysql -u root -p"$OCTETH_MYSQL_ROOT_PASSWORD" -e "GRANT ALL PRIVILEGES ON oempro.* TO 'oempro'@'%';"
docker exec -i oempro_mysql mysql -u root -p"$OCTETH_MYSQL_ROOT_PASSWORD" -e "FLUSH PRIVILEGES;"

Stop services and remove override:

docker compose down
rm docker-compose.override.yml

6. Rebuild and Restart Octeth

Rebuild containers:

cd /path/to/octeth
chmod -R 0777 data system/storage/ system/bootstrap/cache/ _dockerfiles/elasticsearch/data _dockerfiles/mysql/data _dockerfiles/mysql/log _dockerfiles/rabbitmq/data _dockerfiles/redis/data
docker compose build --no-cache
docker compose up -d

7. Update config.inc.php Temporarily

Edit data/config.inc.php:

vi data/config.inc.php
# Change: define('PRODUCT_VERSION', '5.6.0');
# To:     define('PRODUCT_VERSION', '5.5.5');

8. Run Database Upgrade via Web Browser

  • Open your browser and navigate to http://yourdomain/install/upgrade.php.
  • Complete the database upgrade wizard.

9. Final Adjustments

Update data/config.inc.php again:

vi data/config.inc.php
# Change back: define('PRODUCT_VERSION', '5.6.0');

Remove the install/ directory:

rm -rf install/

Install Composer dependencies:

docker exec -ti oempro_app bash -c "cd /var/www/html && /usr/bin/php5.6 /usr/local/bin/composer install --ignore-platform-reqs"
docker exec -ti oempro_app bash -c 'for dir in /var/www/html/plugins/*; do [ -d "$dir" ] && [ -f "$dir/composer.json" ] && echo "Running composer install in $dir" && (cd "$dir" && /usr/bin/php5.6 /usr/local/bin/composer install --ignore-platform-reqs); done'
docker exec -ti oempro_supervisor bash -c "cd /var/www/html/cli/email_campaign_controller && php8.1 /usr/local/bin/composer install"
docker exec -ti oempro_system bash -c "cd /var/www/html/system && php artisan optimize:clear"

Run Laravel and Octeth DB migrations:

docker exec -ti oempro_system bash -c "cd /var/www/html/system && php artisan migrate"
docker exec -ti oempro_app bash -c "cd /var/www/html/cli && php5.6 dbmigrator.php migrate"

Restart supervisor processes:

docker exec -ti oempro_supervisor bash -c "supervisorctl restart all"
docker exec -ti oempro_system bash -c "supervisorctl restart all"

Check supervisor status:

docker exec -ti oempro_supervisor bash -c "supervisorctl status"
docker exec -ti oempro_system bash -c "supervisorctl status"

10. Final Health Check

Find your ADMIN_API_KEY:

cat data/config.inc.php | grep ADMIN_API_KEY

Run system health check:

curl -i http://yourdomain/api/v1/system-health-check --header "Authorization: Bearer YOUR_ADMIN_API_KEY"

You should see all systems as OK.

Congratulations!

You have successfully upgraded Octeth to v5.6.0 with MySQL 8.0. Your future upgrades will now be easier and faster.

ℹ️

If you encounter any issues, please contact support@octeth.com.

How to Upgrade Octeth v4.14.5 (or Older) to v5.5.2

This document outlines the process for upgrading your Octeth installation from version 5.0.0 to version 5.5.2. Please follow the steps carefully to ensure a successful upgrade.

Prerequisites

Ensure that you are currently running Octeth version 4.14.5 or newer. You can verify your version by executing the following commands:

cd /opt/oempro/
cat data/config.inc.php | grep VERSION
# Output should be: define('PRODUCT_VERSION', '5.0.0');

Backup Current Installation

Before proceeding with the upgrade, take a backup of the current installation:

cd /opt/
du -csh oempro  # Check the directory size for reference
docker-compose stop  # Stop all running containers
tar -cvzf oempro_backup_YYYYMMDD.tar.gz oempro  # Create a backup archive. Replace YYYYMMDD with the current date

Upgrade Docker Compose

Ensure that Docker Compose is updated to the latest version:

uname -s | tr '[:upper:]' '[:lower:]'  # Outputs the OS type in lowercase
uname -m  # Outputs the machine type
curl -L "<https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-$>(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
docker-compose -v  # Verify the version

Transfer New Package

Transfer the new Octeth package from your local machine to the server:

scp /path/of/octeth/oempro-rel-v5.5.2.zip root@your.server.ip:/opt/

Prepare Environment Files

Verify and update the necessary environment configuration files:

  • .oempro_clickhouse_env
  • .oempro_mysql_env
  • .oempro_rabbitmq_env
  • .oempro_redis_env
  • .oempro_supervisor_env
cd /opt/oempro
# Check and regenerate necessary values if needed
ls .oempro_*_env  # Check all environment files exist
echo "Update values as needed here, especially passwords."
# Example environment files are stored under _dockerfiles/examples/ directory

Remove Old Containers and Network

Remove any stopped containers and the existing Docker network to prevent conflicts:

cd /opt/oempro/
docker-compose stop
docker-compose rm -f
docker network rm oempro-network

Prepare for New Version

Unzip the new version into a temporary directory and prepare the system for the upgrade:

mkdir /opt/octeth-v552-deploy
unzip /opt/oempro-rel-v5.5.2.zip -d /opt/octeth-v552-deploy

Exclude Specific Files and Directories

Create an exclusion file list to prevent overwriting custom configurations:

echo "_dockerfiles/clickhouse/data/*
_dockerfiles/elasticsearch/data/*
_dockerfiles/inbound-smtp-server/config.json
_dockerfiles/letsencrypt/*
_dockerfiles/mysql/*
_dockerfiles/rabbitmq/data/*
_dockerfiles/redis/data/*
_dockerfiles/haproxy.cfg
_dockerfiles/*-prod
_dockerfiles/*-prod.*
_dockerfiles/*-staging
_dockerfiles/*-staging.*
k8s-cluster-prod/
k8s-cluster-staging/
data/attachments/*
data/eg_spool/*
data/email_templates/*
data/exports/*
data/imports/*
data/incoming_emails/*
data/logs/*
data/maintenance_cache/*
data/screenshots/*
data/tmp/*
data/config.inc.php
data/license.dat
system/storage/
.oempro_clickhouse_env
.oempro_mysql_env
.oempro_rabbitmq_env
.oempro_redis_env
.oempro_supervisor_env
docker-compose.yml
docker-compose-*.yml
system/.env
system/storage/framework/sessions/*
system/bootstrap/cache" > /opt/octeth-upgrade-exclude-list.txt

File Comparisons and Merging

Compare critical configuration files between the old and new installations to ensure custom settings are retained:

diff -u /opt/oempro/_dockerfiles/haproxy.cfg /opt/octeth-v552-deploy/_dockerfiles/haproxy.cfg
diff -u /opt/oempro/docker-compose.yml /opt/octeth-v552-deploy/docker-compose.yml
diff -u /opt/oempro/data/config.inc.php /opt/octeth-v552-deploy/install/sources/config.inc.php
diff -u /opt/oempro/system/.env /opt/octeth-v552-deploy/system/.env.example

Synchronize New Files

Use rsync to update the installation directory with new files, excluding those specified:

rsync -avz --exclude-from "/opt/octeth-upgrade-exclude-list.txt" /opt/octeth-v552-deploy/ /opt/oempro/

Build and Start Containers

Rebuild Docker containers and verify the configuration by running them in the foreground:

docker-compose build --no-cache
docker-compose up

Perform Database and System Upgrades

Access the upgrade script through your browser and complete the database upgrades:

<https://yourdomain.com/install/upgrade.php>

Once the upgrade process is complete, remove the install/ directory and verify that all services are running correctly:

docker-compose ps

Update Version in Configuration

Finally, update the version number in the config.inc.php file:

vi /opt/oempro/data/config.inc.php
# Change the version number to '5.5.2'

Update Packages

Install or update packages:

cd /opt/oempro/

# app container composer:
docker exec -ti oempro_app bash -c "cd /var/www/html && /usr/bin/php5.6 /usr/local/bin/composer install --ignore-platform-reqs"

# system container composer:
docker exec -ti oempro_system bash -c "cd /var/www/html/system/ && php /usr/local/bin/composer install"

# campaign composer:
docker exec -ti oempro_supervisor bash -c "cd /var/www/html/cli/email_campaign_controller && php8.1 /usr/local/bin/composer install"

# plugins composer:
docker exec -ti oempro_app bash -c 'for dir in /var/www/html/plugins/*; do [ -d "$$dir" ] && [ -f "$$dir/composer.json" ] && echo "Running composer install in $$dir" && (cd "$$dir" && /usr/bin/php5.6 /usr/local/bin/composer install --ignore-platform-reqs); done'

Post-Upgrade Checks

Conduct a system health check to ensure all components are functioning as expected:

cd /opt/oempro
cat data/config.inc.php | grep ADMIN_API_KEY
# define('ADMIN_API_KEY', '****-****-****-****');
curl -i <https://yourdomain.com/api/v1/system-health-check> --header "Authorization: Bearer <your_admin_api_key>"

Troubleshooting

If you encounter issues, refer to the logs for each container, especially if a service is failing to start:

docker logs <container_name>

Consider rolling back to the backup if the upgrade does not resolve after troubleshooting.

Don’t hesitate to contact us for assistance.

How to Upgrade Octeth v4.14.5 (or Newer) to v5.5.1

This article contains version upgrade instructions for Oempro v4.14.5 and higher Docker based versions.

If you are going to upgrade your Oempro v4.14.4 Docker version to the most recent version, please follow these instructions:

  1. First, upload the latest Oempro version zip file to your server. (/opt/oempro/)
  2. Backup your MySQL database
  3. Backup your Oempro directory (/opt/oempro/)
  4. Change current directory into Oempro:
    5. cd /opt/oempro/
  5. Stop Docker containers:
    6. docker-compose kill
  6. Take a backup of _dockerfiles directory. Especially, haproxy.cfg file as it may include modified SSL certificate directives.
    7. cp /opt/oempro/_dockerfiles/haproxy.cfg /opt/oempro/_dockerfiles/haproxy.cfg.bck
  7. Take a backup of the config file:
    8. cp /opt/oempro/data/config.inc.php /opt/oempro/data/config.inc.php.bck
  8. Unzip the Oempro zip package. ZIP may ask you what to do for existing files. Choose “Replace All” option.
  9. Copy the SSL certificate directory from the _dockerfiles/haproxy.cfg.bck file to the _dockerfiles/haproxy.cfg file:
    10. # Enable these two lines if you have activated LetsEncrypt SSLbind *:443 ssl crt /etc/letsencrypt/live/yourdomain.com/yourdomain.com.pem
redirect scheme https if !{ ssl_fc }
  10. Create the following environment file inside /opt/oempro/ directory:
    11. touch /opt/oempro/.oempro_mysql_env
  11. Paste the following content into the .env file:
    12. HOSTNAME=oempro_mysql
MYSQL_ROOT_PASSWORD=set_a_password_here
  12. Pull latest Docker updates:
    13. docker-compose pull
  13. Build Docker containers:
    14. docker-compose build
  14. Start the Docker compose:
    15. docker-compose up -d
  15. Open your web browser and go to the upgrade utility to perform the last upgrade task. The upgrade tool can be executed via the following URL:
    16. https://app.yourdomain.com/install/upgrade.php
  16. This step should be done if Oempro is already installed. Skip this step if there’s no update on the .env file. SSH into oempro_system container to perform a pre-upgrade process:
    17. docker exec -ti oempro_system bash
cd /var/www/html/install/
php phing.phar -f install.xml
  17. Exit to the host machine
  18. Restart supervisor processes in containers:
    19. docker exec -ti oempro_app supervisorctl restart all
docker exec -ti oempro_system supervisorctl restart all
docker exec -ti oempro_bounce supervisorctl restart all
  19. Set file permissions just to be sure:
    20. chmod -R 0777 /opt/oempro/data/
chmod -R 0777 /opt/oempro/system/storage/
chmod -R 0777 /opt/oempro/system/bootstrap/cache/
  20. Edit /opt/oempro/system/.env file and set the values. The values can be found under /opt/oempro/.oempro_rabbitmq_env file.
    21. OEMPRO_RABBITMQ_USERNAME=
OEMPRO_RABBITMQ_PASSWORD=
  21. Run these commands:
    22. docker exec -ti oempro_system php /var/www/html/system/artisan config:clear
docker exec -ti oempro_app supervisorctl restart all
docker exec -ti oempro_system supervisorctl restart all
docker exec -ti oempro_bounce supervisorctl restart all
  22. Lastly, delete the install directory to make sure that it cannot be reached later on:
    23. rm -rf /opt/oempro/install
💠
image

Homepage Customer Area Community Portal Contact Us

Footer Social Icons

©Copyright Octeth, Inc. All rights reserved.