Migration instructions for existing Deveo installations:
Helix TeamHub is a major release and upgrading directly to it from old Deveo installations is not supported. Follow these instructions to setup new Helix TeamHub instances and migrate data from old Deveo instances.
Before proceeding, make sure your Deveo instance is at version 3.18.0 or later. Contact support (email@example.com) if you need to upgrade your old Deveo instance before migrating to Helix TeamHub. Old Deveo licenses no longer work with Helix TeamHub. Contact sales (firstname.lastname@example.org) to obtain a new Helix TeamHub license.
The Main server-side differences between Helix TeamHub (hth) and the old Deveo are:
- User and group have changed from deveo to hth
- File permissions have changed from deveo:deveo to hth:hth
- Services are run as hth user
- deveo-ctl command has changed to hth-ctl
- Package names have changed from deveo to hth
- Configuration file has changed from deveo.json to hth.json
- File system paths have changed:
- /opt/deveo -> /opt/hth
- /var/opt/deveo -> /var/opt/hth
- /var/log/deveo -> /var/log/hth
In the following examples, the data from old Deveo instances is copied to a separate volume, which is mounted in
/mnt/deveo and owned by
deveo user. Adjust the example commands if you are using different approach for copying the data.
Step 1. Install new empty Helix TeamHub instance
Follow the instructions in the Admin Guide (https://helixteamhub.cloud/docs/admin/) for installing the new instances. Alternatively, the migration can be performed on the same machines by wiping the disks and reinstalling the operating system completely after copying the data in Step 2. It is recommended to install the latest supported version of the supported operating system (https://helixteamhub.cloud/docs/admin/preparation/os/).
When using MongoDB or Redis authentication, configure the new instance using the same credentials as in the old instance.
Step 2. Copy data from old Deveo instance
Shut down old Deveo instances:
sudo deveo-ctl stop
Start MongoDB on Combo or DB node:
sudo deveo-ctl start mongodb
Make a backup of MongoDB as deveo user on Combo or DB node and stop MongoDB:
sudo -u deveo -i
# No authentication used:
mongodump --host localhost:4002 -d luotsi_production --excludeCollectionsWithPrefix=system --out /mnt/deveo
# Provide the application username and password when authentication is used:
mongodump --host localhost:4002 -d luotsi_production -u username -p password --excludeCollectionsWithPrefix=system --out /mnt/deveo
sudo deveo-ctl stop mongodb
Copy the data from Combo or Web node as deveo user:
rsync -av opt shared/companies deveo
rsync -av opt shared uploads deveo
cp opt shared/deveo.json deveo
Copy the SSL certificates from Combo node as deveo user:
rsync -av /opt/deveo/sslcert/ /mnt/deveo/sslcerts
Copy the SSH host keys from Combo or Web node as root:
cp /etc/ssh/ssh_host_* /mnt/deveo/host-keys
Optionally, copy the backups from Combo or Web node as deveo user:
rsync -av /var/opt/deveo/backups /mnt/deveo
Step 3. Import data to the new instance
First, make the copied data available to the new Helix TeamHub instance.
Restore MongoDB on Combo or DB node as hth user:
sudo -u hth -i
# No authentication used:
mongorestore --port 4002 --db hth_production --drop /mnt/deveo/luotsi_production
# Provide the application username and password if authentication is used:
mongorestore --port 4002 --db hth_production -u username -p password --drop /mnt/deveo/luotsi_production
Restore avatars on Combo or Web node. Make sure permissions remain as owner and group for hth:
rsync -av /mnt/deveo/uploads/ /var/opt/hth/shared/assets/uploads/
Restore company data on Combo or Web node. Make sure permissions remain as owner and group for hth:
rsync -av /mnt/deveo/companies/ /var/opt/hth/shared/companies/
Copy old deveo.json as hth.json on Combo or Web node as hth user:
cp /mnt/deveo/deveo.json /var/opt/hth/shared/hth.json
Revise the hth.json settings:
- Verify the credentials used in Combo, Web, and DB nodes.
- Update backup and mail settings on DB node.
- Update "db_host" and "redis_host" under "backend" key on Web node.
- Update "opensshp" key's "enable" value to either true or false on Combo or Web node, depending on whether bundled OpenSSH is used (https://helixteamhub.cloud/docs/admin/preparation/os/).
Copy SSL certificates on Combo node as hth user:
rsync -av /mnt/deveo/sslcerts/ /opt/hth/sslcert/
Copy SSH host keys on Web node to the shared location as root and sync the same keys to the load balancer on HA setups.
cp /mnt/deveo/host-keys/ssh_host_* /var/opt/hth/shared/ssh/
Copy SSH host keys on Combo and all Web nodes as root:
cp /mnt/deveo/host-keys/ssh_host_* /etc/ssh/
Reconfigure the instance on Combo or Web node:
sudo hth-ctl reconfigure
Run migrations on Combo or Web node:
sudo hth-ctl migrate deveo-to-hth
Reconfigure the rest of the Web nodes:
sudo hth-ctl reconfigure
Optionally copy backups on Combo or Web node as hth user and rename repositories backup directory:
rsync -av /mnt/deveo/backups/repos_backup /var/opt/hth/backups
rsync -av /mnt/deveo/backups/backend_backup /var/opt/hth/backups
rsync -av /mnt/deveo/backups/mongodb_backup /var/opt/hth/backups
mv deveo hth
Step 4. (Optional) Supporting old SSH clone urls with deveo username
The username in SSH clone urls has changed from
hth. The old clone urls can still be supported by duplicating the
hth user and group entries as
deveo on the Combo and Web nodes (make sure the duplicated deveo user comes after the hth user, and leave the home directory as '/opt/hth' for both users with 'vipw'):
Change the /etc/ssh/sshd_config to match both deveo and hth user on the Combo and Web nodes:
Match User hth,deveo