Cap Standalone

Cap Standalone is a self-hosted version of Cap's backend that allows you to spin up a server to validate and create challenges so you can use it with languages other than JS.

It's simple yet powerful, allowing you to use Cap in any language that can make HTTP requests. It's mostly compatible with reCAPTCHA and hCaptcha's siteverify enpoints, so you can use it as a drop-in replacement for them.

It also offers API key support, a built-in assets server, a dashboard with statistics, and more.

Installation

Requirements

You'll need to have Docker Engine 20.10 or higher installed on your server. Both x86_64 (amd64) and arm64 architectures are supported.

---

Run the following command to pull the Cap Standalone Docker image from Docker Hub:

docker pull tiago2/cap:latest

Then, to run the server, use the following command:

docker run -d \
  -p 3000:3000 \
  -v cap-data:/usr/src/app/.data \
  -e ADMIN_KEY=your_secret_password \
  --name cap-standalone \
  tiago2/cap:latest

Make sure to replace your_secret_password with a strong password, as anyone with it will be able to log into the dashboard and create keys. It'll need to be at least 30 characters long.

Then, you can access the dashboard at http://localhost:3000, log in, and create a key. You'll get a site key and a secret key which you'll be able to use on your widget.

On Debian and other OSes that don't use iptables, if you can't open the dashboard, try setting --network=host in the run command. Thanks to Boro Vukovic for letting me know about this.

You'll also need to make the server publicly accessible from the internet, as the widget needs to be able to reach it. If you're using a reverse proxy, make sure to check the options guide to configure rate-limiting properly.

Usage

Client-side

Let's configure your widget to use your self-hosted Cap Standalone server. To do this, set the widget's API endpoint option to:

https://<instance_url>/<site_key>/

Make sure to replace:

• <instance_url>: The actual URL where your Cap Standalone instance is running. This URL must be publicly accessible from the internet.
• <site_key>: Your site key from this dashboard.

Example:

<cap-widget
  data-cap-api-endpoint="https://cap.example.com/d9256640cb53/"
></cap-widget>

Server-side

After a user completes the CAPTCHA on your site, your backend needs to verify their token using this server's API.

You can do this by sending a POST request from your server to the following endpoint:

https://<instance_url>/<site_key>/siteverify

Your request needs to include the following data:

• secret: Your key secret from this dashboard. This is not the admin key, but rather your site key's secret.

• response: The CAPTCHA token generated by the widget on the client-side

Example using curl:

curl "https://<instance_url>/<site_key>/siteverify" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "secret": "<key_secret>", "response": "<captcha_token>" }'

The response should look like this:

{
  "success": true
}

Or, if the captcha token is invalid or expired, it will return:

{
  "success": false
}

If success is true, you can proceed with your app logic.

Client-side library storage

Cap Standalone can also serve the widget and floating client-side library files. Learn more.