mCaptcha

Deploy bare metal

Bare metal deployment is tedious, most of this will be automated with a script in the future.

1. Install Database

The following databases are supported:

  1. Postgres
  2. MariaDB

Please install the database of your choice. Then:

  1. Create new database user for mCaptcha
  2. Create new database for mCaptcha

mCaptcha binary has migrations baked-in and is applied on start up. The choice of database is described using the scheme of the database URL. For instance:

  1. Postgres: postgres://mcaptcha:password@localhost:5432/mcaptcha
  2. Mariadb: mysql://mcaptcha:password@localhost:3306/mcaptcha

2. Optionally, install mCaptcha/cache

We recommend this for larger instances. For single-user instances or for instances that protect personal websites, we recommend using the internal cache system. To do so, please comment out the redis section of the configuration file.

Please see mCaptcha/cache for more details.

3. Install mCaptcha

3.1 Install from source

To build mcaptcha, you need the following dependencies:

  1. rust
  2. node(v20)
  3. yarn(JavaScript package manager)
  4. make

With all dependencies installed, run:

make dev-env && make release

And the following commands to install the compiled binary:

sudo cp ./target/release/mcaptcha /usr/bin/ && \
	mkdir sudo /etc/mcaptcha && \
	sudo cp config/default.toml /etc/mcaptcha/config.toml

3.2 Install pre-compiled binary

i. Download assets

wget https://dl.mcaptcha.org/mcaptcha/mCaptcha/master/mcaptcha-master-linux-amd64.tar.gz.asc
wget https://dl.mcaptcha.org/mcaptcha/mCaptcha/master/mcaptcha-master-linux-amd64.tar.gz.sha256
wget https://dl.mcaptcha.org/mcaptcha/mCaptcha/master/mcaptcha-master-linux-amd64.tar.gz

ii Verify checksum

sha256sum -c mcaptcha-master-linux-amd64.tar.gz.sha256

iii Verify GPG signature

All mcaptcha binaries are signed with our GPG key. Please verify signatures to verify authenticity.

gpg --keyserver keyserver.ubuntu.com --recv 73DAC973A9ADBB9ADCB5CDC4595A08135BA9FF73
gpg --verify mcaptcha-master-linux-amd64.tar.gz.asc

iv. Install

tar -xvzf mcaptcha-master-linux-amd64.tar.gz \
  && sudo cp mcaptcha-master-linux-amd64/mcaptcha /usr/local/bin \
  && sudo mkdir /etc/mcaptcha \
  && sudo cp mcaptcha-master-linux-amd64/config.toml /etc/mcaptcha/

4. Configuration

mCaptcha is highly configurable.

Configuration is applied/merged in the following order:

  1. path to configuration file passed in via MCAPTCHA_CONFIG
  2. ./config/default.toml
  3. /etc/mcaptcha/config.toml
  4. environment variables. Please see here for a full list of environment variables.

5. Systemd service configuration:

  1. Copy the following to /etc/systemd/system/mcaptcha.service:
[Unit]
Description=mCaptcha: a CAPTCHA system that gives attackers a run for their money

[Service]
Type=simple
User=mcaptcha
ExecStart=/usr/bin/mcaptcha
Restart=on-failure
RestartSec=1
SuccessExitStatus=3 4
RestartForceExitStatus=3 4
SystemCallArchitectures=native
MemoryDenyWriteExecute=true
NoNewPrivileges=true
Environment="RUST_LOG=info"

[Unit]
After=sound.target
Wants=network-online.target
Wants=network-online.target
Requires=postgresql.service
After=syslog.target

[Install]
WantedBy=multi-user.target
  1. Enable service:
sudo systemctl daemon-reload && \
	sudo systemctl enable mcaptcha && \ # Auto startup during boot
	sudo systemctl start mcaptcha

6. Install and configure Nginx

mCaptcha doesn’t implement SSL yet. Please use a reverse proxy like Nginx to add SSL to your deployment. Here’s an example virtual host configuration for Nginx:

server {
  server_name <your mcaptcha hostname>;
	listen 80;
	listen [::]:80;

	location / {
		proxy_pass http://127.0.0.1:<mcaptcha_port>;
		proxy_set_header Host $host;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
	}

}

Edit this page on git.batsense.net

← Getting started
Using Ansible →