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:
/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.