cap/docs/guide/standalone.md

# 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](https://docs.docker.com/get-docker/) installed on your server. Once you have it installed, you can run the following command to pull the image:

```bash
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:

```bash
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](widget.md).

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:

```html
<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`:

```bash
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:

```json
{
  "success": true
}
```

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