Skip to content

Getting started

This page runs FastProof on your machine, creates a project and uploads a first report. It takes about ten minutes. You need Docker (or Podman) and openssl.

FastProof always needs PostgreSQL (14 to 18; 18 is recommended). Attachments go to an S3-compatible bucket or, for a single replica, to a directory.

Create an admin token

FastProof never runs without authentication. For a first start, give it a static admin token. The token file holds only the SHA-256 hash of the token, so the file itself is not a secret:

mkdir fastproof-demo && cd fastproof-demo
export FASTPROOF_TOKEN="$(openssl rand -hex 32)"
printf 'admin:admin:sha256:%s\n' "$(printf %s "$FASTPROOF_TOKEN" | sha256sum | cut -d' ' -f1)" > admin-tokens
chmod 0644 admin-tokens
echo "$FASTPROOF_TOKEN"

Keep the printed token: it is the Authorization: Bearer value for the API and the CLI. The line format is name:role:sha256:<hex>; see Security for roles. After the first start you can create managed tokens with an expiry and drop the static one.

Option 1: Docker with a directory for attachments

The smallest setup: one PostgreSQL container and FastProof storing attachments in a volume.

docker network create fastproof

docker run -d --name fastproof-db --network fastproof \
  -e POSTGRES_USER=fastproof -e POSTGRES_PASSWORD=fastproof -e POSTGRES_DB=fastproof \
  -v fastproof-db:/var/lib/postgresql \
  docker.io/library/postgres:18.7-trixie

docker run -d --name fastproof --network fastproof \
  -p 127.0.0.1:8080:8080 -p 127.0.0.1:9090:9090 \
  -e FASTPROOF_DATABASE_URL=postgres://fastproof:fastproof@fastproof-db:5432/fastproof \
  -e FASTPROOF_BLOB_BACKEND=fs \
  -e FASTPROOF_ADMIN_TOKENS_FILE=/etc/fastproof/admin-tokens \
  -e FASTPROOF_LOG_FORMAT=text \
  -v "$PWD/admin-tokens:/etc/fastproof/admin-tokens:ro" \
  -v fastproof-blobs:/var/lib/fastproof \
  docker.io/franshub/fastproof:0.1.0-dev1

FastProof runs its database migrations at start (FASTPROOF_MIGRATE=auto, guarded by an advisory lock). Check that it is ready:

curl -fsS http://localhost:9090/readyz

/readyz answers 200 once PostgreSQL is reachable, the schema is at the expected version and the blob store is writable. Open http://localhost:8080/ for the UI.

Option 2: Docker Compose with PostgreSQL and Garage

Garage is a small S3-compatible server. With it, attachments live in a bucket exactly as they would in production. Download the two example files next to admin-tokens:

Create .env with the Garage secrets and start everything:

cat > .env <<EOF
GARAGE_RPC_SECRET=$(openssl rand -hex 32)
S3_ACCESS_KEY=GK$(openssl rand -hex 12)
S3_SECRET_KEY=$(openssl rand -hex 32)
EOF
docker compose up -d
docker compose logs -f fastproof

Garage creates the access key and the fastproof bucket on its first start (--single-node --default-bucket). Garage is AGPL-3.0 licensed; FastProof only talks to it over the S3 API.

Create a project

Projects are the unit of access control; launches and results belong to one project. The key is lowercase letters, digits and dashes:

curl -fsS -X POST http://localhost:8080/api/v1/projects \
  -H "Authorization: Bearer $FASTPROOF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"key":"web","name":"Web shop","description":"Browser and API tests of the shop"}'

Upload the first report

The fastproof binary is also the CLI. Without installing anything, run it from the same image. Here it uploads an allure-results directory from the current directory:

docker run --rm --network host \
  -e FASTPROOF_URL=http://localhost:8080 \
  -e FASTPROOF_TOKEN -e FASTPROOF_PROJECT=web \
  -v "$PWD:/work:ro" -w /work \
  docker.io/franshub/fastproof:0.1.0-dev1 upload allure-results

The CLI creates a launch (or joins the one named by FASTPROOF_LAUNCH), uploads the directory as one archive and finishes the launch. Uploads are processed asynchronously; the UI shows the launch while it fills up.

Any report format works the same way: a junit.xml file, a CTRF ctrf-report.json, a Playwright results.json or a directory of them. See Report formats.

No reports at hand?

Run any test suite with the Allure adapter of your framework (for example allure-pytest with pytest --alluredir=allure-results) or with a JUnit reporter, then upload the output.

Install the CLI

The CLI is a static Linux binary inside the image. Copy it out once:

id=$(docker create docker.io/franshub/fastproof:0.1.0-dev1)
docker cp "$id:/usr/local/bin/fastproof" ./fastproof
docker rm "$id"
./fastproof version

Or add it to your CI image:

COPY --from=docker.io/franshub/fastproof:0.1.0-dev1 /usr/local/bin/fastproof /usr/local/bin/fastproof

Next steps

  • CI recipes: upload from GitLab CI, GitHub Actions and Jenkins, live with fastproof watch.
  • Concepts: how launches, shards, retries and flaky tests work.
  • Helm chart: run FastProof in Kubernetes.
  • Configuration: every setting.