feat: document bare metal deployment using pre-compiled bins

This commit is contained in:
Aravinth Manivannan 2024-01-08 00:31:40 +05:30
parent e3de4168e6
commit 457ec237d2
Signed by: realaravinth
GPG key ID: F8F50389936984FF

View file

@ -13,86 +13,112 @@ weight: 532
toc: true
---
### 2. Configure
## 1. Install Database
mcaptcha is highly configurable.
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](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#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`](https://github.com/mCaptcha/mCaptcha/blob/d4967626ee59504b32b0f85e409b4e3444ddc4f0/config/default.toml#L54) section of the configuration file.
Please see [`mCaptcha/cache`](https://github.com/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](https://keyserver.ubuntu.com/pks/lookup?search=73DAC973A9ADBB9ADCB5CDC4595A08135BA9FF73&fingerprint=on&op=index).
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.
4. environment variables. Please see
[here](https://github.com/mCaptcha/mCaptcha/blob/master/docs/CONFIGURATION.md) for a full list of environment variables.
### 1. Install postgres if you don't have it already.
For Debian based distributions:
```bash
sudo apt install postgres
```
### 2. Create new user for running `mcaptcha`
```bash
$ sudo useradd -b /srv -m -s /usr/bin/zsh mcaptcha
```
### 3. Create new user in Postgres
```bash
$ sudo -iu postgres # switch to `postgres` user
$ psql
postgres=# CREATE USER mcaptcha WITH PASSWORD 'my super long password and yes you need single quote`;
$ createdb -O mcaptcha mcaptcha # create db 'mcaptcha' with 'mcaptcha' as owner
```
### 4. Install and load [`mCaptcha/cache`](https://github.com/mCaptcha/cache) module:
See [`mCaptcha/cache`](https://github.com/mCaptcha/cache) for more
details.
### 4. Build `mcaptcha`
To build `mcaptcha`, you need the following dependencies:
1. rust
2. node(`v14.16.0`)
3. yarn(JavaScript package manager)
4. make
## How to build
1. Install Cargo using [rustup](https://rustup.rs/) with:
```bash
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
2. Install node(`v14.16.0`)
3. Install yarn(JavaScript package manager)
4. Build with make:
```bash
$ make dev-env && \
make release
```
### 5. Install package:
```bash
$ sudo cp ./target/release/mcaptcha /usr/bin/ && \
mkdir sudo /etc/mcaptcha && \
sudo cp config/default.toml /etc/mcaptcha/config.toml
```
### 6. Systemd service configuration:
### 5. Systemd service configuration:
1. Copy the following to `/etc/systemd/system/mcaptcha.service`:
```systemd
```
[Unit]
Description=mCaptcha: a CAPTCHA system that gives attackers a run for their money
@ -122,9 +148,33 @@ WantedBy=multi-user.target
2. Enable service:
```bash
$ sudo systemctl daemon-reload && \
```
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;
}
}
```