From daa8bb577d3d6230c7fe5dfc2e372b448ded6ac1 Mon Sep 17 00:00:00 2001 From: realaravinth Date: Wed, 21 Jul 2021 15:49:53 +0530 Subject: [PATCH] deployment docs --- content/docs/_index.md | 8 +- content/docs/help/_index.md | 2 +- content/docs/help/faq.md | 38 +----- content/docs/help/how-to-update.md | 24 ---- content/docs/help/troubleshooting.md | 22 +--- content/docs/prologue/_index.md | 2 +- content/docs/prologue/commands.md | 106 ---------------- content/docs/prologue/introduction.md | 52 ++------ content/docs/prologue/quick-start.md | 60 --------- content/docs/self-hosted/_index.md | 9 ++ content/docs/self-hosted/bare-metal.md | 130 ++++++++++++++++++++ content/docs/self-hosted/dependencies.md | 101 +++++++++++++++ content/docs/self-hosted/docker.md | 60 +++++++++ content/docs/self-hosted/getting-started.md | 21 ++++ 14 files changed, 346 insertions(+), 289 deletions(-) delete mode 100644 content/docs/help/how-to-update.md delete mode 100644 content/docs/prologue/commands.md delete mode 100644 content/docs/prologue/quick-start.md create mode 100644 content/docs/self-hosted/_index.md create mode 100644 content/docs/self-hosted/bare-metal.md create mode 100644 content/docs/self-hosted/dependencies.md create mode 100644 content/docs/self-hosted/docker.md create mode 100644 content/docs/self-hosted/getting-started.md diff --git a/content/docs/_index.md b/content/docs/_index.md index f807c65..ec50132 100644 --- a/content/docs/_index.md +++ b/content/docs/_index.md @@ -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: [] --- diff --git a/content/docs/help/_index.md b/content/docs/help/_index.md index bc503ec..f344caf 100644 --- a/content/docs/help/_index.md +++ b/content/docs/help/_index.md @@ -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 diff --git a/content/docs/help/faq.md b/content/docs/help/faq.md index 1ec59f9..542b256 100644 --- a/content/docs/help/faq.md +++ b/content/docs/help/faq.md @@ -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 diff --git a/content/docs/help/how-to-update.md b/content/docs/help/how-to-update.md deleted file mode 100644 index 0129cdc..0000000 --- a/content/docs/help/how-to-update.md +++ /dev/null @@ -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 semantic versioning and advanced range syntax." >}} - -## Update npm packages - -Bump the versions in the `devDependencies` section of `./package.json` to your liking, and run: - -```bash -npm update -``` diff --git a/content/docs/help/troubleshooting.md b/content/docs/help/troubleshooting.md index 0d52dbb..2e20827 100644 --- a/content/docs/help/troubleshooting.md +++ b/content/docs/help/troubleshooting.md @@ -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 diff --git a/content/docs/prologue/_index.md b/content/docs/prologue/_index.md index c3c1c40..59d9e61 100644 --- a/content/docs/prologue/_index.md +++ b/content/docs/prologue/_index.md @@ -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 diff --git a/content/docs/prologue/commands.md b/content/docs/prologue/commands.md deleted file mode 100644 index b5818d1..0000000 --- a/content/docs/prologue/commands.md +++ /dev/null @@ -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 -``` diff --git a/content/docs/prologue/introduction.md b/content/docs/prologue/introduction.md index 1766779..d9c01c4 100644 --- a/content/docs/prologue/introduction.md +++ b/content/docs/prologue/introduction.md @@ -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) diff --git a/content/docs/prologue/quick-start.md b/content/docs/prologue/quick-start.md deleted file mode 100644 index a516f2a..0000000 --- a/content/docs/prologue/quick-start.md +++ /dev/null @@ -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" >}}) diff --git a/content/docs/self-hosted/_index.md b/content/docs/self-hosted/_index.md new file mode 100644 index 0000000..5d17810 --- /dev/null +++ b/content/docs/self-hosted/_index.md @@ -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: [] +--- diff --git a/content/docs/self-hosted/bare-metal.md b/content/docs/self-hosted/bare-metal.md new file mode 100644 index 0000000..7e67ebe --- /dev/null +++ b/content/docs/self-hosted/bare-metal.md @@ -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 +`` +``` diff --git a/content/docs/self-hosted/dependencies.md b/content/docs/self-hosted/dependencies.md new file mode 100644 index 0000000..df74b64 --- /dev/null +++ b/content/docs/self-hosted/dependencies.md @@ -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= \ + -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. diff --git a/content/docs/self-hosted/docker.md b/content/docs/self-hosted/docker.md new file mode 100644 index 0000000..beb8d8b --- /dev/null +++ b/content/docs/self-hosted/docker.md @@ -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 : \ + --add-host=database: \ + -e RUST_LOG=debug \ + -e DATABASE_URL="postgres://:@database:/" \ + 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 +``` diff --git a/content/docs/self-hosted/getting-started.md b/content/docs/self-hosted/getting-started.md new file mode 100644 index 0000000..507efa8 --- /dev/null +++ b/content/docs/self-hosted/getting-started.md @@ -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