FCaptcha 5-minute self-hosted quickstart

Run FCaptcha locally, open its bundled demo, and confirm the API is ready. No WebDecoy account is required.

Prerequisites

• Docker
• openssl for generating a signing secret
• Port 3000 available on your machine

1. Start FCaptcha

Generate a secret and run the current release container:

export FCAPTCHA_SECRET="$(openssl rand -hex 32)"

docker run --rm --name fcaptcha \
  -p 127.0.0.1:3000:3000 \
  -e FCAPTCHA_SECRET \
  ghcr.io/webdecoy/fcaptcha:1.48.1

The server rejects short or repetitive production secrets. Binding to 127.0.0.1 keeps this quickstart local.

2. Confirm readiness

In another terminal:

curl --fail http://127.0.0.1:3000/ready

Expected response:

{"status":"ok"}

3. Complete a challenge

Open http://127.0.0.1:3000/demo/ and complete the checkbox challenge. The same page also demonstrates invisible scoring.

What you built

The container serves all three parts from one origin:

• the browser client at /fcaptcha.js;
• challenge, scoring and verification APIs under /api/;
• the local demo at /demo/.

State is process-local by default. Configure Redis before running multiple replicas so proof-of-work challenges, token replay protection, rate limits, suspicion, and idempotency state are shared.

Before production

• Pin a release tag or image digest instead of latest.
• Set a separate FCAPTCHA_VERIFY_SECRET so a leaked verification credential cannot mint tokens.
• Restrict FCAPTCHA_ALLOWED_HOSTNAMES to the sites that may request tokens.
• Configure TRUSTED_PROXIES for the proxies that overwrite visitor-address headers.
• Keep token verification on your backend.

Continue with integrate and verify tokens.