Standalone server

Installation

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.

To install Cap Standalone, you need to have Docker installed on your server. Once you have it installed, you can run the following command to pull the image:

docker pull tiago2/cap:latest

NOTE

Both x86_64 (amd64) and arm64 architectures are supported. Docker Engine 20.10 or higher is recommended

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

docker run \
  -p 3000:3000 \
  -v $(pwd)/cap-standalone:/usr/src/app/.data \
  -e ADMIN_KEY=your_secret_key \
  tiago2/cap:latest

This will start the server on port 3000 and create a cap-standalone folder in your current directory to store the data. Change the port if needed.

Make sure to replace your_secret_key with a strong secret key, as anyone with it will be able to log into the dashboard and create keys.

Then, you can access the dashboard at http://localhost:3000, log in, and create a key. The key ID and secret will be used to configure the widget and verify the token on your server. You'll also need to make the server publicly accessible from the internet, as the widget needs to be able to reach it.

Usage

Client-side

First, add the Cap widget to your website by following this guide.

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

https://<instance_url>/<key_id>/api/

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.
• <key_id>: Your key ID from this dashboard.

Example:

<cap-widget
  data-cap-api-endpoint="https://cap.example.com/d9256640cb53/api/"
></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>/<key_id>/siteverify

Your request needs to include the following data:

• secret: Your key secret from this dashboard
• response: The CAPTCHA token generated by the widget on the client-side

Example using curl:

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

Remember to replace:

• <instance_url>: This server's URL
• <key_id>: Your key ID from this dashboard
• <key_secret>: Your key secret from this dashboard
• <captcha_token>: The token value received from the client

The response should look like this:

{
  "success": true
}

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