Upgrade Rudder on Debian or Ubuntu

Before upgrading, especially for minor and major version upgrades, please read the upgrade notes.

Rudder includes a script for upgrading all files, databases, etc…​ which need migrating. Therefore, you should not replace your old files by the new ones when apt asks about this, unless you want to reset all your parameters.

Add Rudder’s package repository:

# If lsb_release is not installed on your machine, change $(lb_release -cs) by your distribution codename.
# Ex:
#   stretch for Debian 9
#   bionic  for Ubuntu 18.04 LTS

echo "deb [arch=$(dpkg --print-architecture)] http://repository.rudder.io/apt/7.3/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/rudder.list

If you have an active subscription, use the following to get access to long term support. You need to replace the user name (LOGIN) and the password (PASSWORD) by your Rudder account:

echo "deb [arch=$(dpkg --print-architecture)] https://download.rudder.io/apt/7.3/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/rudder.list

# for recent debian (>=10) and ubuntu (>=20)
echo 'machine download.rudder.io login LOGIN password PASSWORD' > /etc/apt/auth.conf.d/rudder.conf
chmod 640 /etc/apt/auth.conf.d/rudder.conf

# on old debian (<10) and ubuntu (<20) use this instead
#echo 'machine download.rudder.io login LOGIN password PASSWORD' >> /etc/apt/auth.conf
#chmod 640 /etc/apt/auth.conf

Update your local package database to retrieve the list of packages available on our repository:

apt-get update

Rudder agent

For Rudder agent, upgrade the agent package:

apt-get install rudder-agent

Rudder server

For Rudder server, upgrade the server packages:

apt-get install rudder-server

Technique upgrade

At the first installation, Rudder will automatically deploy a technique library in the /var/rudder/configuration-repository/techniques directory.

When upgrading Rudder to another version, a new (updated) technique library will be deployed in /opt/rudder/share/techniques, and Rudder will only update the system Techniques in the configuration-repository directory.

However, Techniques from Rudder standard library are not updated automatically in Rudder 4.x, so it needs a user action.

If you want to do any modification in a Technique from the standard library, it is recommended to create a whole new Technique (copy the source one with a new name and version), and do your changes in this new Technique. Thus, your standard library won’t diverge from Rudder upstream one, and you will be able to benefit from its updates.

To upgrade you local techniques, run the following commands on the Rudder server: If you did any manual modifications in existing Techniques from standard library, you will need to merge the changes during upgrade of Techniques.

To upgrade your standard library’s techniques, there are two possibilities

Default case: your standard technique library is pristine

If you did not modify any of the Technique from standard library (default case), or don’t wish to keep any changes you made, you can override the Technique Library

rudder server upgrade-techniques -o

Techniques created with the Technique Editor are not impacted by this command.

Special case: Techniques from standard library were modified

If you modified a Technique from the standard library and wish to keep the changes, changes will be performed in an update branch in the git repository You will need to create the update branch if it is not already created, with the following command

$ rudder server upgrade-techniques  -i
Creating initial branch from an early commit
You have not provided an initial commit, we will use the first commit with techniques.
This can make the upgrade merge complex.
Use -c option to specify a more recent commit with no patch.

Type ctrl-c to abort now and return to continue.

If the branch already exists, you will get the following output

Creating initial branch from an early commit
The upgrade branch 'rudder_update' already exists, aborting

And then you can merge your changes in the upgraded Techniques with

# Upgrade the techniques
$ rudder server upgrade-techniques -u
Switched to branch 'rudder_update'
Switched to branch 'master'
Merge made by the 'recursive' strategy.
ok: reload techniques from files.

Please note that you may have to manually fix the merge.

Finally, please check that the deployment is successful in the Rudder web interface.

← Upgrade notes on RHEL/CentOS/Amazon Linux →