This repository contains the public deployment bundle for running BreakTest from prepared Docker images. It does not contain application source code.
Note: This repository is a generated release artifact. Its content is maintained in the BreakTest source repository (
deploy/selfhost/) and published here by the release pipeline, one commit per release. Direct commits or pull requests against this repository will be overwritten by the next release — please report issues to BreakTest support instead.
The updated lifecycle scripts target MongoDB 9.0.4 (verified on 2026-10-21). They inspect the existing standalone server before Compose removes its container. FCV is server-wide: customers on the same server share it. Each independent installation is checked separately.
For customers upgrading from a bundle whose upgrade.sh predates staged
MongoDB upgrades, use this one-time bootstrap:
git pull --ff-only && ./upgrade.sh --no-bundle-updateAn already-running old script continues its old code after downloading a new
script. It cannot run the new preflight during that invocation. To keep this
path safe, Compose defaults to 8.3.9 when no MONGODB_VERSION is configured.
If a customer runs only the old upgrade.sh, that first invocation safely
updates the backend on MongoDB 8.3.9; migration 17 prepares FCV 8.3. Run the
now-updated upgrade.sh again to finish the 9.0.4 upgrade. Updated launchers
restart themselves after git pull, so subsequent bundle upgrades run the
new code immediately.
After preflight succeeds, the updated scripts persist MONGODB_VERSION=9.0.4
in config.env before starting MongoDB. This prevents later Compose calls from
selecting the 8.3 fallback. An explicit 8.3.9 pin is respected; remove it or
select 9.0.4 when ready. The upgrade waits for service health before cleaning
up superseded images.
The automatic sequence is:
- An 8.2 server at FCV 8.2 first starts MongoDB 8.3.9 on the same volume.
- An 8.3 server at FCV 8.2 advances to FCV 8.3, which is read back and verified.
- An 8.3 server already at FCV 8.3 proceeds directly to MongoDB 9.0.4.
- A 9.0 server at FCV 8.3 or 9.0 is left prepared; it is never downgraded.
- A fresh installation without an existing data volume starts 9.0.4 directly.
Authentication failures, unsupported versions, replica sets/sharded deployments,
and unfinished FCV transitions stop the upgrade. After each verified check and
successful start, the scripts record the server version and FCV in
.breaktest-mongodb-state inside the MongoDB data volume. ./stop.sh now
stops all profiles without removing containers, retaining the original MongoDB
binaries for the next preflight. Startup verifies that the running MongoDB version
matches the requested image before reporting success.
If containers are removed manually with docker compose down, the saved marker
selects the recovery binaries. The script starts that version and reads the live
FCV before allowing an upgrade, including an unfinished preparation at FCV 8.2.
A stale marker never authorizes the target version by itself.
For a legacy volume with neither a container nor a marker, supply the known previous server version once. For the office installation previously running 8.3.9:
MONGODB_RECOVERY_VERSION=8.3.9 ./start.shThe recovery override selects only the initial binaries; the normal staged upgrade then runs automatically. It does not persist an 8.3 target in config.env. Unknown or unsupported versions are refused instead of guessed. Do not select an older version for a volume already upgraded to 9.0.
Platform migration 17 remains an idempotent fallback and records completion when the backend starts. Deploying a separate intermediate backend release is not required. FCV 9.0 remains an explicit operator action for existing databases. No application document rewrite is required by the compatibility changes identified in the current backend queries.
-
Schedule a maintenance window and finish active tests. Take a consistent database backup and test restoring it into an isolated deployment. Retain the deployment configuration and application images. Never copy a live WiredTiger data directory as a backup.
-
Test the upgrade in staging, then select
MONGODB_VERSION=9.0.4inconfig.env(or let the updated scripts select it). Use./upgrade.shor./start.shso the preflight runs; directdocker compose upbypasses this protection. -
Watch for the verified FCV 8.3 message before the 9.0 container starts. If preparation fails, resolve the reported state and retry. The script does not continue to 9.0 or automatically roll back failed database transitions.
-
Check the running database:
docker exec mongodb mongosh --quiet --eval ' const admin = db.getSiblingDB("admin"); if (!admin.auth(process.env.MONGO_INITDB_ROOT_USERNAME, process.env.MONGO_INITDB_ROOT_PASSWORD)) throw new Error("Authentication failed"); printjson({server: db.version(), fcv: admin.runCommand({getParameter: 1, featureCompatibilityVersion: 1})}); '
-
Verify MongoDB health and logs, backend health, login, customer/scenario/test reads and writes, a short test run, and backup/restore with tools supporting MongoDB 9.0. For upgraded databases, expect server 9.0.4 and FCV 8.3; fresh databases start at FCV 9.0. Retain FCV 8.3 during a burn-in period.
-
Once the deployment is validated and a return to 8.3 is no longer expected, explicitly enable the 9.0 features:
docker exec mongodb mongosh --quiet --eval ' const admin = db.getSiblingDB("admin"); if (!admin.auth(process.env.MONGO_INITDB_ROOT_USERNAME, process.env.MONGO_INITDB_ROOT_PASSWORD)) throw new Error("Authentication failed"); const result = admin.runCommand({setFeatureCompatibilityVersion: "9.0", confirm: true}); if (!result.ok) throw new Error(JSON.stringify(result)); printjson(result); '
Do not roll back by simply changing the image tag after enabling FCV 9.0. Follow MongoDB's downgrade procedure, including removing incompatible features and lowering FCV while the 9.0 server is still running, or restore the tested pre-upgrade backup into a separate 8.3 deployment. Even during burn-in, use the documented downgrade checks and a clean shutdown before replacing binaries.
References: 9.0 release notes, standalone upgrade, compatibility changes, driver compatibility.
- Docker Engine
- Docker Compose v2, or
docker-compose openssl- Network access to
https://breaktest.iofor pairing and startup validation
Run the guided installer:
./install.shThe installer asks for:
- HTTP port
- TLS mode:
disabled,letsencrypt, orexternal.letsencryptasks for the HTTPS port and email address;externalis for an upstream proxy that terminates HTTPS and forwards HTTP to this stack - The public URL users and remote load generators use to reach BreakTest, with detected local IP addresses offered as choices
- Service timezone, prefilled from the host machine when detectable
A local load generator is always included. It is labeled Local and allowed to
run synthetic monitoring. Container mode is preferred because each JMeter or K6
test runs in its own workload container. When a load-generator image is already
local, the installer probes whether a Docker socket can be bind-mounted and
selects process mode if the probe fails. On a first install, ./start.sh
performs that probe immediately after pulling the image and falls back to
process mode if needed.
It writes config.env and generates local MongoDB, PostgreSQL, JWT, and credential-encryption secrets.
Image namespace, Compose project name, single-customer generator scope,
Docker-managed TimescaleDB storage, and disabled AI are safe installer defaults.
They remain editable in config.env after installation.
The configured timezone controls service logs, PostgreSQL defaults, and the
daily retention cleanup schedule (03:00 in that timezone). Dates in the web
interface are rendered in each viewer's browser timezone.
Full backups are written to BACKUP_PATH. Each archive includes config.env
alongside MongoDB, PostgreSQL, and Grafana data so restore has the matching
secrets. Fresh generated configurations keep the two newest timestamped
archives with LOCAL_BACKUP_RETENTION_COUNT=2; an older config.env without
that key keeps all existing archives on its first run. For Hetzner Storage Box,
BACKUP_INSTALLATION_NAME is optional for backward compatibility: leaving it
empty preserves the old remote directory, while setting a unique name stores
new backups below that name.
Run a backup from the bundle directory with ./full_backup.sh. Manual backups
should run in a durable shell or service session: interrupting the command
aborts the backup and terminates only the database dump sessions owned by that
run. MAX_PARALLEL controls concurrent PostgreSQL dumps, while
BACKUP_DISK_HEADROOM_GB adds free-space headroom to the preflight check.
When BreakTest DB is enabled, the backup also contains its results volume
(breaktest_db_data.tar). Restore those results with
./restore_breaktest_db.sh backups/full_backup_<timestamp>.tar, together with
MongoDB from the same archive; existing results are never overwritten.
The externally visible origin and local TLS behavior are configured separately:
BREAKTEST_PUBLIC_URL=https://office.example.com
BREAKTEST_TLS_MODE=letsencryptBREAKTEST_PUBLIC_URL is the canonical origin for application links, secure
cookies, and external load-generator connections. BreakTest automatically maps
https to wss and http to ws.
BREAKTEST_TLS_MODE accepts:
disabled: Traefik serves HTTP onHTTP_PORT; the public URL must usehttp.letsencrypt: Traefik serves HTTPS and obtains a certificate; the public URL must usehttps, and portsHTTP_PORTandHTTPS_PORTmust be reachable.external: an upstream proxy terminates HTTPS and forwards HTTP toHTTP_PORT; the public URL must usehttps, and this stack does not publish port 443.
Upgrades automatically migrate legacy CONTROLLER_HOST, ENABLE_SSL, and
ENABLE_HTTPS settings to the canonical variables and retain a timestamped
backup of config.env. Legacy Traefik values matching the generated defaults
are removed; customized TRAEFIK_* values are preserved and reported during
startup. Contradictory legacy SSL flags fail with a clear error instead of
silently selecting an insecure connection.
Then start:
./start.shSet database tuning values in config.env, then run ./start.sh to recreate
services whose Compose configuration changed. A plain container restart does
not apply a changed Compose command. Schedule this outside active tests because
recreating TimescaleDB interrupts database connections.
The self-host bundle now passes POSTGRES_MAX_WAL_SIZE, POSTGRES_WAL_LEVEL,
POSTGRES_MAX_WAL_SENDERS, TIMESCALEDB_ENABLE_DIRECT_COMPRESS_COPY,
TIMESCALEDB_ENABLE_IN_MEMORY_RECOMPRESSION, and
TIMESCALEDB_ENABLE_DIRECT_COMPRESS_ON_CAGG_REFRESH to PostgreSQL. Older bundles
ignored these keys even when they were present in config.env.
For compression parity with the original source deployment's sample configuration:
TIMESCALEDB_ENABLE_DIRECT_COMPRESS_COPY=true
TIMESCALEDB_ENABLE_IN_MEMORY_RECOMPRESSION=true
TIMESCALEDB_ENABLE_DIRECT_COMPRESS_ON_CAGG_REFRESH=true
POSTGRES_MAX_WAL_SIZE=2GBDirect COPY compression affects eligible new writes; it does not retroactively
compress all existing data. Direct COPY and aggregate-refresh compression now
default to enabled in both deployments, matching the source sample configuration.
Existing explicit false values remain effective; change them to true to
use compression. Set either flag to false to disable that feature.
WAL settings are independently configurable. Self-host defaults are
POSTGRES_WAL_LEVEL=minimal and POSTGRES_MAX_WAL_SENDERS=0, matching the
original source deployment. Use this pair only when replication and
point-in-time recovery are not required. Changing wal_level to minimal
requires max_wal_senders=0 and affects backup/recovery capabilities.
With minimal and non-zero senders, PostgreSQL refuses to start. Both
start.sh and upgrade.sh reject this combination before recreating services.
Existing explicit values are preserved; set replica or logical explicitly
when replication/PITR is required. WAL is
still generated for ordinary writes to existing tables with minimal.
POSTGRES_MAX_WAL_SIZE now defaults explicitly to 1GB; preserve an existing
custom or image-tuned value in config.env if needed.
Check effective settings in the affected customer database after recreation:
SHOW timescaledb.enable_direct_compress_copy;
SHOW timescaledb.enable_in_memory_recompression;
SHOW timescaledb.enable_direct_compress_on_cagg_refresh;
SHOW wal_level;
SHOW max_wal_senders;
SHOW max_wal_size;Matching these six settings does not reproduce source-deployment performance
by itself. Fresh self-host and source samples still differ in worker processes
(64 vs 128), parallel workers (16 vs 24), TimescaleDB background workers (32 vs
96), and work_mem (64MB vs 128MB). These are intentional sizing differences;
compare effective settings on both servers and explicitly match the benchmark's
resource configuration, which may also differ from either sample.
Existing config.env files are not rewritten by this change. Previously ignored
values in them now take effect; inspect those values before applying the updated
bundle. Database/role overrides and persisted PostgreSQL configuration should
also be considered when comparing deployments.
The compose file pulls BreakTest runtime images from Docker Hub:
breakingit/breaktest-backend:${BREAKTEST_BACKEND_VERSION}
breakingit/breaktest-frontend:${BREAKTEST_FRONTEND_VERSION}
breakingit/breaktest-ai-assistant:${BREAKTEST_AI_ASSISTANT_VERSION}
breakingit/breaktest-loadgenerator:${BREAKTEST_LOADGENERATOR_VERSION}
breakingit/breaktest-pg-proxy:${BREAKTEST_PG_PROXY_VERSION}
The bundle release version is pinned in BREAKTEST_VERSION. Each image also
has its own version in version.env, because unchanged images are reused from
the previous release instead of being rebuilt and republished. The release
pipeline writes these values; do not edit version.env by hand.
To temporarily run a different version (rollback, release candidate), set
BREAKTEST_VERSION in config.env; it takes precedence over all per-image
versions in version.env. Remove the override to follow bundle releases again.
The optional BreakTest load generator includes a modified version of Grafana k6. The complete corresponding source code for Breaking-IT's modified k6 component, including the build scripts and the GNU Affero General Public License v3.0 text, is publicly available at Breaking-IT/k6.
The fork's breakingit branch contains
the current source and immutable source-release tags are published there. This notice applies
to the k6 component only; it does not change the license terms for other BreakTest components.
The guided installer always starts a local load generator. Disable it later by
clearing COMPOSE_PROFILES:
COMPOSE_PROFILES=loadgeneratorLeave COMPOSE_PROFILES empty if this controller should run without a local generator.
The local load generator can be scoped in config.env:
LOAD_GENERATOR_RUN_MODE=container
# LOAD_GENERATOR_DOCKER_SOCKET=/var/run/docker.sock
# LOAD_GENERATOR_CPU_LIMIT=4.0
# LOAD_GENERATOR_MEMORY_LIMIT=4096m
LOAD_GENERATOR_PUBLIC=false
LOAD_GENERATOR_CUSTOMER_NAME=Defaultcontainer is preferred because every JMeter or K6 test runs in its own
workload container. When the image is available, the installer probes whether
a Docker socket can actually be bind-mounted (preferring
/var/run/docker.sock inside Docker Desktop or Colima VMs over the macOS
client path from DOCKER_HOST / docker context inspect). On a first install,
./start.sh performs the real probe after pulling the image. It also repeats
the check on later starts and falls back to process mode if the socket is no
longer mountable.
Set LOAD_GENERATOR_DOCKER_SOCKET only when the probe must use a specific
path. The optional CPU and memory limits cap the load generator; container-mode
test workloads inherit the same limits.
The guided installer always keeps the local generator private to the default
customer. Service-provider deployments can change these advanced settings in
config.env after installation.
Grafana is disabled by the guided installer. To enable it later, set:
GRAFANA_ENABLED=true
GRAFANA_ADMIN_PASSWORD=choose-a-strong-password
GRAFANA_IP_ALLOWLIST=127.0.0.1/32,::1/128,203.0.113.10/32./start.sh adds the grafana Compose profile, serves Grafana at
/grafana on the public URL, provisions the BreakTest System Monitoring
dashboard and a Timescale datasource for breaktest_monitoring, and generates
credentials for the dedicated graf_breaktest_monitoring_ro database role.
Sign in as admin with GRAFANA_ADMIN_PASSWORD.
Traefik only accepts Grafana traffic from GRAFANA_IP_ALLOWLIST
(localhost only by default). Bare IPs are expanded to /32 or /128.
Grafana state is stored in the grafana_data Docker volume.
When BREAKTEST_TLS_MODE=external, also configure the IP or network of the
upstream reverse proxy:
TRAEFIK_TRUSTED_PROXY_IPS=10.0.0.10/32The proxy must send X-Forwarded-For with the real client address. BreakTest
trusts that header only when the request comes from TRAEFIK_TRUSTED_PROXY_IPS;
the Grafana allowlist then checks the forwarded client address. Never set this
to an unrestricted range such as 0.0.0.0/0.
The AI assistant is disabled by the guided installer. To select an inference provider, authenticate, and choose a model, run this from the Selfhost bundle directory:
./ai-setup.shHermes presents its provider and model picker inside a one-off AI-assistant
container. For an OpenAI subscription, choose OpenAI, then OpenAI Codex;
Hermes prints an OpenAI device URL and one-time code for login. Provider
configuration and credentials are stored only in the project-scoped Hermes
Docker volume. config.env contains no OpenAI tokens, provider API keys, or AI
model selection. The command enables the ai-assistant Compose profile and
starts the stack. Re-run it to change provider/model or re-authenticate.
Backend access also requires a BreakTest license with the AI assistant entitlement enabled.
Start:
./start.shFollow logs:
./start.sh -fStart with locally built images instead of pulling from Docker Hub:
./start.sh --no-pull -fstart.sh checks for free disk space before Docker pulls or starts the stack,
waits for the database and backend health checks, and exits with service logs if
they do not become healthy. The default safety threshold is 2 GiB and can be
changed with BREAKTEST_MIN_FREE_DISK_GB. The startup health-check budget can
be increased for large installations with
BREAKTEST_STARTUP_HEALTH_TIMEOUT_SECONDS (default: 300 seconds). A
./start.sh --restart <service> operation skips the full-stack health wait.
Set a static Docker Compose project name in config.env to isolate containers and volumes:
BREAKTEST_COMPOSE_PROJECT_NAME=breaktest-selfhost-testRemoving the self-host directory does not remove Docker named volumes. For a deliberate, destructive fresh reset, stop the stack and remove its project volumes explicitly (after taking any needed backups):
./stop.sh
docker compose --env-file version.env --env-file config.env \
-f docker-compose.yaml -p "${BREAKTEST_COMPOSE_PROJECT_NAME:-breaktest}" down -vTimescaleDB uses the project-scoped Docker volume by default. To store its
database on a dedicated host disk, configure an absolute path in config.env:
POSTGRES_DATA_PATH=/data/timescaledbBoth start.sh and upgrade.sh preserve this setting and validate/create the
directory before starting TimescaleDB. Stop the stack before changing this
setting on an existing installation; changing it selects a different
PostgreSQL data directory and does not copy data automatically.
Then start an isolated local test stack with its own Docker volumes:
./start.sh --no-pull -fStop that isolated test stack. Docker volumes are preserved:
./stop.shRestart one service:
./start.sh -r backendUpgrade to the latest release (updates the bundle via git pull, then pulls
the images pinned by the new version.env, restarts services, and removes the
superseded images after the replacement stack starts successfully):
./upgrade.shThe backend checks the public self-host version.env once per day for a newer
stable release. SuperAdmins receive one release notification, with upgrade steps,
under Menu → Notifications, including in single-tenant installations. The
hamburger badge refreshes every minute. Other users cannot see release alerts.
The check compares the installed bundle's BREAKTEST_VERSION, not individual
image versions (which may be reused between releases). It never upgrades automatically.
Deleting an alert does not cause the same release to be announced again.
Set BREAKTEST_RELEASE_CHECK_ENABLED=false in config.env and recreate the
backend container to disable outbound release checks, for example on offline
installations. Failed checks leave the platform running and retry on the next
daily check. Only public release metadata is fetched; no installation or customer
data is sent. The source checkout reports its latest Git release tag through
start.sh; if no stable installed version is available, the first observed
release becomes a baseline and only subsequent releases produce notifications.
Immediately before recreating containers, the upgrade checks the running
installation for load generators reporting running, starting, paused, or stopping
work, or nonempty active run IDs. Stale/disconnected active reports are flagged
as uncertain. Unfinished tests started within the last two hours (with or without metrics)
also warn, including when an agent restart has lost its active run IDs. Older unfinished
test records alone do not trigger the guard. This is a conservative warning,
not a maintenance lock or a cleanup of historical records.
If activity or uncertainty is found, it lists up to 20 records and asks
Continue with upgrade? [yes/stop] (default: stop):. Enter yes to proceed and
interrupt the tests, or stop to cancel the upgrade without restarting containers.
An empty answer or end-of-input also cancels. If test state cannot be checked,
the script reports that uncertainty and requires the same explicit confirmation.
For unattended upgrades, explicitly opt in to interrupting tests (or continuing
when their state cannot be checked):
BT_UPGRADE_ASSUME_YES=1 ./upgrade.shThe check and warning still run. Only the exact value 1 bypasses the
interruption prompt; unset or other values retain the safe default. This
variable applies to both upgrade scripts and does not answer the source
checkout's separate git-pull prompt.
Builds/image pulls and bundle updates already completed are not rolled back.
The source checkout's upgrade.sh uses the same check before stopping services.
Pull and restart at the currently pinned version without updating the bundle:
./upgrade.sh --no-bundle-updateStop:
./stop.shSee CHANGELOG.md for self-host release notes. Release notifications in self-host installations link to this document; source/development notifications do not. Historical notes have not been backfilled.
Before publishing a self-host release, maintainers should replace the placeholder
under Unreleased with reviewed, user-facing changes, fixes, and any required
upgrade actions. Move those notes under a ## <version> - <date> heading matching
BREAKTEST_VERSION, and start a fresh Unreleased section. Include changes in
application images shipped by the bundle, even when only some images change.
Both the release workflow and scripts/release_selfhost.sh copy this file into
the public self-host repository with the rest of the bundle.
- In
letsencryptmode, DNS for the public URL hostname must point at the server and ports 80/443 must be reachable for Let's Encrypt HTTP-01 validation. - Do not mount application source code into runtime containers.
- Keep
config.envprivate. - Back up Docker volumes and the
backups/directory before upgrades. - Support should be tied to official BreakTest images and a valid license.
Start BreakTest, sign in as the interactive SuperAdmin, and open Platform → License. Pair the installation with your breaktest.io account, approve its short code in /portal, create or select a license there, then refresh and activate it in BreakTest. Portal credentials and raw license keys are never stored in Selfhost.
Official Selfhost images contact https://breaktest.io at every backend start. If that check fails because of a connection problem or HTTP 5xx response, BreakTest may continue using its last signed license until 72 hours after the last successful license validation, including across restarts. A definitive license-server rejection (for example, an expired, revoked, or unavailable license) clears that grace immediately. The License page remains available while restricted or operating in grace.
Stable releases publish a generated CHANGELOG.md and releases.json alongside
version.env, after the required image builds and tests succeed. The daily
SuperAdmin update notification includes the available notes for every release
newer than the installed version, including upgrade requirements. The notes are
read from the advertised release's immutable tag. Releases from before this
history was introduced may not have notes; missing coverage is labelled.
The check never installs updates automatically.
The release pipeline publishes breakingit/breaktest-db for Linux amd64 and
arm64 alongside the other images. version.env pins BREAKTEST_DB_VERSION;
the standard global BREAKTEST_VERSION override also applies to this image.
Use a bundle released with BreakTest DB support; older releases do not have this image.
To enable the service in a self-host installation, set in config.env:
BREAKTEST_DB_ENABLED=trueWhen upgrading an existing configuration, ./start.sh and ./upgrade.sh replace the
former BREAKTEST_DB_APPLICATION_PREVIEW flag in config.env with BREAKTEST_DB_ENABLED
(1 becomes true). true/false are preferred; 1/0, yes/no and on/off are
also accepted in any case, and any other value stops startup. Keep the existing admin token.
No volume or customer setting needs to change.
Then run ./start.sh (or ./upgrade.sh to install the new bundle first). The scripts
add the breaktest-db profile before pulling images and generate/persist an admin
token if missing. The backend and the local load generator use the internal service
URL; remote load generators automatically write through BREAKTEST_PUBLIC_URL and
Traefik, the same rule as the TimescaleDB proxy. Set BREAKTEST_DB_INGEST_URL only
to send every generator to another origin. Only producer POST routes are exposed;
administration/query endpoints remain inside the Docker network.
One ordered ingestion lane per generator is used by default to avoid multiplying
watermark traffic for distributed fleets. Extra lanes can help individual
generators with upload throughput constraints; benchmark before increasing them.
BREAKTEST_DB_LANES is an optional tuning override (1–4), not a required setting.
The breaktest_results named volume stores portable results; the backend mounts it
read-only for results/backup and separately for restore. Do not remove this volume
when stopping/upgrading. The ordinary load-generator image now includes the BreakTest DB
k6 writer and the BreakTest/JMeter-fork listener, alongside TimescaleDB support.
After upgrading existing generators, choose the customer storage setting in the UI.
TimescaleDB remains the default; no customer settings or existing results are migrated by installation or upgrade.
The backend service runs the complete Rust backend by default. No backend-selection
flags or native-control overlay are required. Run ./start.sh or ./upgrade.sh;
existing data volumes and the service name remain unchanged. The backend image is
breaktest-backend, with its version pinned through BREAKTEST_BACKEND_VERSION.
Releases up to v26.11.1 published the Python backend under that name and the Rust
backend as breaktest-backend-api-rs; the bundle's compose file and version.env
always refer to the right one. The backend applies schema migrations itself
when it starts. A migration failure leaves the backend stopped; fix the failure and
rerun startup. Back up existing data before upgrading.
Upgrading from a release older than v26.10.3 is a stop-over upgrade: first upgrade to v26.11.1 (it applies the historical database migrations), then to this version. The backend refuses to start on an older database and says so.
BACKEND_NATIVE_UID/BACKEND_NATIVE_GID default to the previous Python container's root
identity to retain access to existing backup/results files without changing their ownership.
You can configure a non-root identity after granting it access to those shared directories.
Historical repair scripts remain offline utilities, and the NeoLoad/HAR converter
implementations are unchanged by this control migration.
Use ./migrate_customer.sh plan --customer CUSTOMER_ID, followed by
./migrate_customer.sh copy --customer CUSTOMER_ID --test TEST_ID to validate one
completed test before copying the customer. The wrapper uses the running deployment's
configuration and storage volume. It leaves TimescaleDB intact and enables verified
copies through the customer's Results storage setting.
See migration requirements, commands and rollback.
By default results use the existing breaktest_results Docker volume. To use a
host directory, prepare an absolute path owned by the storage UID/GID and set:
sudo install -d -o 1000 -g 1000 -m 750 /data/breaktest-dbBREAKTEST_DB_DATA_PATH=/data/breaktest-dbThe directory overrides the named volume for the store, backend read/restore mounts,
full backup and restore scripts. The migration wrapper follows the running store's
mount and checks it against the backend configuration. Leave the setting blank to
keep named-volume behavior, including BREAKTEST_DB_VOLUME_NAME.
For an existing installation, do not simply change the setting and start. Wait
for tests to finish and stop the backend and BreakTest DB so ingestion, finalization,
retention and deletion cannot change files. Copy the entire old results volume to
the new directory, preserving ownership and permissions. Verify file counts and
checksums before setting the path and recreating both services with start.sh.
Check health and historical results before allowing tests again. Keep the old volume
for rollback; remove it only after you no longer need that copy. Rollback after new
writes requires reconciling those writes, not just clearing the path setting.
Startup and backup/restore reject missing or relative configured paths. They do not silently select a different empty directory. On Linux the storage process runs as UID/GID 1000 and needs write permission on the destination. The path is on the Docker host, not inside the container. Backups keep the same archive layout whether results use a named volume or a host directory.