Skip to content

Migration v26.1

Hleb Kanonik edited this page Nov 20, 2026 · 3 revisions

Migration from ReportPortal 26.0 to 26.1

This guide is for administrators moving a Docker Compose installation from ReportPortal 26.0.7 to 26.1. Read Breaking changes first. Docker Compose does not copy objects and does not rewrite paths in PostgreSQL.

Contents

Pick your path

Start from the 26.0.7 docker-compose.yml. Storage settings in that file are inside x-environment (API, Jobs, UAT) and again inside x-analyzer-environment. There is no x-storage block. Then pick the option that matches the storage you run today:

Your 26.0.7 install What you do Where
Filesystem (DATASTORE_TYPE: filesystem, volume storage at /data/storage) Take the 26.1 file. x-storage is already filesystem. No object copy Option A
External MinIO, SeaweedFS, Ceph RGW, or another S3 API (DATASTORE_TYPE: minio, or s3 with your own endpoint), multi Move the settings into x-storage as s3-compatible and copy the buckets into folders inside the default bucket Option B
The same external store with RP_FEATURE_FLAGS: singleBucket Move the settings into x-storage as s3-compatible. No copy Option B
Amazon S3 (DATASTORE_TYPE: s3, RP_FEATURE_FLAGS: singleBucket) Move the settings into x-storage as aws-s3. No copy Option C

Breaking changes

Read this section before you change anything. Each item can make existing files unreachable or stop the release from starting.

  1. Storage settings moved to x-storage. In 26.0.7, DATASTORE_TYPE and the other DATASTORE_* keys live in x-environment, and the analyzer repeats them in x-analyzer-environment. The 26.1 file removes those keys from both blocks and adds one anchor, x-storage, which both blocks include. A value you leave in the old place is not applied. Copy your values into x-storage before you start the new release. See Where the settings moved.
  2. DATASTORE_TYPE: minio and DATASTORE_TYPE: s3 are no longer valid. Use s3-compatible (MinIO, SeaweedFS, Ceph RGW, and other S3 APIs) or aws-s3. filesystem is unchanged.
  3. The 26.0.7 S3 example spells the secret DATASTORE_SECRETSKEY. The variable the services read is DATASTORE_SECRETKEY. A key left under the old spelling is ignored, and the API starts without your secret.
  4. The multi object layout changed. In 26.0, multi means one bucket per project (prj-<projectId>). In 26.1, multi keeps the same names but as folders inside the default bucket (rp-bucket/prj-<projectId>/…). 26.1 does not read the 26.0 buckets. Existing data must be copied into the new layout. Filesystem storage is not affected. See Where objects live.
  5. The UAT service is removed. service-api now issues tokens and manages sessions. The token endpoint moves from /uat/sso/oauth/token to /api/sso/oauth/token. docker compose up -d --remove-orphans removes the old uat container.
  6. The index service is removed. The same --remove-orphans flag removes that container.
  7. The superadmin login changes. In 26.1 the built-in superadmin account is renamed to admin@reportportal.internal. Sign in with the new name. Scripts that use superadmin as the login must change too.

Compared releases:

26.0.7 26.1
Service images 5.15.x (API_IMAGE, JOBS_IMAGE, UI_IMAGE, MIGRATIONS_IMAGE, ANALYZER_IMAGE) 6.0.0 on the same variables
Storage settings Inside x-environment and again in x-analyzer-environment One x-storage anchor, included by both
DATASTORE_TYPE minio, s3, filesystem s3-compatible, aws-s3, filesystem
API and Jobs filesystem path Volume mount /data/storage DATASTORE_PATH: /data/storage plus the same mount. The analyzer does not read DATASTORE_PATH
Analyzer filesystem path FILESYSTEM_DEFAULT_PATH: /data/storage/analyzer Unchanged. This is the path service-auto-analyzer 6.0.0 reads
Analyzer store type ANALYZER_BINARYSTORE_TYPE and a separate DATASTORE_TYPE DATASTORE_TYPE from x-storage. ANALYZER_BINARYSTORE_TYPE is deprecated
Secret variable in the S3 example DATASTORE_SECRETSKEY DATASTORE_SECRETKEY
Default bucket mode multi, unless RP_FEATURE_FLAGS: singleBucket multi (folders in one bucket). singleBucket is unchanged
Analyzer object path DATASTORE_DEFAULTBUCKETNAME: <bucket>/analyzer DATASTORE_BUCKETPREFIX: analyzer/prj- on the shared bucket
Superadmin login superadmin admin@reportportal.internal
Token endpoint /uat/sso/oauth/token /api/sso/oauth/token

What changed

service-api, service-jobs, and service-auto-analyzer use Apache OpenDAL and accept only s3-compatible, aws-s3, and filesystem.

26.0.7 value 26.1 value
DATASTORE_TYPE: minio DATASTORE_TYPE: s3-compatible
DATASTORE_TYPE: s3 DATASTORE_TYPE: aws-s3
DATASTORE_TYPE: filesystem unchanged. The analyzer reads this value
ANALYZER_BINARYSTORE_TYPE deprecated. Remove it. 6.0.0 warns when it is set, and uses DATASTORE_TYPE

RP_FEATURE_FLAGS: singleBucket still selects one bucket with the 26.0 key layout. Leave it unset for multi.

In Docker Compose, DATASTORE_ENDPOINT keeps the scheme and the port, for example http://minio:9000.

The commented MinIO secret in 26.0.7 is miniopassword. The commented secret in 26.1 is rppassword. If you set STORAGE_SECRETKEY in .env, that value still wins. If you relied on the compose default, write the password you use today into DATASTORE_SECRETKEY. A new default does not open the old store.

Where the settings moved

26.0.7 keeps storage on the services that include x-environment. The analyzer does not use that anchor. It has its own DATASTORE_TYPE.

# 26.0.7 — inside x-environment (API, Jobs, UAT)
x-environment: &common-environment
  # ... database and AMQP ...
  DATASTORE_TYPE: filesystem          # or s3

# 26.0.7 — inside x-analyzer-environment (analyzer only)
x-analyzer-environment: &common-analyzer-environment
  ANALYZER_BINARYSTORE_TYPE: filesystem
  DATASTORE_TYPE: filesystem          # or minio, or s3
  FILESYSTEM_DEFAULT_PATH: &analyzer-default-path /data/storage/analyzer

26.1 defines DATASTORE_TYPE once. x-environment and x-analyzer-environment both pull the anchor in with <<: *storage-environment. service-auto-analyzer 6.0.0 reads DATASTORE_TYPE. ANALYZER_BINARYSTORE_TYPE is deprecated: if it is still set, the process warns and keeps DATASTORE_TYPE. Delete the old variable. The analyzer does not read DATASTORE_PATH. Its filesystem directory stays FILESYSTEM_DEFAULT_PATH.

# 26.1
x-storage: &storage-environment
  DATASTORE_TYPE: filesystem
  DATASTORE_PATH: /data/storage          # API and Jobs only

x-environment: &common-environment
  # ... database and AMQP ...
  <<: *storage-environment

x-analyzer-environment: &common-analyzer-environment
  <<: *storage-environment               # DATASTORE_TYPE comes from here
  FILESYSTEM_DEFAULT_PATH: &analyzer-default-path /data/storage/analyzer

Before you replace docker-compose.yml, copy every DATASTORE_* line and RP_FEATURE_FLAGS you changed in both blocks. After you take the 26.1 file:

  • Put the API and Jobs values into x-storage only.
  • Leave x-environment as database, AMQP, and <<: *storage-environment.
  • Delete ANALYZER_BINARYSTORE_TYPE and any second DATASTORE_TYPE from x-analyzer-environment.
  • Keep FILESYSTEM_DEFAULT_PATH there. That is the analyzer filesystem path. DATASTORE_PATH does not replace it.
  • For object storage, uncomment DATASTORE_BUCKETPREFIX: analyzer/prj- in x-analyzer-environment. That replaces the 26.0.7 analyzer bucket name <bucket>/analyzer. The prefix applies only to the analyzer, because it is set after the merge.

DATASTORE_PATH is new, and only API and Jobs read it. It must be the path where the storage volume is mounted on those containers. The 26.1 default is /data/storage, which matches storage:/data/storage. If you replaced that mount with a bind such as ./data/storage:/data/storage, put the same bind back on api and jobs and keep DATASTORE_PATH equal to the container path. The analyzer volume stays mounted at FILESYSTEM_DEFAULT_PATH (/data/storage/analyzer).

Where objects live

In 26.1 the API opens one bucket, DATASTORE_DEFAULTBUCKETNAME. In multi mode the name of the old bucket becomes the first folder inside it. The database stores the same paths in both releases, so no SQL is needed after the copy.

Data 26.0 (bucket / key) 26.1 multi (bucket / key)
Attachments of project 1 prj-1 / 2026-11/<launchUuid>/<file> rp-bucket / prj-1/2026-11/<launchUuid>/<file>
Integration salt prj-keystore / secret-integration-salt rp-bucket / prj-keystore/secret-integration-salt
User photos prj-users / <file> rp-bucket / prj-users/<file>
Plugins rp-bucket / <file>.jar rp-bucket / rp-bucket/<file>.jar

Every 26.0 bucket becomes a folder of the same name. That includes the default bucket itself, which holds the plugins.

The database never stores a bucket. attachment.file_id holds the base64 of the relative path, for example 1/2026-11/<launchUuid>/<file>. 26.0 and 26.1 build that path the same way. Only the step from path to storage changed:

Mode Path in the database 26.0 storage 26.1 storage
multi 1/2026-11/<launchUuid>/<file> bucket prj-1, key 2026-11/<launchUuid>/<file> bucket rp-bucket, key prj-1/2026-11/<launchUuid>/<file>
single project-data/1/2026-11/<launchUuid>/<file> bucket rp-bucket, same key the same, no change

DATASTORE_BUCKETPREFIX is only the folder prefix. It does not have to be prj-, but it must be the value that 26.0 used.

In single mode new attachment keys are:

<DATASTORE_DEFAULTBUCKETNAME>/project-data/<projectId>/<yyyy-M>/<launchUuid>/<file>

A 26.0 install that already used RP_FEATURE_FLAGS: singleBucket keeps its layout. It needs no object copy.

The analyzer always uses one bucket. With the prefix override in x-analyzer-environment, 26.1 stores models at:

<DATASTORE_DEFAULTBUCKETNAME>/analyzer/prj-<projectId>/

The compose file does not move existing model files.

The integration salt is the one object you must not lose. If the API does not find it, it generates a new one and existing integration secrets in the database can no longer be decrypted. In multi mode it is read from <DATASTORE_BUCKETPREFIX>keystore/secret-integration-salt in the default bucket (default prj-keystore/secret-integration-salt). RP_INTEGRATION_SALT_PATH stays keystore.

Option A: Filesystem storage

Use this when 26.0.7 used DATASTORE_TYPE: filesystem. The files stay on the storage volume, mounted at /data/storage on the API and Jobs. The layout is the same, so there is no copy.

  1. Back up PostgreSQL and the storage volume.
docker compose up -d postgres
docker compose exec postgres pg_dump -U rpuser reportportal > backup-26.0.7.sql
docker run --rm -v reportportal_storage:/data alpine tar -czf - -C /data . > storage-backup-26.0.7.tar.gz

If the volume name differs, read it from docker volume ls. A host bind at ./data/storage is archived with tar -czf storage-backup-26.0.7.tar.gz ./data/storage.

  1. Save the file you are about to replace, and note any DATASTORE_* lines you changed. On a default 26.0.7 install the only active line is DATASTORE_TYPE: filesystem in both environment blocks.
cp docker-compose.yml docker-compose.yml.26.0.7
cp .env .env.26.0.7
  1. Check out the 26.1 compose file. Image tags come from .env, not from *_VERSION names. 26.0.7 and 26.1 both read API_IMAGE, JOBS_IMAGE, UI_IMAGE, MIGRATIONS_IMAGE, and ANALYZER_IMAGE. When a variable is unset, the compose file uses its own default (5.15.x on 26.0.7, 6.0.0 on 26.1). If .env pins the old images, point them at 6.0.0.
git fetch origin
git checkout 26.1
API_IMAGE=reportportal/service-api:6.0.0
JOBS_IMAGE=reportportal/service-jobs:6.0.0
UI_IMAGE=reportportal/service-ui:6.0.0
MIGRATIONS_IMAGE=reportportal/migrations:6.0.0
ANALYZER_IMAGE=reportportal/service-auto-analyzer:6.0.0
  1. Confirm x-storage. The shipped block is already the filesystem setup. Leave it as it is unless step 2 found a custom container path.
x-storage: &storage-environment
  DATASTORE_TYPE: filesystem
  DATASTORE_PATH: /data/storage

api and jobs still mount storage:/data/storage. If 26.0.7 used a bind mount, put that bind back on both services. DATASTORE_PATH must be the path inside those containers, not the host path. The analyzer ignores DATASTORE_PATH. Confirm x-analyzer-environment still has FILESYSTEM_DEFAULT_PATH: /data/storage/analyzer and does not set ANALYZER_BINARYSTORE_TYPE. The analyzer-storage volume is mounted at that path.

  1. Start 26.1. --remove-orphans deletes the uat and index containers, which this file no longer defines.
docker compose pull
docker compose up -d --remove-orphans
docker compose logs -f migrations

Wait until the migrations log reports that the migration finished, then check the stack:

docker compose ps

postgres, rabbitmq, opensearch, api, jobs, ui, analyzer, and gateway are running. migrations has exited 0. uat and index are gone.

  1. Sign in through the API. Open http://localhost:8080 and sign in as admin@reportportal.internal with the password you used for superadmin. Open a launch from 26.0 and download an attachment. Scripts that request tokens use /api/sso/oauth/token with client ui:uiman.

Option B: S3-compatible storage

Use this when you run the object store yourself and keep it: external MinIO, SeaweedFS, Ceph RGW, or another S3 API (26.0 DATASTORE_TYPE: minio, or s3 with a custom endpoint). The store stays where it is. You move the settings into x-storage, and for multi you copy inside the store.

In 26.0, multi means one bucket per project (prj-<projectId>). In 26.1, multi keeps the same names but as folders inside the default bucket (rp-bucket/prj-<projectId>/…). 26.1 does not read the 26.0 buckets.

For single (RP_FEATURE_FLAGS: singleBucket), do steps 1, 2, 5, and 6. Skip the copy.

  1. Back up PostgreSQL and save the 26.0.7 compose file, including the DATASTORE_* lines from x-environment and from x-analyzer-environment.
docker compose exec postgres pg_dump -U rpuser reportportal > backup-26.0.7.sql
cp docker-compose.yml docker-compose.yml.26.0.7
cp .env .env.26.0.7
  1. Put the storage settings into x-storage on the 26.1 file. Set the *_IMAGE tags from Option A step 3. Keep the bucket name, prefix, postfix, region, and keys you used in 26.0. Write the secret as DATASTORE_SECRETKEY.
x-storage: &storage-environment
  DATASTORE_TYPE: s3-compatible
  DATASTORE_ENDPOINT: "http://minio:9000"   # scheme and port, as in 26.0
  DATASTORE_REGION: ""
  DATASTORE_ACCESSKEY: ${STORAGE_ACCESSKEY-rpuser}
  DATASTORE_SECRETKEY: ${STORAGE_SECRETKEY-rppassword}
  DATASTORE_DEFAULTBUCKETNAME: rp-bucket
  DATASTORE_BUCKETPREFIX: prj-
  DATASTORE_BUCKETPOSTFIX: ""
  RP_INTEGRATION_SALT_PATH: keystore
  # RP_FEATURE_FLAGS: singleBucket          # only if 26.0 already used it

In x-analyzer-environment, keep FILESYSTEM_DEFAULT_PATH and set the analyzer prefix. Delete ANALYZER_BINARYSTORE_TYPE. Do not set DATASTORE_TYPE or DATASTORE_DEFAULTBUCKETNAME again in that block. The analyzer takes DATASTORE_TYPE from x-storage.

x-analyzer-environment: &common-analyzer-environment
  <<: *storage-environment
  FILESYSTEM_DEFAULT_PATH: &analyzer-default-path /data/storage/analyzer

x-environment must not contain DATASTORE_*. It only merges the anchor:

x-environment: &common-environment
  # ... database and AMQP ...
  <<: *storage-environment
  1. Only for multi: stop the services that write objects.
docker compose stop api jobs analyzer uat

uat is still the 26.0 service at this point. If it is already gone, omit it.

  1. Only for multi: copy inside the store. The copy reads the old buckets and writes folders into the default bucket. The old buckets stay as the rollback copy.
# macOS: brew install minio/stable/mc
# Linux: wget https://dl.min.io/client/mc/release/linux-amd64/mc && chmod +x mc

mc alias set store http://localhost:9000 <access-key> <secret-key>
mc mb --ignore-existing store/rp-bucket

# Plugins that already sit in the default bucket become rp-bucket/rp-bucket/
mc mirror --preserve --exclude "rp-bucket/*" store/rp-bucket store/rp-bucket/rp-bucket

# Every other bucket becomes a folder of the same name
mc mirror --preserve --exclude "rp-bucket/*" store/ store/rp-bucket/

Use your endpoint, keys, and DATASTORE_DEFAULTBUCKETNAME if they are not the defaults above. For a store on another host, set the alias to that URL (https://s3.example.com:443 when the store requires TLS).

Check the salt before you start 26.1. The API reads it once, at start.

mc stat store/rp-bucket/prj-keystore/secret-integration-salt

The result is one folder per old bucket:

rp-bucket/
├── prj-1/
├── prj-keystore/secret-integration-salt
├── prj-users/
└── rp-bucket/
  1. Start 26.1.
docker compose pull
docker compose up -d --remove-orphans
docker compose logs -f migrations
  1. For multi, restart the API and Jobs after the copy. This is required. The API reads the integration salt once, at start, so it must be restarted to use the copied salt. Restarting Jobs is harmless.
docker compose restart api jobs
docker compose ps
  1. Check. Wait until api is healthy, then confirm:
  • an attachment that was uploaded on 26.0 opens
  • the connection test of an existing integration works. This confirms that the old salt is in use
  • the plugins page loads
  • for multi, mc stat store/rp-bucket/prj-keystore/secret-integration-salt still shows the salt you copied
  • you can sign in as admin@reportportal.internal

Option C: Amazon S3

Use this when 26.0.7 used DATASTORE_TYPE: s3 with RP_FEATURE_FLAGS: singleBucket. The bucket and the layout stay the same, so there is no copy.

  1. Back up PostgreSQL and save the compose file, as in Option B step 1.
  2. Move the settings into x-storage. Keep the region, the bucket name, and singleBucket. Keep the keys you use, or leave them empty when the host role (an EC2 instance profile) provides them. The 26.0.7 example name DATASTORE_SECRETSKEY becomes DATASTORE_SECRETKEY.
x-storage: &storage-environment
  DATASTORE_TYPE: aws-s3
  DATASTORE_REGION: us-east-1
  DATASTORE_ACCESSKEY: ""
  DATASTORE_SECRETKEY: ""
  DATASTORE_DEFAULTBUCKETNAME: my-rp-bucket
  RP_FEATURE_FLAGS: singleBucket

Set the analyzer prefix in x-analyzer-environment, as in Option B step 2, if the analyzer used <bucket>/analyzer in 26.0.7. Remove every DATASTORE_* line from x-environment. Set the *_IMAGE tags from Option A step 3.

  1. Start 26.1.
docker compose pull
docker compose up -d --remove-orphans
docker compose logs -f migrations
  1. Check. Wait until api is healthy, then confirm that an attachment from 26.0 opens, and that the connection test of an existing integration works. Sign in as admin@reportportal.internal.

Safety and rollback

  • Back up PostgreSQL before you change the release. For filesystem storage, also back up the storage volume. For multi object storage, the copy only creates folders; it does not delete the original buckets, and those buckets are the rollback copy.
  • The database is not changed by the object copy. The 26.1 migrations change the schema when the new stack starts.
  • To roll back, stop 26.1, return to the 26.0.7 compose file and .env, restore the database, and start that file.
docker compose down
git checkout 26.0.7
cp .env.26.0.7 .env
# If you edited the 26.1 file in place instead of checking out a tag:
# cp docker-compose.yml.26.0.7 docker-compose.yml

docker compose up -d postgres
docker compose exec postgres psql -U rpuser -c "DROP DATABASE reportportal;"
docker compose exec postgres psql -U rpuser -c "CREATE DATABASE reportportal;"
docker compose exec -T postgres psql -U rpuser -d reportportal < backup-26.0.7.sql
docker compose up -d

Filesystem bytes are still on the volume, because 26.1 uses the same mount. For multi, 26.0 reads the original buckets, which the copy left in place.

Known limits

  • Docker Compose does not copy objects and does not rewrite attachment.file_id. The copy in Option B is the only data move. Filesystem and single need none.
  • The analyzer looks for models at <bucket>/analyzer/prj-<projectId>/ after the upgrade. Confirm one model; the compose file does not move it. On filesystem storage the models stay on the analyzer-storage volume at FILESYSTEM_DEFAULT_PATH (/data/storage/analyzer). DATASTORE_PATH does not point at that directory.
  • Leaving ANALYZER_BINARYSTORE_TYPE set makes service-auto-analyzer 6.0.0 log a deprecation warning on start. Remove the variable. The type in use is DATASTORE_TYPE.
  • 26.1 renames the built-in user in the database (superadmin becomes admin@reportportal.internal). Sign in with the new name. Accounts from LDAP or SAML are unchanged. API tokens remain valid.
  • Clients that called /uat/sso/oauth/token call /api/sso/oauth/token instead.
  • The plugin copy leaves the old and the new plugin jar versions side by side under rp-bucket/rp-bucket/. The page still loads. Remove the old jars once you no longer need the 26.0 copies.
  • uat or index still running means the stack was started without --remove-orphans. Run docker compose up -d --remove-orphans again.

Clone this wiki locally