From f6a6bf371c69132aaf207aabe5c508742a9c5def Mon Sep 17 00:00:00 2001 From: Aravinth Manivannan Date: Fri, 27 Oct 2023 21:39:40 +0530 Subject: [PATCH] chore: refactor --- config/_default/menus.toml | 27 +++--- .../{self-hosted => self-hosting}/_index.md | 2 +- .../bare-metal.md | 2 +- .../dependencies.md | 2 +- .../{self-hosted => self-hosting}/docker.md | 2 +- .../getting-started.md | 2 +- content/docs/terminology/_index.md | 9 -- content/docs/terminology/access-token.md | 37 -------- content/docs/terminology/cooldown-period.md | 30 ------ .../terminology/difficulty-factor/index.md | 23 ----- content/docs/terminology/visitor-threshold.md | 49 ---------- .../{introduction => webmasters}/_index.md | 4 +- .../configuring-difficulty-factor/index.md | 2 +- .../new-sitekey-adv-mode.png | Bin .../new-sitekey-easy-mode.png | Bin .../faq}/copy-sitekey.png | Bin .../sitekey => webmasters/faq}/index.md | 21 ++--- .../faq}/sitekey-in-dashboard-sidepanel.png | Bin .../installing-captcha}/copy-sitekey.png | Bin .../installing-captcha/index.md | 2 +- .../mcaptcha-widget-installation-result.png | Bin .../new-sitekey-adv-mode.png | Bin .../installing-captcha/new-sitekey-btn.png | Bin .../new-sitekey-easy-mode-filled.png | Bin .../new-sitekey-easy-mode.png | Bin .../sitekey-in-dashboard-sidepanel.png | Bin content/docs/webmasters/terminology/index.md | 86 ++++++++++++++++++ 27 files changed, 117 insertions(+), 183 deletions(-) rename content/docs/{self-hosted => self-hosting}/_index.md (85%) rename content/docs/{self-hosted => self-hosting}/bare-metal.md (99%) rename content/docs/{self-hosted => self-hosting}/dependencies.md (98%) rename content/docs/{self-hosted => self-hosting}/docker.md (98%) rename content/docs/{self-hosted => self-hosting}/getting-started.md (93%) delete mode 100644 content/docs/terminology/_index.md delete mode 100644 content/docs/terminology/access-token.md delete mode 100644 content/docs/terminology/cooldown-period.md delete mode 100644 content/docs/terminology/difficulty-factor/index.md delete mode 100644 content/docs/terminology/visitor-threshold.md rename content/docs/{introduction => webmasters}/_index.md (58%) rename content/docs/{introduction => webmasters}/configuring-difficulty-factor/index.md (98%) rename content/docs/{introduction => webmasters}/configuring-difficulty-factor/new-sitekey-adv-mode.png (100%) rename content/docs/{introduction => webmasters}/configuring-difficulty-factor/new-sitekey-easy-mode.png (100%) rename content/docs/{introduction/installing-captcha => webmasters/faq}/copy-sitekey.png (100%) rename content/docs/{terminology/sitekey => webmasters/faq}/index.md (50%) rename content/docs/{introduction/installing-captcha => webmasters/faq}/sitekey-in-dashboard-sidepanel.png (100%) rename content/docs/{terminology/sitekey => webmasters/installing-captcha}/copy-sitekey.png (100%) rename content/docs/{introduction => webmasters}/installing-captcha/index.md (99%) rename content/docs/{introduction => webmasters}/installing-captcha/mcaptcha-widget-installation-result.png (100%) rename content/docs/{introduction => webmasters}/installing-captcha/new-sitekey-adv-mode.png (100%) rename content/docs/{introduction => webmasters}/installing-captcha/new-sitekey-btn.png (100%) rename content/docs/{introduction => webmasters}/installing-captcha/new-sitekey-easy-mode-filled.png (100%) rename content/docs/{introduction => webmasters}/installing-captcha/new-sitekey-easy-mode.png (100%) rename content/docs/{terminology/sitekey => webmasters/installing-captcha}/sitekey-in-dashboard-sidepanel.png (100%) create mode 100644 content/docs/webmasters/terminology/index.md diff --git a/config/_default/menus.toml b/config/_default/menus.toml index bd789ed..1622351 100644 --- a/config/_default/menus.toml +++ b/config/_default/menus.toml @@ -1,20 +1,20 @@ [[docs]] - name = "Introduction" + name = "Webmasters" weight = 510 - identifier = "Introduction" - url = "/docs/introduction/" + identifier = "Webmasters" + url = "/docs/webmasters/" + +#[[docs]] +# name = "Terminology" +# weight = 520 +# identifier = "Terminology" +# url = "/docs/terminology/" [[docs]] - name = "Terminology" - weight = 520 - identifier = "Terminology" - url = "/docs/terminology/" - -[[docs]] - name = "Self-Hosted" + name = "Self-Hosting" weight = 530 - identifier = "Self-Hosted" - url = "/docs/self-hosted/" + identifier = "Self-Hosting" + url = "/docs/self-hosting/" [[docs]] name = "API" @@ -51,10 +51,9 @@ name = "Contact" url = "/contact/" weight = 40 - [[main]] name = "Docs" - url = "/docs/introduction/installing-captcha/" + url = "/docs/webmasters/installing-captcha/" weight = 500 diff --git a/content/docs/self-hosted/_index.md b/content/docs/self-hosting/_index.md similarity index 85% rename from content/docs/self-hosted/_index.md rename to content/docs/self-hosting/_index.md index 10b8732..80f2aba 100644 --- a/content/docs/self-hosted/_index.md +++ b/content/docs/self-hosting/_index.md @@ -1,5 +1,5 @@ --- -title : "Self-Hosted" +title : "Self-Hosting" description: "Instructions to self-host mCaptcha" lead: "" date: 2021-07-21 15:44 diff --git a/content/docs/self-hosted/bare-metal.md b/content/docs/self-hosting/bare-metal.md similarity index 99% rename from content/docs/self-hosted/bare-metal.md rename to content/docs/self-hosting/bare-metal.md index ec3e02e..f71ae10 100644 --- a/content/docs/self-hosted/bare-metal.md +++ b/content/docs/self-hosting/bare-metal.md @@ -8,7 +8,7 @@ draft: false images: [] menu: docs: - parent: "Self-Hosted" + parent: "Self-Hosting" weight: 532 toc: true --- diff --git a/content/docs/self-hosted/dependencies.md b/content/docs/self-hosting/dependencies.md similarity index 98% rename from content/docs/self-hosted/dependencies.md rename to content/docs/self-hosting/dependencies.md index e537a1d..a600cbb 100644 --- a/content/docs/self-hosted/dependencies.md +++ b/content/docs/self-hosting/dependencies.md @@ -10,7 +10,7 @@ draft: false images: [] menu: docs: - parent: "Self-Hosted" + parent: "Self-Hosting" weight: 534 toc: true --- diff --git a/content/docs/self-hosted/docker.md b/content/docs/self-hosting/docker.md similarity index 98% rename from content/docs/self-hosted/docker.md rename to content/docs/self-hosting/docker.md index e7a6ef3..bfbc648 100644 --- a/content/docs/self-hosted/docker.md +++ b/content/docs/self-hosting/docker.md @@ -7,7 +7,7 @@ draft: false images: [] menu: docs: - parent: "Self-Hosted" + parent: "Self-Hosting" weight: 533 toc: true --- diff --git a/content/docs/self-hosted/getting-started.md b/content/docs/self-hosting/getting-started.md similarity index 93% rename from content/docs/self-hosted/getting-started.md rename to content/docs/self-hosting/getting-started.md index 2c06a43..1a9f2af 100644 --- a/content/docs/self-hosted/getting-started.md +++ b/content/docs/self-hosting/getting-started.md @@ -8,7 +8,7 @@ draft: false images: [] menu: docs: - parent: "Self-Hosted" + parent: "Self-Hosting" weight: 531 toc: true --- diff --git a/content/docs/terminology/_index.md b/content/docs/terminology/_index.md deleted file mode 100644 index 4d4a5de..0000000 --- a/content/docs/terminology/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title : "Terminology" -description: "Information about terminology used in mCaptcha, some of which unique to the project" -lead: "" -date: 2022-07-27T08:48:45+00:00 -lastmod: 2020-07-27T08:48:45+00:00 -draft: false -images: [] ---- diff --git a/content/docs/terminology/access-token.md b/content/docs/terminology/access-token.md deleted file mode 100644 index 315bdbc..0000000 --- a/content/docs/terminology/access-token.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "Access token" -description: "mCaptcha implements leaky bucket algorithm to measure -current traffic levels. Cooldown period specifies the leak or the time -after which a visitor addition is decremented." -lead: "" -date: 2022-07-22 -lastmod: 2022-07-22 20:17 -draft: false -images: [] -menu: - docs: - parent: "Terminology" -weight: 521 -toc: true ---- - -When a visitor solves the CAPTCHA and sends their solution to an -mCaptcha instance, the solution will be verified for correctness. If the -solution is correct, mCaptcha will return a single use access token. - -This access token should be attached to the visitor's requited to the -protected service and the protected service should validity of the -access token with the mCaptcha instance and only allow access to -protected resource if the access token is valid. - -## Validate access token: - -```bash -curl --location --request POST 'https://mcaptcha.example.net/api/v1/pow/siteverify' \ - --header 'Content-Type: application/json' \ - --data-raw '{ - "token": "replace this with the access token presented by visitor", - "key": "replace this with the sitekey associated with the CAPTCHA" - "secret": "replace this with mCaptcha account secret, available in settings" - }' -``` diff --git a/content/docs/terminology/cooldown-period.md b/content/docs/terminology/cooldown-period.md deleted file mode 100644 index 09ba07e..0000000 --- a/content/docs/terminology/cooldown-period.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Cooldown Period" -description: "mCaptcha implements leaky bucket algorithm to measure -current traffic levels. Cooldown period specifies the leak or the time -after which a visitor addition is decremented." -lead: "" -date: 2022-07-22 -lastmod: 2022-07-22 20:17 -draft: false -images: [] -menu: - docs: - parent: "Terminology" -weight: 522 -toc: true ---- - -mCaptcha implements leaky bucket algorithm to measure -current traffic levels. Cooldown period specifies the leak or the time -after which a visitor addition is decremented. - -For instance, if initial traffic level is 0 and a user visits one -second later, the traffic level will be incremented to 1. Now, if the -cooldown period is set to 30 seconds, the traffic level will be -decremented after 30 seconds. So after 30 seconds, the traffic level will -go from 1 to 0. - -## Easy Mode: Default cooldown - -When configuring mCaptcha in [easy Mode](/docs/introduction/configuring-difficulty-factor/#easy-option), the default cooldown period is set to 30 seconds. diff --git a/content/docs/terminology/difficulty-factor/index.md b/content/docs/terminology/difficulty-factor/index.md deleted file mode 100644 index 3b24162..0000000 --- a/content/docs/terminology/difficulty-factor/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Difficulty Factor" -description: "Difficulty factor determines the time it takes to solve a CAPTCHA, there are two modes to setting difficulty factor: advance and easy, this page documents both modes." -lead: "" -date: 2022-07-22 -lastmod: 2022-07-22 20:17 -draft: false -images: [] -menu: - docs: - parent: "Terminology" -weight: 523 -toc: true ---- - -Difficulty factor determines the time it takes to solve a CAPTCHA. The -higher the difficulty factor, the longer it will take to generate a -proof of work for it to solve the CAPTCHA. - -mCaptcha's proof of work based mechanism makes it highly accessible to -people with special needs but it is important to choose the difficulty factor -with care as very high difficulty factors will make the CAPTCHA -inaccessible to users on slow devices. diff --git a/content/docs/terminology/visitor-threshold.md b/content/docs/terminology/visitor-threshold.md deleted file mode 100644 index 0191f7f..0000000 --- a/content/docs/terminology/visitor-threshold.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Visitor Threshold" -description: "Visitor threshold is used to split traffic into levels. If -the traffic level supersceedes the configured threshold, then mCaptcha will -increase difficulty factor based on the configuration provided." -lead: "" -date: 2022-07-22 -lastmod: 2022-07-22 20:17 -draft: false -images: [] -menu: - docs: - parent: "Terminology" -weight: 525 -toc: true ---- - -mCaptcha's variable difficulty factor mechanism requires a website's traffic -statistics be split into levels, so that it can deploy the right -difficulty factor for each level. - -Visitor threshold is used to traffic into levels and mCaptcha accepts a -difficulty configuration for each of these levels. When current traffic -exceeds a difficulty factor, mCaptcha will increase the difficulty -factor to the next configured level. - -For instance, consider the configuration given below: - -- Cool down period: 30 seconds - -| Level | Difficulty Factor | Visitor Threshold | -| ----- | ----------------- | ----------------- | -| 1 | 5,000 | 2,000 | -| 2 | 50,000 | 5,000 | -| 3 | 500,000 | 10,000 | -| 4 | 5,000,000 | 15,000 | - -If the website sees 2,000 requests in a 30 second window, level 1 -difficulty factor(5,000) will be deployed. If the traffic increases to -5,000 requests in a 30 second window, then difficulty factor will be -upgraded to level 2(50,000). Likewise 10,000 and 15,000 requests over 30 -seconds will result in difficulty factor being upgraded to 500,000 and -5,000,000 respectively. - -Visitor threshold is how mCaptcha determines which difficulty factor -level to deploy. mCaptcha uses leaky bucket algorithm to keep the -visitor threshold constantly updated within the configured cool down -period. So, at any given moment the, the current visitor level will be -the amount of traffic that was served in the cool down period specified. diff --git a/content/docs/introduction/_index.md b/content/docs/webmasters/_index.md similarity index 58% rename from content/docs/introduction/_index.md rename to content/docs/webmasters/_index.md index 4bc86c0..461ad84 100644 --- a/content/docs/introduction/_index.md +++ b/content/docs/webmasters/_index.md @@ -1,6 +1,6 @@ --- -title : "Introduction" -description: "Introduction to mCaptcha." +title : "Webmasters" +description: "Introduction to mCaptcha for webmasters" lead: "" date: 2020-10-06T08:48:45+00:00 lastmod: 2020-10-06T08:48:45+00:00 diff --git a/content/docs/introduction/configuring-difficulty-factor/index.md b/content/docs/webmasters/configuring-difficulty-factor/index.md similarity index 98% rename from content/docs/introduction/configuring-difficulty-factor/index.md rename to content/docs/webmasters/configuring-difficulty-factor/index.md index c163880..4bae741 100644 --- a/content/docs/introduction/configuring-difficulty-factor/index.md +++ b/content/docs/webmasters/configuring-difficulty-factor/index.md @@ -10,7 +10,7 @@ draft: false images: [] menu: docs: - parent: "Introduction" + parent: "Webmasters" weight: 512 toc: true --- diff --git a/content/docs/introduction/configuring-difficulty-factor/new-sitekey-adv-mode.png b/content/docs/webmasters/configuring-difficulty-factor/new-sitekey-adv-mode.png similarity index 100% rename from content/docs/introduction/configuring-difficulty-factor/new-sitekey-adv-mode.png rename to content/docs/webmasters/configuring-difficulty-factor/new-sitekey-adv-mode.png diff --git a/content/docs/introduction/configuring-difficulty-factor/new-sitekey-easy-mode.png b/content/docs/webmasters/configuring-difficulty-factor/new-sitekey-easy-mode.png similarity index 100% rename from content/docs/introduction/configuring-difficulty-factor/new-sitekey-easy-mode.png rename to content/docs/webmasters/configuring-difficulty-factor/new-sitekey-easy-mode.png diff --git a/content/docs/introduction/installing-captcha/copy-sitekey.png b/content/docs/webmasters/faq/copy-sitekey.png similarity index 100% rename from content/docs/introduction/installing-captcha/copy-sitekey.png rename to content/docs/webmasters/faq/copy-sitekey.png diff --git a/content/docs/terminology/sitekey/index.md b/content/docs/webmasters/faq/index.md similarity index 50% rename from content/docs/terminology/sitekey/index.md rename to content/docs/webmasters/faq/index.md index ce486a2..2811933 100644 --- a/content/docs/terminology/sitekey/index.md +++ b/content/docs/webmasters/faq/index.md @@ -1,23 +1,20 @@ --- -title: "Site key" -description: "Site key is the unique identifier associated with a CAPTCHA created on mCaptcha" +title: "Webmasters FAQ" +description: "Frequently asked questions related to using mCaptcha as a webmaster" lead: "" -date: 2022-07-22 -lastmod: 2022-07-22 20:17 +date: 2022-07-27T08:48:45+00:00 +lastmod: 2020-07-27T08:48:45+00:00 draft: false -images: [] menu: docs: - parent: "Terminology" -weight: 524 -toc: true + parent: "Webmasters" --- -Site key is a unique identifier associated with CAPTCHA configurations -created on mCaptcha. It is required to integrate a CAPTCHA with your -website. +### Easy Mode: Default cooldown period -## How to get site key? +When configuring mCaptcha in [easy mode](/docs/webmasters/configuring-difficulty-factor/#easy-option), the default cooldown period is set to 30 seconds. + +## How to get site key from dashboard? 1. Go to "Site keys" on the side panel in the dashboard diff --git a/content/docs/introduction/installing-captcha/sitekey-in-dashboard-sidepanel.png b/content/docs/webmasters/faq/sitekey-in-dashboard-sidepanel.png similarity index 100% rename from content/docs/introduction/installing-captcha/sitekey-in-dashboard-sidepanel.png rename to content/docs/webmasters/faq/sitekey-in-dashboard-sidepanel.png diff --git a/content/docs/terminology/sitekey/copy-sitekey.png b/content/docs/webmasters/installing-captcha/copy-sitekey.png similarity index 100% rename from content/docs/terminology/sitekey/copy-sitekey.png rename to content/docs/webmasters/installing-captcha/copy-sitekey.png diff --git a/content/docs/introduction/installing-captcha/index.md b/content/docs/webmasters/installing-captcha/index.md similarity index 99% rename from content/docs/introduction/installing-captcha/index.md rename to content/docs/webmasters/installing-captcha/index.md index 5c62696..b91810d 100644 --- a/content/docs/introduction/installing-captcha/index.md +++ b/content/docs/webmasters/installing-captcha/index.md @@ -8,7 +8,7 @@ draft: false images: [] menu: docs: - parent: "Introduction" + parent: "Webmasters" weight: 511 toc: true --- diff --git a/content/docs/introduction/installing-captcha/mcaptcha-widget-installation-result.png b/content/docs/webmasters/installing-captcha/mcaptcha-widget-installation-result.png similarity index 100% rename from content/docs/introduction/installing-captcha/mcaptcha-widget-installation-result.png rename to content/docs/webmasters/installing-captcha/mcaptcha-widget-installation-result.png diff --git a/content/docs/introduction/installing-captcha/new-sitekey-adv-mode.png b/content/docs/webmasters/installing-captcha/new-sitekey-adv-mode.png similarity index 100% rename from content/docs/introduction/installing-captcha/new-sitekey-adv-mode.png rename to content/docs/webmasters/installing-captcha/new-sitekey-adv-mode.png diff --git a/content/docs/introduction/installing-captcha/new-sitekey-btn.png b/content/docs/webmasters/installing-captcha/new-sitekey-btn.png similarity index 100% rename from content/docs/introduction/installing-captcha/new-sitekey-btn.png rename to content/docs/webmasters/installing-captcha/new-sitekey-btn.png diff --git a/content/docs/introduction/installing-captcha/new-sitekey-easy-mode-filled.png b/content/docs/webmasters/installing-captcha/new-sitekey-easy-mode-filled.png similarity index 100% rename from content/docs/introduction/installing-captcha/new-sitekey-easy-mode-filled.png rename to content/docs/webmasters/installing-captcha/new-sitekey-easy-mode-filled.png diff --git a/content/docs/introduction/installing-captcha/new-sitekey-easy-mode.png b/content/docs/webmasters/installing-captcha/new-sitekey-easy-mode.png similarity index 100% rename from content/docs/introduction/installing-captcha/new-sitekey-easy-mode.png rename to content/docs/webmasters/installing-captcha/new-sitekey-easy-mode.png diff --git a/content/docs/terminology/sitekey/sitekey-in-dashboard-sidepanel.png b/content/docs/webmasters/installing-captcha/sitekey-in-dashboard-sidepanel.png similarity index 100% rename from content/docs/terminology/sitekey/sitekey-in-dashboard-sidepanel.png rename to content/docs/webmasters/installing-captcha/sitekey-in-dashboard-sidepanel.png diff --git a/content/docs/webmasters/terminology/index.md b/content/docs/webmasters/terminology/index.md new file mode 100644 index 0000000..bde8934 --- /dev/null +++ b/content/docs/webmasters/terminology/index.md @@ -0,0 +1,86 @@ +--- +title: "Terminology" +description: "Information about terminology used in mCaptcha, some of which unique to the project" +lead: "" +date: 2022-07-27T08:48:45+00:00 +lastmod: 2020-07-27T08:48:45+00:00 +draft: false +menu: + docs: + parent: "Webmasters" +--- + +## Authorization token + +When a visitor solves the CAPTCHA and sends their solution to an +mCaptcha instance, the solution will be verified for correctness. If the +solution is correct, mCaptcha will return a single use authorization token. + +This authorization token should be attached to the visitor's requited to the +protected service and the protected service should validity of the +authorization token with the mCaptcha instance and only allow authorization to +protected resource if the authorization token is valid. + +## Cooldown Period + +mCaptcha implements leaky bucket algorithm to measure +current traffic levels. Cooldown period specifies the leak or the time +after which a visitor addition is decremented. + +For instance, if initial traffic level is 0 and a user visits one +second later, the traffic level will be incremented to 1. Now, if the +cooldown period is set to 30 seconds, the traffic level will be +decremented after 30 seconds. So after 30 seconds, the traffic level will +go from 1 to 0. + +## Difficulty Factor + +Difficulty factor determines the time it takes to solve a CAPTCHA. The +higher the difficulty factor, the longer it will take to generate a +proof of work for it to solve the CAPTCHA. + +mCaptcha's proof of work based mechanism makes it highly accessible to +people with special needs but it is important to choose the difficulty factor +with care as very high difficulty factors will make the CAPTCHA +inaccessible to users on slow devices. + +## Sitekey + +Site key is a unique identifier associated with CAPTCHA configurations +created on mCaptcha. It is required to integrate a CAPTCHA with your +website. + +## Visitor Threshold + +mCaptcha's variable difficulty factor mechanism requires a website's traffic +statistics be split into levels, so that it can deploy the right +difficulty factor for each level. + +Visitor threshold is used to traffic into levels and mCaptcha accepts a +difficulty configuration for each of these levels. When current traffic +exceeds a difficulty factor, mCaptcha will increase the difficulty +factor to the next configured level. + +For instance, consider the configuration given below: + +- Cool down period: 30 seconds + +| Level | Difficulty Factor | Visitor Threshold | +| ----- | ----------------- | ----------------- | +| 1 | 5,000 | 2,000 | +| 2 | 50,000 | 5,000 | +| 3 | 500,000 | 10,000 | +| 4 | 5,000,000 | 15,000 | + +If the website sees 2,000 requests in a 30 second window, level 1 +difficulty factor(5,000) will be deployed. If the traffic increases to +5,000 requests in a 30 second window, then difficulty factor will be +upgraded to level 2(50,000). Likewise 10,000 and 15,000 requests over 30 +seconds will result in difficulty factor being upgraded to 500,000 and +5,000,000 respectively. + +Visitor threshold is how mCaptcha determines which difficulty factor +level to deploy. mCaptcha uses leaky bucket algorithm to keep the +visitor threshold constantly updated within the configured cool down +period. So, at any given moment the, the current visitor level will be +the amount of traffic that was served in the cool down period specified.