Migrating to Perforce TeamHub Enterprise

Migration instructions for existing Deveo installations:

Perforce TeamHub is a major release and upgrading directly to it from old Deveo installations is not supported. Follow these instructions to setup new 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 protected]) if you need to upgrade your old Deveo instance before migrating to TeamHub. Old Deveo licenses no longer work with TeamHub. Contact sales ([email protected]) to obtain a new Perforce TeamHub license.

The Main server-side differences between Perforce 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 Perforce 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 /var/opt/deveo/shared/companies /mnt/deveo

rsync -av /var/opt/deveo/shared/assets/uploads /mnt/deveo

cp /var/opt/deveo/shared/deveo.json /mnt/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:

mkdir /mnt/deveo/host-keys

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 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:

mkdir /var/opt/hth/backups/

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

cd /var/opt/hth/backups/repos_backup/var/opt/

mv deveo hth

 

Step 4. (Optional) Supporting old SSH clone urls with deveo username

The username in SSH clone urls has changed from deveo to 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'):

vipw

vipw -s

vigr

vigr -s

 

Change the /etc/ssh/sshd_config to match both deveo and hth user on the Combo and Web nodes:

Match User hth,deveo