Add documentation for setting up a Self-Hosted Endpoint#75
Conversation
| 1. `X-Frc-Proxy-Key`: The proxy key you generated in the Friendly Captcha dashboard. | ||
| 2. `X-Frc-Proxy-Client-IP`: The original (source) IP address of the end user. | ||
|
|
||
| As the upstream server for the proxied requests, you should specify |
There was a problem hiding this comment.
| As the upstream server for the proxied requests, you should specify | |
| Forward proxied requests to this endpoint (i.e., the upstream server): |
| As the upstream server for the proxied requests, you should specify | ||
|
|
||
| ``` | ||
| global.proxy.frcapi.com |
There was a problem hiding this comment.
| global.proxy.frcapi.com | |
| https://global.proxy.frcapi.com |
| If you have access to [the EU Endpoint](./eu-endpoint.md), you may alternatively specify | ||
|
|
||
| ``` | ||
| eu.proxy.frcapi.com |
There was a problem hiding this comment.
| eu.proxy.frcapi.com | |
| https://eu.proxy.frcapi.com |
| global.proxy.frcapi.com | ||
| ``` | ||
|
|
||
| If you have access to [the EU Endpoint](./eu-endpoint.md), you may alternatively specify |
There was a problem hiding this comment.
| If you have access to [the EU Endpoint](./eu-endpoint.md), you may alternatively specify | |
| If you have access to [the EU Endpoint](./eu-endpoint.md), you may alternatively forward proxied requests to this endpoint: |
|
Looks great! ⭐ I made some suggested changes ☝️ I didn't test any of the setup or the web server configs, though possibly the nginx config is broken due to the missing semi-colon. I'd maybe suggest using |
I didn't test them either, but good suggestion to do so—I'll spin up Docker containers for each server and make sure they work.
Done ✅ |
Co-authored-by: Jamie Nguyen <j@jamielinux.com>
Co-authored-by: Jamie Nguyen <j@jamielinux.com>
Co-authored-by: Jamie Nguyen <j@jamielinux.com>
greenberga
force-pushed
the
self-hosted-endpoint-guide
branch
from
ee27560 to
2179834
Compare
|
Glad I tested—I ended up making changes to the Apache, Caddy, and HAProxy examples! But I've gotten them to all work smoothly. And, I think I've addressed all feedback thus far. |
jamielinux
left a comment
jamielinux
left a comment
There was a problem hiding this comment.
Looks good! Just added some minor comments/suggestions.
|
|
||
| ::: | ||
|
|
||
| When a customer website or application loads a Friendly Captcha widget, the widget makes a number of requests to the Friendly Captcha API. The API endpoint is `global.frcapi.com`, or `eu.frcapi.com` for customers who use [the EU Endpoint](./eu-endpoint). Friendly Captcha offers the **Self-Hosted Endpoint** feature for customers who prefer to have all end-user traffic funneled through their own infrastructure. |
There was a problem hiding this comment.
Nitpick, but I might prefer "routed" rather than "funneled" (just because it's a more common expression used for this sort of thing and might be better understood by non-native english speakers).
| There are 3 steps to setting up a Self-Hosted Endpoint. | ||
|
|
||
| 1. Generate a proxy key in the Friendly Captcha dashboard. | ||
| 2. Configure your web server to proxy widget requests to the Friendly Captcha API. | ||
| 3. Configure your widget to use your Self-Hosted Endpoint. |
There was a problem hiding this comment.
I would maybe remove this chunk, or replace it with just To set up a Self-Hosted Endpoint, follow the 3 steps below: or similar.
Alternatively, it could be like a mini table of contents for the steps (where each bullet matches the wording of each heading and links to it).
In its current form, it's easy to miss that the bullet points match with the three steps below it (ie, at first I didn't realise that there were more instructions below).
|
|
||
| ### 2. Configure your web server | ||
|
|
||
| Your web server needs to be configured to forward the widget requests to the Friendly Captcha API. These are the requests that must be forwarded: |
There was a problem hiding this comment.
Generally active voice is considered better for documentation. So, something like this instead for example:
You need to configure your web server to forward the following requests to the Friendly Captcha API:
There's a few more places like this but it's up to you if you want to tweak them.
|
|
||
| To verify that proxied widget requests come from your infrastructure, you must set a header that contains a proxy key. You can generate a key in the [Friendly Captcha dashboard](https://app.friendlycaptcha.eu/dashboard/accounts/-/keys). Make sure to generate a **Proxy Key**; API keys are not accepted. Store the generated key somewhere safe and retrievable—Friendly Captcha doesn't keep a copy of the key, so you will need to regenerate it if you lose it. | ||
|
|
||
| All proxied requests need to send your proxy key as the value of the `X-Frc-Proxy-Key` header. |
There was a problem hiding this comment.
Maybe we don't need this sentence, as it's detailed in step 2.
Or you could replace it to say:
You will need this proxy key in the next step.
Reasoning: the sentence in its current form means someone might ask themselves "ok, but how do I do that?" and not realise immediately that it's detailed in the next step.
| http-request set-header X-Frc-Proxy-Key "<% PROXY KEY %>" | ||
| http-request set-header X-Frc-Proxy-Client-IP %[src] | ||
|
|
||
| server frc_api global.proxy.frcapi.com:443 ssl verify required ca-file /etc/ssl/certs/ca-certificates.crt |
There was a problem hiding this comment.
The path to the CA certificates depends on the Linux distribution, so it's worth putting in a note about this somewhere just saying the path depends on your OS.
/etc/ssl/certs/ca-certificates.crt is for Linux distributions based on Debian/Ubuntu. /etc/pki/tls/certs/ca-bundle.crt is for Linux distributions based on Red Hat Enterprise Linux.
2 participants
No description provided.