Cap Standalone

Cap Standalone is the default way of self-hosting Cap's backend. It provides a simple HTTP API for the widget to use and a siteverify endpoint compatible with hCaptcha or reCAPTCHA's, along with the ability to use multiple site keys.

Installation

You'll need to have Docker Engine 20.10 or higher installed on your server.

Start by creating a docker compose file named docker-compose.yml with the following content:

version: "3.8"

services:
  cap:
    image: tiago2/cap:latest
    container_name: cap
    ports:
      - "3000:3000"
    environment:
      ADMIN_KEY: your_secret_password
    volumes:
      - cap-data:/usr/src/app/.data
    restart: unless-stopped

volumes:
  cap-data:

Tips

• Make sure to add an admin key to log into the web UI. It should be at least 30 characters long.

• If your port 3000 is already in use, feel free to change it to something else.

• If you're having trouble accessing the dashboard, add network_mode: "host" under the Cap service.

Start the container:

docker compose up -d

And access your web dashboard at http://localhost:3000 or by accessing port 3000 on your machine.

Log in with your admin key and create a new site key. Take note of both the site key and secret key.

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

You'll need to 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>" }'

A successful response will return:

{
  "success": true
}

Client-side library storage

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