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.
On Linux or macOS, in a terminal:
curl -fsSL https://spitfire.sh | bash -s -- docker --checkOn Windows, in PowerShell:
& ([scriptblock]::Create((irm https://spitfire.sh/ps))) docker -CheckFor Kubernetes write
kubernetesinstead ofdocker. With the bundle already installed,~/spitfire/install.sh docker --check(Windows:& "$env:USERPROFILE\spitfire\install.ps1" docker -Check) works too.Success check: the last line is a green
✔ Prerequisites are met. To install: …and the command exits with 0. If you seeMISSING: N prerequisite(s) not met, apply eachFix: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:
To install Docker on Linux when it is missing:
curl -fsSL https://spitfire.sh | bash -s -- docker --install-dockerTo start Docker when it is installed but stopped:
curl -fsSL https://spitfire.sh | bash -s -- docker --start-dockerTo install k3s on Linux when there is no Kubernetes:
curl -fsSL https://spitfire.sh | bash -s -- kubernetes --install-k3sOn Windows (PowerShell):
& ([scriptblock]::Create((irm https://spitfire.sh/ps))) docker -InstallDocker -StartDockerCheck: the install goes on after the
Docker readyline (Docker Desktop is runningon Windows,k3s cluster readyfor k3s).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.
- The report is shown on screen, then you are asked
Send this error to the support team? … [y/N]. Typeyto send it. - The e-mail address is optional; you can leave it empty.
- Success check: the line
Your report number: IR-XXXXXX; support@usespitfire.comappears; quote that number when you write. If you seeThe 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:
~/spitfire/install.sh --send-report ~/spitfire/logs/spitfire-install-report-20261109-153000.jsonOn 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):
curl -fsSL https://spitfire.sh | bash -s -- docker --with-demoA 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). |