Getting started — what to do, in which order

Spitfire is a self-hosted, distributed load testing platform with a web UI. You define a test step by step in the UI; runners in one or more locations generate the load; you watch the results live — p95/p99 latency, RPS and error rate — and a threshold decides pass or fail.

This page is a roadmap: it tells you in which order to do things, from installation to the first load test and on to CI/CD. Each step has its own detailed page; open it when you get stuck.

#What it is for

• It shows which step has to come before which (for example, no run can start before a runner is connected, and a SQL step cannot run before its connection exists).
• It says who does each step (installation admin, workspace admin, user).
• It collects the concepts in one table, so you can look up any term used on the other pages.

#When to use it

• When you install Spitfire for the first time: follow it from top to bottom.
• When a colleague asks "where do I start?": send them this page.
• When something does not work and you don't know which prerequisite is missing: check the steps before the one you are on.

#Roadmap

This order gets you there with the fewest surprises. Optional steps are marked; you can skip them and come back later.

#1. Installation

Install the controller (web UI + API + Postgres) and the local runners. On Linux/macOS one command is enough:

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

Use kubernetes for Kubernetes, and irm https://spitfire.tr/install.ps1 | iex on Windows (Docker Desktop). The machine only needs Docker (plus kubectl for Kubernetes). The Docker installation starts Postgres, the controller and 2 runners, so you can run a test right after installing. Details, ports, proxy and backups: Installation.

#2. First sign-in and setup code

Open the address on the Kurulum tamamlandı. Tarayıcıda açın: http://... line at the end of the installation. The first visit shows the Create the first admin screen, which asks for the one-time setup code (Setup code) printed at the end of the installation. The account you create there is the installation admin; it adds everyone else afterwards. Lost the code? See Installation → First sign-in and setup code.

#3. License: free key or paid plan

An installation without a key runs with the free limits for 14 days from when it is first seen; after that, starting new runs needs a license key (tests and results are not deleted). Get a free key by e-mail at spitfire.tr/ucretsiz-anahtar and paste it on the License page. Several users, higher VU/RPS, several runners or locations, SSO and the audit log need a paid plan. Details: License.

#4. Users, groups and SSO (optional)

If a team will use Spitfire, create the accounts on the Users page and decide on the Groups page who may see and run which test. If you want sign-in with your corporate identity, set up OpenID Connect (Entra ID, Okta, Google, Keycloak…) or LDAP / Active Directory on the Single sign-on page. On the Agency plan you can open a separate workspace for each client. Details: Users and access.

#5. Runners and locations

The local runners that come with the installation are in the local location and are enough for the first tests. To send load from another city or cloud region, create a location-bound registration key on the Runners page and run the command it gives on that server. The runner connects out to the controller; no inbound port has to be opened on the remote server. Details: Runners and locations.

Dashboard: active runs, runs in the last 24 h, 7-day pass rate, idle runners and the recent runs list

#6. Connections and secrets

Protocols other than HTTP (gRPC, Kafka, MQTT, RabbitMQ, Redis, SQL, MongoDB) and mTLS client certificates need a connection on the Connections page first (e.g. {connection:orders-db}). Passwords and other secrets are stored encrypted; tests refer to a connection by name and never see the password. Details: Protocols and connections.

#7. Data files (optional)

If every VU should use a different user name, card number, product id…, upload a CSV on the Data files page; rows can be handed out sequentially, randomly or uniquely across runners. Details: Test data.

#8. Your first test: the editor

On the Tests page, New test opens the editor. A test is made of one or more scenarios; each scenario is an ordered list of steps. Every step can have checks (status, JSONPath, header, latency…) and extracts (take a value from the response into a variable for later steps). If you already have a k6 script, a JMeter plan, an OpenAPI/Postman document, a HAR recording or an access log, import it instead of writing from scratch: Open file and Import API / HAR. Details: Test editor and Import.

#9. Load model and thresholds

In the editor, choose an executor (load model) for each scenario: constant-vus, ramping-vus, constant-arrival-rate, ramping-arrival-rate, shared-iterations, per-vu-iterations. This is where you set the ramp-up, the target VUs or RPS, and think time. On the Thresholds tab, write the pass/fail criteria (e.g. p(95)<500 for req_duration, rate<0.01 for req_failed). A run without thresholds counts as "passed"; for a meaningful verdict add at least one latency and one error-rate threshold. Details: Load model and thresholds.

#10. Your first run and reading the results

Press Run on the test page. In the Run test dialog, choose the runners By count, By labels, Pick or By location, then click Start. The run page shows live RPS, active VUs, p95 latency, error rate, the step table and threshold results; when the run ends, findings (slowest step, error kinds, regression…) are listed. Mark a good run with Set as baseline (e.g. {run:checkout-baseline}); later runs are compared with it. Details: Runs and results.

#11. Reports and sharing

The Report menu on the run page opens the HTML report, downloads a PDF, exports CSV, and with Share link… creates a link valid for 1–90 days for someone without an account. Details: Runs and results.

#12. Scheduled runs, synthetic monitoring and notifications

To run a test regularly use Schedule on the test page or the Scheduled runs page; for low-load checks at an interval use Synthetic monitoring; for Slack, Teams, e-mail, SMS or webhook notifications use Integrations. Details: Scheduling and monitoring.

#13. CI/CD

Create an API token from the user menu → API tokens, store it in your pipeline as the secret variable SPITFIRE_TOKEN, and run the saved test with spitfire cloud run "<test name>". The command waits for the run to end and exits according to the thresholds (0 passed, 99 a threshold failed…). Details: CI/CD.

#14. Version comparison

To run two versions (e.g. the current one and a candidate) in two environments at the same time, under the same load, and compare them step by step, use a comparative run (version A/B); measure the noise with an A/A calibration. Details: Version comparison.

#15. Observability

With an observability connection (OTLP from an OpenTelemetry Collector, Prometheus, Tempo, Jaeger, Loki) the run's Backend tab lines up your systems' own traces, metrics and logs with the load steps: which service or database slowed down at which step. Details: Observability.

#16. Mock services, fault injection and capacity planning (advanced)

Stand in for outside APIs (payment, SMS, cargo…) with mock services, delete pods and add network latency under load on Kubernetes, and estimate capacity from a breakpoint run. Details: Mocks, chaos and capacity.

#17. When something goes wrong

If the UI shows a server error, copy its error code; the installation admin can look at the System events page and prepare a zip with Download support bundle. Details: Troubleshooting.

#The shortest path: a first run in 15 minutes

If you only want to see "does it work?" and leave the team, SSO and remote runners for later:

1. On a machine with Docker, run curl -fsSL https://spitfire.tr/install.sh | bash -s -- docker.
2. Open the printed address, enter the Setup code and click Create admin and sign in.
3. Tests → New test; put an endpoint you want to test in the first step's URL (your own system; do not send load to someone else's system without permission).
4. Add a latency threshold on the Thresholds tab and Save.
5. Run → Start. Watch the charts fill on the run page.

The license step can wait for the first 14 days; but at the end of those 14 days new runs need a key.

#Who does what

#Concepts

#Common problems

Symptom: The Dashboard says "No runners connected, so tests can't start." Cause: No runner is connected to the controller (the local runner containers may have stopped, or Kubernetes was installed with --runners 0). Fix: Follow Runners → Common problems.

Symptom: Clicking Start shows "A license key is required to start new runs". Cause: The 14 keyless days are over. Fix: Get a free key and paste it on the License page: License.

Symptom: You cannot add a colleague; "Another user cannot be enabled" appears. Cause: The free edition allows 1 active user. Fix: Move to a paid plan or set an unused account to Disabled: License.

Symptom: A colleague with the user role cannot see any tests. Cause: Users only see tests assigned to their groups. Fix: On the Groups page add them to a group and mark tests Visible / May run: Users and access.

#Related pages

• Installation
• License
• Users and access
• Runners and locations
• Test editor
• Runs and results
• Troubleshooting