Getting started
Installation & Setup
Video Tutorials
Administration
Audience Management
Email Marketing
Plug-Ins & Add-Ons
Developers
Advanced
Help
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:
- First, upload the latest Oempro version zip file to your server. (
/opt/oempro/
) - Backup your MySQL database
- Backup your Oempro directory (
/opt/oempro/
) - Change current directory into Oempro:
- Stop Docker containers:
- Take a backup of
_dockerfiles
directory. Especially,haproxy.cfg
file as it may include modified SSL certificate directives. - Take a backup of the config file:
- Unzip the Oempro zip package. ZIP may ask you what to do for existing files. Choose “Replace All” option.
- Copy the SSL certificate directory from the
_dockerfiles/haproxy.cfg.bck
file to the_dockerfiles/haproxy.cfg
file: - Create the following environment file inside
/opt/oempro/
directory: - Paste the following content into the .env file:
- Pull latest Docker updates:
- Build Docker containers:
- Start the Docker compose:
- 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:
- 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: - Exit to the host machine
- Restart supervisor processes in containers:
- Set file permissions just to be sure:
- Edit
/opt/oempro/system/.env
file and set the values. The values can be found under/opt/oempro/.oempro_rabbitmq_env
file. - Run these commands:
- Lastly, delete the install directory to make sure that it cannot be reached later on:
cd /opt/oempro/
docker-compose kill
cp /opt/oempro/_dockerfiles/haproxy.cfg /opt/oempro/_dockerfiles/haproxy.cfg.bck
cp /opt/oempro/data/config.inc.php /opt/oempro/data/config.inc.php.bck
# 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 }
touch /opt/oempro/.oempro_mysql_env
HOSTNAME=oempro_mysql
MYSQL_ROOT_PASSWORD=set_a_password_here
docker-compose pull
docker-compose build
docker-compose up -d
https://app.yourdomain.com/install/upgrade.php
docker exec -ti oempro_system bash
cd /var/www/html/install/
php phing.phar -f install.xml
docker exec -ti oempro_app supervisorctl restart all
docker exec -ti oempro_system supervisorctl restart all
docker exec -ti oempro_bounce supervisorctl restart all
chmod -R 0777 /opt/oempro/data/
chmod -R 0777 /opt/oempro/system/storage/
chmod -R 0777 /opt/oempro/system/bootstrap/cache/
OEMPRO_RABBITMQ_USERNAME=
OEMPRO_RABBITMQ_PASSWORD=
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
rm -rf /opt/oempro/install
On this page
- Version Upgrade
- How to Upgrade Octeth v5.5.5 (or Older) to v5.6.0
- Why This Upgrade Requires Manual Steps
- Step-by-Step Upgrade Instructions
- 1. Backup Your Octeth v5.5.5 Installation
- 2. Download and Prepare Octeth v5.6.0 Package
- 3. Sync Files (Excluding Runtime and Config Files)
- 4. Update and Verify Environment Files
- 5. Upgrade MySQL from 5.7 to 8.0
- 6. Rebuild and Restart Octeth
- 7. Update config.inc.php Temporarily
- 8. Run Database Upgrade via Web Browser
- 9. Final Adjustments
- 10. Final Health Check
- Congratulations!
- How to Upgrade Octeth v4.14.5 (or Older) to v5.5.2
- Prerequisites
- Backup Current Installation
- Upgrade Docker Compose
- Transfer New Package
- Prepare Environment Files
- Remove Old Containers and Network
- Prepare for New Version
- Exclude Specific Files and Directories
- File Comparisons and Merging
- Synchronize New Files
- Build and Start Containers
- Perform Database and System Upgrades
- Update Version in Configuration
- Update Packages
- Post-Upgrade Checks
- Troubleshooting
- How to Upgrade Octeth v4.14.5 (or Newer) to v5.5.1