SpitfireLoad Testing & APMWhat's new

Installer options and requirements

The Installation page covers the one-command path; this page covers what sits behind it: supported systems, machine size, what happens without Docker, every install.sh option and the ports. You do not need to read it top to bottom; go to the heading you are stuck on.

What the installer does

install.sh (install.ps1 on Windows) downloads the installer bundle from spitfire.tr/download, checks its SHA-256 and unpacks it into ~/spitfire; the image comes from Docker Hub (usespitfire/spitfire:<VERSION>, amd64 and arm64). It starts Postgres, the controller and the runners. It generates secrets such as SPITFIRE_SECRET_KEY once and keeps them on every later run, which is why running the same command again is an update.

Requirements

Installation Needs
Docker (Linux/macOS) Docker Engine or Docker Desktop, Docker Compose v2, curl. The user must reach the Docker daemon (on Linux: be in the docker group).
Kubernetes Also kubectl and an active context. Nodes pull the image from Docker Hub; without access, use an internal registry.
Windows Docker Desktop, PowerShell 5.1 or 7, tar.exe (ships with Windows 10 1803 and later).

Operating systems

Platform Versions Architecture
Linux (Docker Engine and Compose v2) Ubuntu 22.04 LTS and later; Debian 12 and later; RHEL, Rocky Linux, AlmaLinux 8 and later; Fedora (current releases) amd64, arm64
macOS (Docker Desktop) macOS 14 Sonoma and later (the last three releases Docker Desktop supports) Apple silicon, Intel
Windows (Docker Desktop, WSL 2) Windows 11 23H2 and later; Windows 10 22H2 (64-bit) x64
Kubernetes (kubectl or Helm 3) Kubernetes 1.28 and later (EKS, AKS, GKE, OpenShift, k3s, RKE2…) amd64, arm64 nodes
Remote runner, Linux without Docker (systemd service) Ubuntu 20.04 and later, Debian 11 and later, RHEL / Rocky / AlmaLinux 8 and later, SUSE Linux Enterprise 15 amd64, arm64
Remote runner, Windows without Docker (Windows service) Windows 10 / 11; Windows Server 2016, 2019, 2022, 2025 x64

Docker Desktop does not run on Windows Server; install Spitfire on a Linux VM there and use Windows Server only for runners.

Hardware

On one machine, Postgres, the controller and the runners share it:

Profile Load Machine Disk
Trial Up to 500 VUs, ~2,000 requests/s 2 vCPU, 4 GB RAM 20 GB
Small team Up to 2,000 VUs, ~10,000 requests/s 4 vCPU, 8 GB RAM 40 GB SSD
Medium Up to 5,000 VUs, ~25,000 requests/s 8 vCPU, 16 GB RAM 80 GB SSD
Large Up to 10,000 VUs, ~50,000 requests/s 16 vCPU, 32 GB RAM 100 GB SSD

We pick half as many runners as vCPUs (--runners 4 on 8 vCPUs). On Kubernetes set aside ~2 vCPU for the controller and Postgres; the default runner pod (2 vCPU / 1 GiB) carries about 10,000 requests/s or 3,000 VUs. How to work it out: Runners → Capacity.

Before installing, the installer says which profile the machine fits and what it will install; below the Trial profile it warns but carries on. On macOS and Windows, Docker's resources are set in Docker Desktop → Settings → Resources.

Check the prerequisites first

The check changes nothing; it marks what is missing with ✗ and a Fix: line.

  1. On Linux or macOS, in a terminal:

    bash
    curl -fsSL https://spitfire.sh | bash -s -- docker --check

    On Windows, in PowerShell:

    powershell
    & ([scriptblock]::Create((irm https://spitfire.sh/ps))) docker -Check

    For Kubernetes write kubernetes instead of docker. With the bundle already installed, ~/spitfire/install.sh docker --check (Windows: & "$env:USERPROFILE\spitfire\install.ps1" docker -Check) works too.

  2. Success check: the last line is a green ✔ Prerequisites are met. To install: … and the command exits with 0. If you see MISSING: N prerequisite(s) not met, apply each Fix: line and repeat step 1.

No Docker or Kubernetes yet

When Docker is missing the installer prints the command it would run, asks, and installs only if you answer y: on Linux through get.docker.com (needs sudo; it adds you to the docker group, which applies once you sign in again), on macOS with brew install --cask docker, on Windows with winget install -e --id Docker.DockerDesktop. When Docker is stopped it offers to start it and waits up to 3 minutes. You accept Docker Desktop's terms on its first start yourself; if Windows asks for a restart for WSL 2, run the command again afterwards. Docker Desktop is paid in companies with more than 250 employees or more than USD 10 million a year in revenue; on Windows the alternative is Docker Engine inside WSL2.

Without a Kubernetes cluster the installer says There is no reachable Kubernetes cluster on this system and, on Linux, offers a single-node k3s (kubeconfig goes to ~/.kube/config, or ~/.kube/spitfire-k3s.yaml when that file exists; remove it with sudo /usr/local/bin/k3s-uninstall.sh). With a context that is configured but unreachable, k3s is not offered and the error is printed.

With no terminal (CI, --offline) nothing is asked, and --yes does not install Docker. To have it done without a question, give the option explicitly:

  1. To install Docker on Linux when it is missing:

    bash
    curl -fsSL https://spitfire.sh | bash -s -- docker --install-docker
  2. To start Docker when it is installed but stopped:

    bash
    curl -fsSL https://spitfire.sh | bash -s -- docker --start-docker
  3. To install k3s on Linux when there is no Kubernetes:

    bash
    curl -fsSL https://spitfire.sh | bash -s -- kubernetes --install-k3s
  4. On Windows (PowerShell):

    powershell
    & ([scriptblock]::Create((irm https://spitfire.sh/ps))) docker -InstallDocker -StartDocker
  5. Check: the install goes on after the Docker ready line (Docker Desktop is running on Windows, k3s cluster ready for k3s).

    bash
    docker info --format '{{.ServerVersion}}' && echo OK

Sending the error to support

When the installer stops at a step it prints ERROR: and Fix: lines and, at the bottom, an error code such as SF-{{version}}-L355 (ending in -W on Windows). If you cannot fix it, it offers to send the error to support; nothing is sent without your yes.

  1. The report is shown on screen, then you are asked Send this error to the support team? … [y/N]. Type y to send it.
  2. The e-mail address is optional; you can leave it empty.
  3. Success check: the line Your report number: IR-XXXXXX; support@usespitfire.com appears; quote that number when you write. If you see The report could not be sent, e-mail the file named on that line to support@usespitfire.com.

Without a terminal (--yes, CI) nothing is sent; the installer prints the command that sends it later:

bash
~/spitfire/install.sh --send-report ~/spitfire/logs/spitfire-install-report-20261109-153000.json

On Windows: & "$env:USERPROFILE\spitfire\install.ps1" -SendReport <file>; for an e-mail add --report-email you@example.com (-ReportEmail).

The report is a JSON file in the logs folder, readable only by you, and it is everything that would be sent: version, system, step, error code, message and the last 16 KB of the log. Passwords, tokens, license keys and the setup code become [redacted] before the file is written. In the wizards, Send error report in the error window sends the same report. To never be asked, set SPITFIRE_REPORT=off.

Demo target

If you have no system to test yet, run the installer with --with-demo (Windows: -WithDemo; the old name --demo works too):

bash
curl -fsSL https://spitfire.sh | bash -s -- docker --with-demo

A small demo app that only the local runners reach is installed next to Spitfire: an HTTP API (/api/items, /ocpp/{id} for OCPP) and a demo store (/store). The store's search deliberately runs on a connection pool of 2 connections; above 90 searches a second it returns 503. The first steps list on Load Testing → Dashboard starts the bundled "Demo store: find the breaking point" test; in under two minutes the report shows the load where it broke and the slow step. The HTTP and OCPP templates on Tests → From a template point at this address too.

The setting is kept on updates; to remove it, ~/spitfire/install.sh docker --no-demo. There is no demo app on Kubernetes or Helm. To try Spitfire without installing, Open the demo on the sign-in page opens the shared read-only demo, reset every night (off on your own installation, SPITFIRE_DEMO_MODE).

Installer options

~/spitfire/install.sh --help lists them all; on Windows use the PowerShell spelling of the same name (--runners → -Runners).

Option Meaning
--port 8480 --grpc-port 8481 Docker: UI and runner ports (default 8470/8471)
--runners N Number of local runners (default 2)
--location NAME Location of the local runners (default local; a-z 0-9 - _ .)
--with-demo / --no-demo Docker: install / remove the demo app
--updater on|off Docker: one-click update (off by default)
--install-docker, --start-docker, --install-k3s Install / start Docker or k3s without asking (details)
--otlp-grpc-port 4327 Docker: the OTLP/gRPC port (default 4317; a taken one gives way to a free port, the UI shows it)
--tower on|off Docker: Tower and Collector for server metrics (off by default; --tower-port 4318)
--grpc-public-addr HOST:PORT The address remote runners dial (on Docker the LAN IP by default)
--version V / --image IMAGE Another release / a specific image
--offline FILE Install or update from an offline bundle (Updating without internet)
--admin-email E --admin-password P Create the first admin during installation (password at least 8 characters)
--no-backup Do not back up the database when updating
--rollback [DUMP] Roll the last update back
--support-bundle Installs nothing; prepares a support bundle (zip)
-y, --yes Do not ask for confirmation
SPITFIRE_DIR=/opt/spitfire Installation folder (default ~/spitfire)
SPITFIRE_LANG=en / tr Language of the installer and the UI (default: the system's language; on update, the earlier installation's)

Variables go before bash; before curl they never reach the script: curl -fsSL https://spitfire.sh | SPITFIRE_LANG=en bash -s -- docker.

Ports and network

Port For Who must reach it
8470 (Docker; NodePort 30470 on Kubernetes) Web UI and REST API Users, CI pipelines
8471 gRPC endpoint remote runners connect to, TLS Runner servers in other locations (inbound TCP)
4317 OTLP/gRPC receiver (OTLP/HTTP is on 8470 under /otlp); TLS when SPITFIRE_OTLP_GRPC_TLS_CERT/_KEY are given Services and Collectors sending traces, metrics and logs
8475 Plaintext gRPC for runners on the same machine/cluster Only the installation's own runners; never published
8472 (optional) Mock services (turned on with SPITFIRE_MOCK_ADDR) The system under test

Runners connect out to the controller; no inbound port is needed on a runner server. Network settings:

Variable When
SPITFIRE_PUBLIC_URL The address in notification and e-mail links (e.g. https://spitfire.company.com). An address saved under Admin → Integrations → Settings → General wins.
SPITFIRE_TRUSTED_PROXIES CIDR list of a proxy on a public address in front (cloud load balancer, Cloudflare). Without it the audit log and sign-in limits see the proxy's address; X-Forwarded-For is read only from loopback and private networks.
SPITFIRE_TRUST_PRIVATE_NETWORKS=false Users come from a private network with no proxy; only the proxies you declared may set the client address.
SPITFIRE_SIGNIN_BURST Many users behind one NAT. One address may try 30 times at once, then once every 2 s; this variable raises the 30. Per account: 10 wrong passwords, then one a minute.
SPITFIRE_ALLOW_LINK_LOCAL=1 The system under test lives on a link-local address (on the runners).
SPITFIRE_EGRESS=public-only Shared environments that test only internet targets; localhost and private addresses are refused too. On-prem installs do not need it.

Neither the controller nor test steps reach link-local and cloud metadata addresses (169.254.0.0/16, fe80::/10, fd00:ec2::254, 100.100.100.200); such a request fails with link-local and cloud metadata addresses are not allowed. In public-only mode the error adds this installation reaches only public internet addresses. In Helm, --set networkPolicy.egress=public-only also adds egress NetworkPolicies; give networkPolicy.kubeAPICIDR for on-demand runners and list an internal database, SMTP relay or SSO in networkPolicy.controllerAllowCIDRs.

TLS and runner pin basics

Port 8471 is always TLS. The controller creates its identity on first start and stores it encrypted with SPITFIRE_SECRET_KEY; a remote runner verifies it by its pin (sha256:…). The pin and the ready-made command are in the key dialog on the Runners page. For your own certificate give SPITFIRE_GRPC_TLS_CERT and SPITFIRE_GRPC_TLS_KEY; runners then use --tls or --ca <PEM file>. Details: Runners → TLS pin and certificates.

Common problems

The most common one: the user was added to the docker group but has not signed in again, so the installer cannot reach the daemon. Signing out and in is enough.

Symptom Cause Fix
ERROR: Docker Compose not found. The Compose v2 plugin is not installed. Install the plugin: https://docs.docker.com/compose/install/
ERROR: Could not pull the image: usespitfire/spitfire:... The machine cannot reach Docker Hub, or the version is wrong. Try docker pull; behind a proxy, configure the Docker daemon's proxy (Installing behind a proxy); check the version.
The sign-in page opens instead of the setup screen: "Setup is already complete". The first admin already exists (perhaps through --admin-email). Sign in with that account; if its password is unknown, run spitfire-controller reset-password on the server: Users and access.
ERROR: The controller was not ready within 180 s. The controller failed while starting (database, missing setting…). Read the log with docker compose -p spitfire -f ~/spitfire/deploy/docker/docker-compose.yml logs -f controller; if you cannot solve it, prepare a support bundle with ~/spitfire/install.sh --support-bundle (Troubleshooting).