Skip to content

Quick start

This guide installs TestFleet on a machine with Docker and runs a first, tiny suite: a container that checks a website answers. It takes a few minutes. For a production setup behind a reverse proxy, continue with Install afterwards.

You need a 64-bit Linux host (or a laptop) with Docker Engine and Compose v2.20 or later, and openssl to generate secrets.

  1. Download the Compose file and the configuration template into a new directory:

    Terminal window
    mkdir testfleet && cd testfleet
    curl -fsSLO https://raw.githubusercontent.com/TestFleetLabs/TestFleet/main/deploy/compose.yaml
    curl -fsSL -o .env https://raw.githubusercontent.com/TestFleetLabs/TestFleet/main/deploy/.env.example
  2. Fill in the four required values in .env. Generate the secrets with:

    Terminal window
    openssl rand -base64 48 # SECRET_KEY_BASE
    openssl rand -base64 32 # CLOAK_KEY
    openssl rand -hex 24 # POSTGRES_PASSWORD

    For a trial on your own machine, set PHX_HOST=localhost. On a server, use the host name your users will open.

  3. Start the stack:

    Terminal window
    docker compose up -d
    docker compose ps # testfleet, db, and docker-socket-proxy are up

    TestFleet listens on 127.0.0.1:4000 and runs its database migrations on every start.

  4. Create the first admin. While TestFleet has no users, it writes a one-time setup link to its log:

    Terminal window
    docker compose logs testfleet | grep "No users yet"
    # No users yet. Create the first admin at https://localhost/setup?token=…

    The link uses https://<PHX_HOST>, as a reverse proxy would serve it. For a trial without one, open the same path on http://localhost:4000 instead: http://localhost:4000/setup?token=…. TestFleet only redirects to HTTPS for other host names.

    The setup page also asks for your organization’s name, such as your company or team. Its slug starts every page’s URL.

This “suite” is the smallest thing that fits the container contract: a stock Alpine image whose command fetches a URL. It exits 0 when the site answers and non-zero when it does not.

  1. Projects → New project. Name it Website.

  2. New environment on the project page. Name it production, and add a variable BASE_URL with the address of a website you want to check, such as https://example.com.

  3. New test definition. Name it Smoke, with:

    • Image: alpine:3

    • Command, one argument per line (there is no shell unless you start one, as here):

      sh
      -c
      wget -q --spider "$BASE_URL" && echo "$BASE_URL answers"

    Leave the timeout and limits at their defaults.

  4. On the test definition’s page, the Run now panel lists the project’s environments. Start a run on production. The run page opens and follows the run live: queued, preparing while Docker pulls alpine:3, running, and finally passed, with the log line https://example.com answers.

  5. Change BASE_URL to an address that does not exist and run it again: the run ends failed, because the command exited non-zero.