Self Hosting

[trymeouteh]

Please allow for anyone to self host their own Procaptcha instance with documentation.

[forgetso]

Hi @trymeouteh, sorry I've only just seen this. Please follow these steps:

Self-hosted Procaptcha

Pre-requisites

• Ability to edit TypeScript source code and maintain a GitHub fork
• At least one VPS for a Captcha Provider with min 4GB RAM
• Somewhere to host files
• An image dataset file
  • See how to produce a dataset

Set up your Captcha Provider

Step 1.

Clone https://github.com/prosopo/captcha to your VPS

Step 2.

Create your env file

cd captcha && cp dev/scripts/env.production .env.production

Step 3.

Provider Account

These variables refer to a Polkadot account (sr25519 format) that will be used to secure your API and payloads

PROSOPO_PROVIDER_ACCOUNT_PASSWORD=
PROSOPO_PROVIDER_ADDRESS=
PROSOPO_PROVIDER_JSON=
PROSOPO_PROVIDER_MNEMONIC=

Create one using this script from within the root of the repo:

npx tsx ./dev/scripts/src/scripts/generateMnemonic.ts
{"scope":"file:///home/chris/dev/prosopo/captcha-private/captcha/dev/scripts/src/scripts/generateMnemonic.ts","ts":"2025-08-06T11:02:29.400Z","level":"debug","data":{"address":"5HThUF9mHgtBtTrGx8Co7691wt54YWgdXYUJgwqAyCioWQ6A"},"msg":"Address generated"}
{"scope":"file:///home/chris/dev/prosopo/captcha-private/captcha/dev/scripts/src/scripts/generateMnemonic.ts","ts":"2025-08-06T11:02:29.400Z","level":"debug","data":{"mnemonic":"<YOUR MNEMONIC>"},"msg":"Mnemonic generated"}

Caddy Domain

The caddy domain is the host for your Provider (e.g. pronode.yourdomain.com). You will need to set up DNS to point at your VPS.

CADDY_DOMAIN=

Not Required

Fill in the missing env variables. The following are not required

PROSOPO_SITE_KEY=
PROSOPO_SERVER_URL=
CAPTCHA_STORAGE_SCHEDULE=*/5 * * * *
PROSOPO_PROVIDER_JSON=

Step 3. Start the docker services

The docker services use the docker-compose.provider.yml in the captcha repo. They also refer to the .env.production that you created above. Start them with the following command.

REDIS_IMAGE=latest MONGO_IMAGE=6.0.17 CADDY_IMAGE=2.5.5 VECTOR_IMAGE=2.5.5 COMPOSE_PROVIDER_PREVIOUS_IMAGE_VERSION=3.1.10 COMPOSE_PROVIDER_IMAGE_VERSION=3.1.10 docker compose --file ./docker/docker-compose.provider.yml --env-file .env.production --profile production up -d

Step 4. Load your image captcha dataset

# Docker cp the dataset file to the provider container
docker cp "{{ home_folder }}/{{ DATASET_FILE }}" "provider1:/usr/src/app/{{ DATASET_FILE }}"

# Import the dataset
docker exec -it provider1 bash -c "npx provider provider_set_data_set --file /usr/src/app/{{ DATASET_FILE }}"

Step 5. Obtain your detector bundle

Contact [email protected] with a request for an obfuscated detector package. This is the code here: https://github.com/prosopo/captcha/blob/745cc897c61b7f92b5090cd46cf89ffd515f1eb4/packages/detector/src/index.js

You must provide in your request

• The website on which you are planning to run your self-hosted CAPTCHA solution
• A base64 encoded RSA private key with OAEP padding and SHA-256 as the OAEP hash. Use the following TypeScript snippet to generate:

import crypto from "node:crypto";
export function generateKeyPair(): { publicKey: string; privateKey: string } {
	// Generate the keypair with specific parameters
	const { privateKey, publicKey } = crypto.generateKeyPairSync("rsa", {
		modulusLength: 2048,
		publicKeyEncoding: {
			type: "spki",
			format: "pem",
		},
		privateKeyEncoding: {
			type: "pkcs8",
			format: "pem",
		},
	});

	// Convert to base64
	const privateKeyBase64 = Buffer.from(privateKey).toString("base64");
	const publicKeyBase64 = Buffer.from(publicKey).toString("base64");

	return {
		privateKey: privateKeyBase64,
		publicKey: publicKeyBase64,
	};
}
console.log(generateKeyPair());

We will then send you the contents of index.js. You should replace the existing index.js with the file we give you in a fork of the captcha repo.

Step 6. Build procaptcha.bundle.js and host

Build the procaptcha JS after making some changes to the source code.

1. Replace the detector index.js, as described above.
2. Replace the hard coded providers in @prosopo/load-balancer. We use a dynamic list for production but you could also just put yours directly in this file, as per the development environment setup - see code at previous link.

Then, from within your forked captcha repo:

npm i
npm run build:all
npm run -w @prosopo/procaptcha-bundle build:tsc
NODE_ENV=production npm run -w @prosopo/procaptcha-bundle bundle

Copy the outputs of ./packages/procaptcha-bundle/dist/bundle/ to a hosting provider of your choice (e.g. https://www.jsdelivr.com/) and obtain the URL of procaptcha.bundle.js. This is the entrypoint for the captcha process and is the URL for the script tag you would place on your site.

From this point onwards, implement the client-side as per our docs, switching our script URL for your own.

Step 7. Server-side verification

We run an API for verification which you could replicate but it is not open-source and not advised. For your own verification purposes it is better to use the @prosopo/server package, which will contact the provider directly instead of navigating via an API.

[forgetso]

@trymeouteh Please let us know if you manage to self-host!