GateCHA

GateCHA

Self-hosted ALTCHA CAPTCHA management with API keys, multi-site support, and statistics.

🌐 Website · 📖 Documentation · 🧩 WordPress plugin

GateCHA is an open-source alternative to ALTCHA Sentinel. It wraps the ALTCHA proof-of-work CAPTCHA protocol with a management layer: API key management, per-site configuration, replay protection, and a dashboard with statistics.

Features

• ALTCHA-compatible - Works with the official ALTCHA widget (MIT)
• API Key Management - Create keys per site with custom difficulty, TTL, and domain restrictions (multiple domains + *.example.com wildcards)
• Replay Protection - Consumed challenges are tracked and rejected on reuse
• Statistics Dashboard - Track challenges issued, verifications (success/fail), per key, per day
• Single Binary - Vue.js dashboard embedded in the Go binary via go:embed
• Multi-Database - SQLite by default; MySQL available in the mysql build variant
• Docker Ready - One container, zero external dependencies (SQLite mode)
• Lightweight - ~23.8MB Docker image, ~14.2MB binary (SQLite); ~24.2MB / ~14.5MB with MySQL support

Quick Start

Docker Compose (recommended)

mkdir -p /opt/docker/GateCHA && cd /opt/docker/GateCHA
wget https://raw.githubusercontent.com/Upellift99/GateCHA/refs/heads/main/docker-compose.yml
docker compose up -d

Open http://localhost:8080 and log in with admin / changeme.

Docker Run

docker run -d -p 8080:8080 \
  -v gatecha_data:/app/data \
  -e GATECHA_ADMIN_PASSWORD=your-password \
  ghcr.io/upellift99/gatecha:latest

From Source

# Prerequisites: Go 1.26+, Node.js 20+
git clone https://github.com/Upellift99/GateCHA.git
cd GateCHA
make build        # SQLite only (default)
make build-mysql  # with MySQL support
./gatecha

Usage

1. Create an API Key

Log in to the dashboard at http://localhost:8080, go to API Keys, and create a new key.

2. Add the Widget to Your Site

<script async defer src="https://cdn.jsdelivr.net/npm/altcha/dist/altcha.min.js" type="module"></script>

<form action="/your-endpoint" method="POST">
  <!-- your form fields -->
  <altcha-widget
    challengeurl="https://your-gatecha-host/api/v1/challenge?apiKey=gk_your_key_id"
  ></altcha-widget>
  <button type="submit">Submit</button>
</form>

3. Verify on Your Backend

# Example: Python
import requests

altcha_payload = request.form.get('altcha')
resp = requests.post(
    'https://your-gatecha-host/api/v1/verify?apiKey=gk_your_key_id',
    json={'payload': altcha_payload}
)
if resp.json().get('ok'):
    # Valid submission
    pass

API Endpoints

Public (API Key auth via ?apiKey=gk_xxx)

Admin (JWT auth via Authorization: Bearer)

MySQL Support

The default build is SQLite-only for a lightweight single-binary deployment. MySQL support is compiled in only when explicitly requested.

Build locally with MySQL support:

make build-mysql

Docker image with MySQL support:

docker build --build-arg BUILD_TAGS=mysql -t gatecha:mysql .

Docker Compose with MySQL:

docker compose -f docker-compose.mysql.yml up -d

Note for contributors: When updating Go dependencies while working on MySQL support, run go mod tidy -tags mysql instead of plain go mod tidy to preserve the MySQL driver in go.mod.

Configuration

⚠️ Behind a reverse proxy, set GATECHA_TRUST_PROXY=true. Per-IP rate limiting keys off the connecting IP. With GATECHA_TRUST_PROXY=false behind a proxy, that IP is the proxy itself, so every visitor shares a single rate-limit bucket. It exhausts almost immediately, the public ALTCHA challenge endpoint starts returning 429s, and the login captcha breaks with "Expected application/json, received text/html". Enabling TRUST_PROXY makes the limiter use each visitor's real IP. Only enable it behind a trusted proxy that sets X-Forwarded-For/X-Real-IP, otherwise clients can spoof their IP.

License

MIT - see LICENSE.