Convert DataStax Installer installations

Starting with DSE 6.0, the DataStax Installer isn’t supported.

If you installed an earlier version of DSE using the DataStax Installer, you must convert your installation to a tarball or package installation of the same version before upgrading to DSE 6.0 or later.

These steps summarize the process of converting a DataStax Installer installation to a tarball or package installation. You might need to take alternative steps or modify the commands for your environment and version.

Treat this conversion as you would any other upgrade. Carefully review the planning guide and all instructions to reduce the chance of errors and data loss.

If you have questions or need assistance, contact DataStax Support.

For DSE 5.1 installations, determine the type of installation the DataStax Installer created:
- Services installation: This is typical when the DataStax Installer was run with root permissions. With a services installation, you start DSE using the service dse start command.
  
  For services installations, DataStax recommends converting to a package installation. When installed from a package (Yum or APT), DSE runs as a service.
- No-services installation: Occurs when the DataStax Installer was run without root permissions or with custom directories. With a no-services installation, you start DSE with the dse command.
  
  For no-services installations, DataStax recommends converting to a tarball installation. When installed from a tarball, DSE runs as a stand-alone process.
To reduce risks and effort required for upgrades, follow these best practices:
- Use a continual upgrade strategy to stay up to date with patch releases and access product improvements and new features regularly. This helps reduce the impact of changes between versions.
- Repair your nodes regularly to ensure that data on a replica is consistent with data on other nodes.
Understand that you must perform this migration on each node in each cluster. If you have multiple clusters, perform this migration on one cluster at a time. If you use racks, perform this migration one rack at a time.

In production clusters where service cannot be interrupted, perform this migration in a rolling fashion. Ensure that each node is healthy and able to service queries for existing data before proceeding to the next node.

Verify the current DSE version:

dse -v

You must migrate your installation to the same patch version as you currently have installed. For example, if you have DSE 5.1.11 installed, you must migrate to a package or tarball installation of DSE 5.1.11. Changing versions can result in data loss, incompatible configuration files, and other issues.

Back up your configuration files.
Back up your data.

DataStax recommends backing up your data prior to any version upgrade, including logs and custom configurations. A backup provides the ability to revert and restore all the data used in the previous version, if necessary.

OpsCenter provides a Backup Service that manages enterprise-wide backup and restore operations for DSE clusters. OpsCenter 6.5 is the minimum version for DSE 5.1; however 6.8.35 and later are recommended for compatibility with DSE 5.1, 6.8, and 6.9.

Use the DataStax Installer to uninstall DSE 5.1 and keep the existing data and configuration files in place.

The migration will fail if you remove the data and configuration files.

When prompted by the uninstaller, you must select the option to keep the existing data and configuration files in place.

Convert your DSE installation.

It is crucial that you install the same patch version as your previous installation.

Convert to Yum on RHEL-based systems
Convert to APT on Debian-based systems
Convert to a binary tarball

Use these steps to convert to a Yum-based package installation:

Move your existing DataStax Installer backup directory to another location:
```
cd /usr/share/dse
sudo mv backups backups.old
```
Configure and install DSE at the same patch version that you verified previously.

Because you kept the existing configuration files in place when you uninstalled DSE with the DataStax installer, the Yum installation respects those files and they are used by the package-installed version of DSE.

For example, to install DSE 5.1.11:
```
sudo install dse-full=5.1.11-1
dse=5.1.11-1 dse-libsolr=5.1.11-1 dse-libtomcat=5.1.11-1
dse-liblog4j=5.1.11-1 dse-libcassandra=5.1.11-1 dse-libspark=5.1.11-1
dse-libgraph=5.1.11-1 dse-libhadoop2-client-native=5.1.11-1
dse-libhadoop2-client=5.1.11-1
```
Repeat these steps on each node and cluster.

After upgrading all nodes on one cluster, DataStax recommends starting DSE on the cluster to verify that it is running as expected before proceeding to the next cluster. Optionally, you can test some queries or operations to ensure that the configuration settings were preserved as expected.

Use these steps to convert to an APT-based package installation:

Move your existing DataStax Installer backup directory to another location:
```
cd /usr/share/dse
sudo mv backups backups.old
```

Configure and install DSE at the same patch version that you verified previously. Use the DSE 5.1 Debian installation instructions, and add the following Dpkg::options to the apt-get install commands:

-o Dpkg::Options::="--force-confdef"
-o Dpkg::Options::="--force-confold"

The migration will fail if you don’t include the Dpkg::options flags with apt-get install. These options keep the existing configuration files in place, and prevent them from being overwritten by the new packages.

Be sure to list all packages with the same version as your previous installation. For example, to install DSE 5.1.11:

sudo apt-get -o Dpkg::Options::="--force-confdef" -o
Dpkg::Options::="--force-confold" install dse-full=5.1.11-1
dse=5.1.11-1 dse-libsolr=5.1.11-1 dse-libtomcat=5.1.11-1
dse-liblog4j=5.1.11-1 dse-libcassandra=5.1.11-1 dse-libspark=5.1.11-1
dse-libgraph=5.1.11-1 dse-libhadoop2-client-native=5.1.11-1
dse-libhadoop2-client=5.1.11-1

Repeat these steps on each node and cluster.

After upgrading all nodes on one cluster, DataStax recommends starting DSE on the cluster to verify that it is running as expected before proceeding to the next cluster. Optionally, you can test some queries or operations to ensure that the configuration settings were preserved as expected.

Use these steps to convert a DSE no-services installation to a tarball installation:

If you have any DSE Analytics nodes, recreate the Spark RDD directory, adjusting the base direction as appropriate:
```
mkdir ~/dse/spark/rdd
```
Download the DSE 5.1.z tarball for the same patch version that you verified previously.
Extract the tarball into a different directory.

To avoid conflicts with the previous installation’s preserved data and files, don’t extract the tarball into the same directory as the previous installation.

For example, to extract the DSE 5.1.11 tarball to /tmp/dse5111tar:
```
tar xvzf dse-5.1.11-bin.tar.gz -C /tmp/dse5111tar
```
To configure your new DSE installation, compare the backup configuration files to the new tarball configuration files:
- Look for any deprecated, removed, or changed settings.
- Transfer customizations from your previous no-services installation to your new DSE tarball installation.
- If any settings reference or set file paths, file names, or directories, make sure that your new installation points to the same locations.
Repeat these steps on each node and cluster. After upgrading all nodes on one cluster, DataStax recommends starting DSE on the cluster to verify that the tarball DSE installation runs as expected. Optionally, you can test some queries or operations to ensure that the configuration settings were applied as expected.

After all nodes and clusters are migrated to your new package or tarball installation, and you are able to start and operate each cluster successfully, you can continue the upgrade process to upgrade all nodes and clusters to your target DSE version.

Convert DataStax Installer installations

Was this helpful?

Give Feedback