Skip to content

About

Self hosted BreakTest

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

42 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BreakTest Self-Hosted Runtime

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.

Prepare MongoDB 8.3.9 for 9.0.4

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-update

An 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.sh

The 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.

  1. 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.

  2. Test the upgrade in staging, then select MONGODB_VERSION=9.0.4 in config.env (or let the updated scripts select it). Use ./upgrade.sh or ./start.sh so the preflight runs; direct docker compose up bypasses this protection.

  3. 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.

  4. 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})});
    '
  5. 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.

  6. 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.

Requirements

  • Docker Engine
  • Docker Compose v2, or docker-compose
  • openssl
  • Network access to https://breaktest.io for pairing and startup validation

Install

Run the guided installer:

./install.sh

The installer asks for:

  • HTTP port
  • TLS mode: disabled, letsencrypt, or external. letsencrypt asks for the HTTPS port and email address; external is 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.

Public URL and TLS

The externally visible origin and local TLS behavior are configured separately:

BREAKTEST_PUBLIC_URL=https://office.example.com
BREAKTEST_TLS_MODE=letsencrypt

BREAKTEST_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 on HTTP_PORT; the public URL must use http.
  • letsencrypt: Traefik serves HTTPS and obtains a certificate; the public URL must use https, and ports HTTP_PORT and HTTPS_PORT must be reachable.
  • external: an upstream proxy terminates HTTPS and forwards HTTP to HTTP_PORT; the public URL must use https, 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.sh

TimescaleDB configuration

Set 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=2GB

Direct 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.

Images and Versions

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.

Modified k6 component (AGPL-3.0)

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.

Local Load Generator

The guided installer always starts a local load generator. Disable it later by clearing COMPOSE_PROFILES:

COMPOSE_PROFILES=loadgenerator

Leave 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=Default

container 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

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/32

The 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.

AI Assistant

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.sh

Hermes 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.

Operations

Start:

./start.sh

Follow logs:

./start.sh -f

Start with locally built images instead of pulling from Docker Hub:

./start.sh --no-pull -f

start.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-test

Removing 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 -v

TimescaleDB 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/timescaledb

Both 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 -f

Stop that isolated test stack. Docker volumes are preserved:

./stop.sh

Restart one service:

./start.sh -r backend

Upgrade 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.sh

The 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.sh

The 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-update

Stop:

./stop.sh

Self-host release notes

See 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.

Production Notes

  • In letsencrypt mode, 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.env private.
  • Back up Docker volumes and the backups/ directory before upgrades.
  • Support should be tied to official BreakTest images and a valid license.

Licensing

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.

Release notes in update notifications

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.

Opt-in BreakTest DB

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=true

When 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.

Native Rust backend

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.

Copy existing customer results to BreakTest DB

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.

Store BreakTest DB on a separate disk

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-db
BREAKTEST_DB_DATA_PATH=/data/breaktest-db

The 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.

About

Self hosted BreakTest

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages