Self-hosting and installation - Docs

CDPCaptcha is built to run on your own server.
Requirements: PHP 8.2 or newer with pdo_mysql, mbstring and openssl;
MariaDB 10.6 or newer;
nginx or Apache with HTTPS.

Install

Shell

git clone <your copy of the repository> /var/www/captcha.example.com
sudo bash /var/www/captcha.example.com/connect/install/cdp-install.sh --base-url https://captcha.example.com

The installer creates the database and its user, writes /etc/cdpcaptcha/.env (0640 root:www-data) with generated secrets, applies the migrations and creates the system sitekeys.
It never prints secrets.
Run it again after updates: it only applies new migrations.

Web server

Point the document root at the folder;
every request that is not a file under /core/assets goes to index.php.

nginx

server {
    listen 443 ssl http2;
    server_name captcha.example.com;
    root /var/www/captcha.example.com;
    index index.php;

    location /core/assets/ { expires 7d; add_header Cache-Control "public"; }
    location ~ ^/(config|connect|controller|components|migrations|tests|sdk|\.git)/ { return 404; }
    location / { try_files $uri /index.php$is_args$args; }
    location = /index.php {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

.env keys

Key	Default	Meaning
`BASE_URL`		Public URL, used in mails and embed codes.
`DIFFICULTY_DEFAULT`	4	Level 1 to 10 for sitekeys without their own setting.
`PUZZLE_TTL`	1800	Seconds a puzzle and its solution stay valid.
`PUZZLE_COUNT`	8	Sub-puzzles per puzzle.
`RATE_WINDOW / RATE_STEPS / RATE_PUZZLES_MAX`	600 / 10,30,100,300 / 600	Adaptive difficulty and hard cap per address.
`MAIL_MODE / MAIL_FROM`	sendmail	Transactional mail via the local MTA; "file" writes mails to MAIL_DIR for tests.
`CONTACT_TO`		Recipient of the contact form.
`PLAYGROUND`	1	0 hides the playground.

Command line

Shell

php connect/install/cdp-install.php migrate
php connect/install/cdp-install.php system-sites
php connect/install/cdp-install.php site:add "Contact form" "example.com" 4
php connect/install/cdp-install.php site:list
php connect/install/cdp-install.php key:add "Server A"

Maintenance

There are no cron jobs.
Expired puzzles are removed during normal API calls.
Back up the database and the .env file;
the HMAC key in it signs every puzzle, so changing it invalidates puzzles that are currently in flight (nothing else).