deployment docs

This commit is contained in:
Aravinth Manivannan 2021-07-21 15:49:53 +05:30
parent 6bf8ef09a8
commit daa8bb577d
Signed by untrusted user: realaravinth
GPG key ID: AD9F0F08E855ED88
14 changed files with 346 additions and 289 deletions

View file

@ -1,9 +1,9 @@
---
title : "Docs"
description: "Docs Doks."
title : "mCaptcha"
description: "Docs mCaptcha"
lead: ""
date: 2020-10-06T08:48:23+00:00
lastmod: 2020-10-06T08:48:23+00:00
date: 2021-07-21 14:48
lastmod: 2021-07-21 14:48
draft: false
images: []
---

View file

@ -1,6 +1,6 @@
---
title: "Help"
description: "Help Doks."
description: "Help mCaptcha."
lead: ""
date: 2020-10-06T08:49:15+00:00
lastmod: 2020-10-06T08:49:15+00:00

View file

@ -2,8 +2,8 @@
title: "FAQ"
description: "Answers to frequently asked questions."
lead: "Answers to frequently asked questions."
date: 2020-10-06T08:49:31+00:00
lastmod: 2020-10-06T08:49:31+00:00
date: 2021-07-21 15:47
lastmod: 2021-07-21 15:47
draft: false
images: []
menu:
@ -13,36 +13,4 @@ weight: 630
toc: true
---
## Hyas?
Doks is a [Hyas theme](https://gethyas.com/themes/doks/) build by the creator of Hyas.
## Footer notice?
Please keep it in place.
## Keyboard shortcuts for search?
- focus: `/`
- select: `↓` and `↑`
- open: `Enter`
- close: `Esc`
## Other documentation?
- [Netlify](https://docs.netlify.com/)
- [Hugo](https://gohugo.io/documentation/)
## Can I get support?
Create a topic:
- [Netlify Community](https://community.netlify.com/)
- [Hugo Forums](https://discourse.gohugo.io/)
## Contact the creator?
Send `h-enk` a message:
- [Netlify Community](https://community.netlify.com/)
- [Hugo Forums](https://discourse.gohugo.io/)
Coming soon

View file

@ -1,24 +0,0 @@
---
title: "How to Update"
description: "Regularly update the installed npm packages to keep your Doks website stable, usable, and secure."
lead: "Regularly update the installed npm packages to keep your Doks website stable, usable, and secure."
date: 2020-11-12T13:26:54+01:00
lastmod: 2020-11-12T13:26:54+01:00
draft: false
images: []
menu:
docs:
parent: "help"
weight: 610
toc: true
---
{{< alert icon="💡" text="Learn more about <a href=\"https://docs.npmjs.com/about-semantic-versioning\">semantic versioning</a> and <a href=\"https://docs.npmjs.com/cli/v6/using-npm/semver#advanced-range-syntax\">advanced range syntax</a>." >}}
## Update npm packages
Bump the versions in the `devDependencies` section of `./package.json` to your liking, and run:
```bash
npm update
```

View file

@ -2,29 +2,15 @@
title: "Troubleshooting"
description: "Solutions to common problems."
lead: "Solutions to common problems."
date: 2020-11-12T15:22:20+01:00
lastmod: 2020-11-12T15:22:20+01:00
date: 2021-07-21 15:48
lastmod: 2021-07-21 15:48
draft: false
images: []
menu:
menu:
docs:
parent: "help"
weight: 620
toc: true
---
## Problems updating npm packages
Delete the `./node_modules` folder, and run again:
```bash
npm install
```
## Problems with cache
Delete the temporary directories:
```bash
npm run clean
```
Coming soon

View file

@ -1,6 +1,6 @@
---
title : "Prologue"
description: "Prologue Doks."
description: "Prologue mCaptcha."
lead: ""
date: 2020-10-06T08:48:45+00:00
lastmod: 2020-10-06T08:48:45+00:00

View file

@ -1,106 +0,0 @@
---
title: "Commands"
description: "Doks comes with commands for common tasks."
lead: "Doks comes with commands for common tasks."
date: 2020-10-13T15:21:01+02:00
lastmod: 2020-10-13T15:21:01+02:00
draft: false
images: []
menu:
docs:
parent: "prologue"
weight: 130
toc: true
---
{{< alert icon="💡" text="You can change the commands in the scripts section of `./package.json`." >}}
## start
Start local development server:
{{< btn-copy text="npm run start" >}}
```bash
npm run start
```
## lint
Check scripts, styles, and markdown for errors:
{{< btn-copy text="npm run lint" >}}
```bash
npm run lint
```
### scripts
Check scripts for errors:
{{< btn-copy text="npm run lint:scripts" >}}
```bash
npm run lint:scripts [-- --fix]
```
### styles
Check styles for errors:
{{< btn-copy text="npm run lint:styles" >}}
```bash
npm run lint:styles [-- --fix]
```
### markdown
Check markdown for errors:
{{< btn-copy text="npm run lint:markdown" >}}
```bash
npm run lint:markdown [-- --fix]
```
## clean
Delete temporary directories:
{{< btn-copy text="npm run clean" >}}
```bash
npm run clean
```
## build
Build production website:
{{< btn-copy text="npm run build" >}}
```bash
npm run build
```
### functions
Build Lambda functions:
{{< btn-copy text="npm run build:functions" >}}
```bash
npm run build:functions
```
### preview
Build production website including draft and future content:
{{< btn-copy text="npm run build:preview" >}}
```bash
npm run build:preview
```

View file

@ -1,9 +1,9 @@
---
title: "Introduction"
description: "Doks is a Hugo theme helping you build modern documentation websites that are secure, fast, and SEO-ready — by default."
lead: "Doks is a Hugo theme helping you build modern documentation websites that are secure, fast, and SEO-ready — by default."
date: 2020-10-06T08:48:57+00:00
lastmod: 2020-10-06T08:48:57+00:00
description: "mCaptcha is a privacy focused, libre CAPTCHA system with a kickass UX."
lead: "mCaptcha is a privacy focused, libre CAPTCHA system with a kickass UX."
date: 2021-07-21 14:49
lastmod: 2021-07-21 14:49
draft: false
images: []
menu:
@ -15,44 +15,16 @@ toc: true
## Get started
There are two main ways to get started with Doks:
There are two main ways to get started with mCaptcha:
### Tutorial
1. Managed solution: We run mCaptcha, experience is similar to other
CAPTCHA solutions.
2. Self-hosted: You can host mCaptcha on your server
{{< alert icon="👉" text="The Tutorial is intended for novice to intermediate users." >}}
## Manged solution:
Step-by-step instructions on how to start a new Doks project. [Tutorial →](https://getdoks.org/tutorial/introduction/)
{{< alert icon="⚠️" text="Coming soon" >}}
### Quick Start
### Self-hosted
{{< alert icon="👉" text="The Quick Start is intended for intermediate to advanced users." >}}
One page summary of how to start a new Doks project. [Quick Start →]({{< ref "quick-start" >}})
## Go further
Recipes, Reference Guides, Extensions, and Showcase.
### Recipes
Get instructions on how to accomplish common tasks with Doks. [Recipes →](https://getdoks.org/docs/recipes/project-configuration/)
### Reference Guides
Learn how to customize Doks to fully make it your own. [Reference Guides →](https://getdoks.org/docs/reference-guides/security/)
### Extensions
Get instructions on how to add even more to Doks. [Extensions →](https://getdoks.org/docs/extensions/add-google-fonts/)
### Showcase
See what others have build with Doks. [Showcase →](https://getdoks.org/showcase/parietal-numerics-documentation/)
## Contributing
Find out how to contribute to Doks. [Contributing →](https://getdoks.org/docs/contributing/how-to-contribute/)
## Help
Get help on Doks. [Help →]({{< ref "how-to-update" >}})
One page summary of how to start a new Doks project. [Quick Start →](../self-hosted/introduction)

View file

@ -1,60 +0,0 @@
---
title: "Quick Start"
description: "One page summary of how to start a new Doks project."
lead: "One page summary of how to start a new Doks project."
date: 2020-11-16T13:59:39+01:00
lastmod: 2020-11-16T13:59:39+01:00
draft: false
images: []
menu:
docs:
parent: "prologue"
weight: 110
toc: true
---
## Requirements
Doks uses npm to install dependencies and run commands. Installing npm is pretty simple. Download and install [Node.js](https://nodejs.org/) (it includes npm) for your platform.
## Start a new Doks project
Create a new site, change directories, install dependencies, and start development server.
### Create a new site
{{< btn-copy text="git clone https://github.com/h-enk/doks.git my-doks-site" >}}
```bash
git clone https://github.com/h-enk/doks.git my-doks-site
```
### Change directories
{{< btn-copy text="cd my-doks-site" >}}
```bash
cd my-doks-site
```
### Install dependencies
{{< btn-copy text="npm install" >}}
```bash
npm install
```
### Start development server
{{< btn-copy text="npm run start" >}}
```bash
npm run start
```
Doks will start the Hugo development webserver accessible by default at `http://localhost:1313`. Saved changes will live reload in the browser.
## Other commands
Doks comes with commands for common tasks. [Commands →]({{< ref "commands" >}})

View file

@ -0,0 +1,9 @@
---
title : "self-hosted"
description: "Instructions to self-host mCaptcha"
lead: ""
date: 2021-07-21 15:44
lastmod: 2021-07-21 15:44
draft: false
images: []
---

View file

@ -0,0 +1,130 @@
---
title: "Deploy bare metal"
description: "Bare metal deployment is tedious, most of this will be automated with a script in the future."
lead: "Bare metal deployment is tedious, most of this will be automated with a script in the future."
date: 2021-07-21 14:49
lastmod: 2021-07-21 14:49
draft: false
images: []
menu:
docs:
parent: "self-hosted"
weight: 120
toc: true
---
### 2. Configure
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.
### 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:
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
[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
```
2. Enable service:
```bash
$ sudo systemctl daemon-reload && \
sudo systemctl enable mcaptcha && \ # Auto startup during boot
sudo systemctl start mcaptcha
``
```

View file

@ -0,0 +1,101 @@
---
title: "Databse and cache"
description: "mCaptcha server requires dependencies like a Postgres
database and a Redis cache"
lead: "mCaptcha server requires dependencies like a Postgres
database and a Redis cache"
date: 2021-07-21 14:49
lastmod: 2021-07-21 14:49
draft: false
images: []
menu:
docs:
parent: "self-hosted"
weight: 130
toc: true
---
## Notes
### Database
- Database migrations are baked into the server binary so don't worry
about them.
- When compiling from source, unset database configuration(comment out
database configuration/ `unset` relevant environment variables).
`mCaptcha` uses [`sqlx`](https://crates.io/crates/sqlx) database client
library which checks SQL queries at compile time. So if you are starting
with a fresh database without migrations applied, compilation will fail.
### Redis
- Redis is an optional dependency. Currently, the non-Redis configuration
doesn't persist CAPTCHA heat. So if there's a systems failure, CAPTCHA
heat will be reset and visitor count will start from 0. For small
installations, this should post a problem as heat is short lived and is
reset anyways at cool down period.
- mCaptcha uses a custom Redis module called
[cache](https://github.com/mCaptcha/cache) to overcome some of Redis'
limitations.
## Instructions
Once again, there are two ways to go about this:
1. Docker
2. Bare metal
### Docker
### Database
Download and run Postgres
```bash
docker create --name mcaptcha-postgres \
-e POSTGRES_PASSWORD=<databse-password> \
-p 5432:5432 \
postgres && docker start mcaptcha-postgres
```
### Redis
```bash
docker create --name mcaptcha-cache \
-p 6379:6379 \
mcaptcha/cache && docker start mcaptcha-cache
```
See [mCaptcha/cache](https://github.com/mCaptcha/cache) for more
details.
### 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/bash 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 [`mCaptcha/cache`](https://github.com/mCaptcha/cache)
See [`mCaptcha/cache`](https://github.com/mCaptcha/cache) for more
details.

View file

@ -0,0 +1,60 @@
---
title: "Docker"
description: "Deploy mCaptcha with docker"
lead: "Deploy mCaptcha with docker"
date: 2021-07-21 15:14
lastmod: 2021-07-21 15:14
draft: false
images: []
menu:
docs:
parent: "self-hosted"
weight: 110
toc: true
---
## Docker
### 1. Configure
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.
See
[CONFIGURATION.md](https://github.com/mCaptcha/mCaptcha/tree/master/docs/CONFIGURATION.md)
for configurable options.
### 2. Run image
If you have already have a Postgres instance running, then:
```bash
docker run -p <host-machine-port>:<port-in-configuration-file> \
--add-host=database:<database-ip-addrss> \
-e RUST_LOG=debug \
-e DATABASE_URL="postgres://<db-user>:<db-password>@database:<db-port>/<db-name>" \
mcaptcha/mcaptcha:latest
```
If you don't have a Postgres instance running, you can either install
one using a package manager or launch one with docker. A [docker-compose
configuration]('../docker-compose.yml) is available that will launch both
a database instance mcaptcha instance.
## With docker-compose
1. Follow steps above to build docker image.
2. Set database password [docker-compose configuration]('../docker-compose.yml).
3. Launch network
```bash
docker-compose up -d
```

View file

@ -0,0 +1,21 @@
---
title: "Getting started"
description: "Get started with self-hosting mCaptcha"
lead: "Get started with self-hosting mCaptcha"
date: 2021-07-21 14:49
lastmod: 2021-07-21 14:49
draft: false
images: []
menu:
docs:
parent: "self-hosted"
weight: 100
toc: true
---
## Get started
There are two main ways to self-host mCaptcha:
1. Bare metal
2. With Docker