Octeth Training Center
Octeth Training Center
Version Upgrade

Version Upgrade

Version Upgrade

Octeth Upgrade Guide: v4.14.5 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.

Octeth Upgrade Guide: v4.14.5+ 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.