Self-hosting

Two different things

Hosting the loader means serving the script file from your own origin while the checks still run on our service. It suits a strict content security policy, change control that wants to review every byte that runs on the page, or a wish to keep third-party hosts out of the page entirely. Running the service means operating the whole system yourself, including the verify endpoint and the store, so no request leaves your infrastructure. The same software runs our service and a self-hosted installation; self-hosting the service is part of the Enterprise conversation on the pricing page.

Hosting the loader

The loader is one self-contained file. Copy it from us, serve it as application/javascript, and reference it from your page. It carries the address of our API, so no configuration changes; the only differences are that your origin now serves the script and starts the workers, and that updates arrive when you copy a new file rather than automatically.

# Copy the current loader and keep its hash with the copy
curl -sS -o otcaptcha.js https://api.otcaptcha.com/captcha/v1/otcaptcha.js
shasum -a 256 otcaptcha.js

<script src="[SCRIPT URL]" defer></script>
<!-- for example /static/otcaptcha.js?v=3; change the query when you copy a new file -->

• Workers. The background workers are started from the script's own URL, so serve it from an origin your worker-src allows, with the right content type, and do not rewrite or wrap the file: it detects that it is running inside a worker by the absence of document.
• Caching. Serve it with a long cache life and change the URL, or its query string, when you copy a new file, so no browser runs a stale copy next to a new one.
• Compression. Serve it compressed. We precompress with brotli and gzip; the file is about 12 KB gzipped and under 11 KB with brotli.
• Version. The loader sends its version with every call, and your reports show which versions your visitors run, so a copy that falls behind is visible. The changelog says what each version changed.
• Integrity. Record the SHA-256 of the file you copied. A integrity attribute on the script tag works only when the file is served from your origin, and it must be updated with every copy.

Running the service

The service is one statically linked binary, built from source into a container image with nothing else in it, plus a store. It has no other runtime dependency.

/health-check answers 200 while the process is up and returns no configuration. /ready fails when the store is unreachable, so use it for readiness, not for a load balancer that would otherwise pull every instance at once: the challenge route needs no store and keeps working through a store failure, while the server check answers 503 and your outage policy applies.

Settings

Everything is set through environment variables. On/off settings take on, off, true or false; anything unparseable stops the start, deliberately, so a typo cannot silently leave a protection off.

# Minimal single-instance run for evaluation. Memory store: not shared, so one instance only.
OTCAPTCHA_STORE=memory
OTCAPTCHA_CREDENTIALS_FILE=/etc/otcaptcha/credentials.json
OTCAPTCHA_ALLOWED_ORIGINS=https://www.example.com,https://*.example.net
OTCAPTCHA_TRUSTED_PROXIES=10.0.0.0/8
OTCAPTCHA_REAL_IP_HEADER=X-Forwarded-For
OTCAPTCHA_VALIDATE_ALLOWED_CIDRS=10.0.0.0/8
OTCAPTCHA_EVENTS_DIR=/var/lib/otcaptcha/events

The credentials file

A JSON object: an account name, then a list of site keys with their secrets. One site key may appear under several accounts; the lookup is by key. A key must be 32 lowercase hex characters, and a file that fails to parse stops the start.

{
  "my-account": [
    { "captcha_id": "[SITE KEY]", "captcha_key": "[SECRET]" }
  ]
}

Pointing the loader at your service

The loader is built with our API address. Pass yours in apiServers, or build the loader from source with your address, which is what a fully self-contained installation does.

otcaptcha.init(
  { captchaId: '[SITE KEY]', apiServers: ['https://captcha.example.com/captcha/v1'] },
  (widget) => { /* as usual */ }
);

Running more than one instance

Instances share nothing but the store. Attack mode and its baselines live in memory per instance, so a surge is seen at about half its size on each of two instances; the thresholds are set with that in mind. Put the public listeners behind a load balancer that health-checks /health-check, keep the internal listeners reachable from your application servers only, and give Redis a replica with Sentinel so a lost instance moves the primary without anyone acting. Spent-pass records from the last moments before a failover can be lost, which means a pass could be checked twice in that window; nothing else needs restoring.