Installation and upgrades¶
Every Rally release is published as Python packages on PyPI and as images on Docker Hub.
From PyPI¶
Rally needs Python 3.11 or newer. To test an OpenStack cloud, add the OpenStack plugins:
$ pip install rally
$ pip install rally-openstack # for OpenStack
$ uv tool install rally
$ uv tool install rally --with rally-openstack # for OpenStack
Then create the database (see Database below):
$ rally db create
Rally runs without a configuration file. All the options you can set are listed in Configuration.
With Docker¶
xrally/xrally has Rally with its own plugins; its tags are Rally
releases. xrally/xrally-openstack adds the OpenStack plugins; its tags
are rally-openstack releases. The image runs rally and already has a
database in /home/rally/.rally; keep that directory in a volume so your
results outlive the container:
$ docker volume create rally $ docker run --rm -v rally:/home/rally/.rally xrally/xrally:5.1.1 env create --name local
$ docker volume create rally $ docker run --rm -v rally:/home/rally/.rally xrally/xrally-openstack:4.1.0 env create --name local
The image keeps the Rally source tree, with all the sample tasks, in
/rally/source (the OpenStack image adds rally-openstack's in
/rally/xrally_openstack). Do not mount anything over /rally, or
these files are hidden.
How to mount a host directory instead of a volume, where the configuration file is inside the container and how to build your own image on top are described on the image page.
Database¶
Rally keeps environments, tasks and verifications in a database. By default,
the database is an SQLite file, rally.sqlite in the system temporary
directory (for example, /tmp/rally.sqlite), which many systems clear on
reboot. To keep your results, or to share them between several machines,
set another location or another database in the connection option of the
[database] section of the configuration file (see Configuration):
[database]
connection = postgresql+psycopg://user:password@db.example.com/rally
The option takes a
SQLAlchemy URL.
For a database server, install the driver with an extra of the rally
package and create an empty database; rally db create then creates the
tables in it.
Database |
Extra |
|
|---|---|---|
SQLite (default) |
none |
|
MySQL or MariaDB |
|
|
PostgreSQL |
|
|
$ pip install "rally[postgres]"
$ uv tool install "rally[postgres]"
uv tool install replaces the whole environment, so add
--with rally-openstack if you use the OpenStack plugins.
The mysql extra installs PyMySQL>=0.9.0 and the postgres
extra installs psycopg[binary]>=3. These are the drivers Rally is
tested with, and the connection URLs above use them.
Upgrades¶
A new release may change the database schema. After you upgrade the package or switch to a newer image, bring the database up to date; your data is kept:
$ pip install --upgrade rally
$ rally db upgrade
$ uv tool upgrade rally
$ rally db upgrade
Run the upgrade with the new image and the same volume:
$ docker run --rm -v rally:/home/rally/.rally xrally/xrally:5.1.1 db upgrade
rally db revision shows which schema version the database has.
Warning
Rally cannot downgrade the database. Back it up before an upgrade if you may need to go back to the older release.
Changing the schema in Rally's code is covered in the developer notes on migrations.
