From 9f1ebf0c50675928436228de93b8579946e7cb92 Mon Sep 17 00:00:00 2001 From: Matthias Date: Fri, 3 May 2024 06:52:48 +0200 Subject: [PATCH] Extract section about CORS to it's own icnlude section --- docs/freq-ui.md | 11 +++++++++++ docs/includes/cors.md | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/rest-api.md | 40 +--------------------------------------- 3 files changed, 55 insertions(+), 39 deletions(-) create mode 100644 docs/includes/cors.md diff --git a/docs/freq-ui.md b/docs/freq-ui.md index eebd5e69c..32d6cb19b 100644 --- a/docs/freq-ui.md +++ b/docs/freq-ui.md @@ -10,3 +10,14 @@ Once the bot is started in trade / dry-run mode (with `freqtrade trade`) - the U ??? Note "Looking to contribute to freqUI?" Developers should not use this method, but instead clone the corresponding use the method described in the [freqUI repository](https://github.com/freqtrade/frequi) to get the source-code of freqUI. A working installation of node will be required to build the frontend. + +!!! tip "freqUI is not required to run freqtrade" + freqUI is an optional component of freqtrade, and is not required to run the bot. + It is a frontend that can be used to monitor the bot and to interact with it - but freqtrade itself will work perfectly fine without it. + +## Configuration + +FreqUI does not have it's own configuration file - but assumes a working setup for the [rest-api](rest-api.md) is available. +Please refer to the corresponding documentation page to get setup with freqUI + +--8<-- "includes/cors.md" diff --git a/docs/includes/cors.md b/docs/includes/cors.md new file mode 100644 index 000000000..f79017747 --- /dev/null +++ b/docs/includes/cors.md @@ -0,0 +1,43 @@ +## CORS + +This whole section is only necessary in cross-origin cases (where you multiple bot API's running on `localhost:8081`, `localhost:8082`, ...), and want to combine them into one FreqUI instance. + +??? info "Technical explanation" + All web-based front-ends are subject to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) - Cross-Origin Resource Sharing. + Since most of the requests to the Freqtrade API must be authenticated, a proper CORS policy is key to avoid security problems. + Also, the standard disallows `*` CORS policies for requests with credentials, so this setting must be set appropriately. + +Users can allow access from different origin URL's to the bot API via the `CORS_origins` configuration setting. +It consists of a list of allowed URL's that are allowed to consume resources from the bot's API. + +Assuming your application is deployed as `https://frequi.freqtrade.io/home/` - this would mean that the following configuration becomes necessary: + +```jsonc +{ + //... + "jwt_secret_key": "somethingrandom", + "CORS_origins": ["https://frequi.freqtrade.io"], + //... +} +``` + +In the following (pretty common) case, FreqUI is accessible on `http://localhost:8080/trade` (this is what you see in your navbar when navigating to freqUI). +![freqUI url](assets/frequi_url.png) + +The correct configuration for this case is `http://localhost:8080` - the main part of the URL including the port. + +```jsonc +{ + //... + "jwt_secret_key": "somethingrandom", + "CORS_origins": ["http://localhost:8080"], + //... +} +``` + +!!! Tip "trailing Slash" + The trailing slash is not allowed in the `CORS_origins` configuration (e.g. `"http://localhots:8080/"`). + Such a configuration will not take effect, and the cors errors will remain. + +!!! Note + We strongly recommend to also set `jwt_secret_key` to something random and known only to yourself to avoid unauthorized access to your bot. diff --git a/docs/rest-api.md b/docs/rest-api.md index 6d2f26f19..51573b77f 100644 --- a/docs/rest-api.md +++ b/docs/rest-api.md @@ -480,42 +480,4 @@ Since the access token has a short timeout (15 min) - the `token/refresh` reques {"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODkxMTk5NzQsIm5iZiI6MTU4OTExOTk3NCwianRpIjoiMDBjNTlhMWUtMjBmYS00ZTk0LTliZjAtNWQwNTg2MTdiZDIyIiwiZXhwIjoxNTg5MTIwODc0LCJpZGVudGl0eSI6eyJ1IjoiRnJlcXRyYWRlciJ9LCJmcmVzaCI6ZmFsc2UsInR5cGUiOiJhY2Nlc3MifQ.1seHlII3WprjjclY6DpRhen0rqdF4j6jbvxIhUFaSbs"} ``` -### CORS - -This whole section is only necessary in cross-origin cases (where you multiple bot API's running on `localhost:8081`, `localhost:8082`, ...), and want to combine them into one FreqUI instance. - -??? info "Technical explanation" - All web-based front-ends are subject to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) - Cross-Origin Resource Sharing. - Since most of the requests to the Freqtrade API must be authenticated, a proper CORS policy is key to avoid security problems. - Also, the standard disallows `*` CORS policies for requests with credentials, so this setting must be set appropriately. - -Users can allow access from different origin URL's to the bot API via the `CORS_origins` configuration setting. -It consists of a list of allowed URL's that are allowed to consume resources from the bot's API. - -Assuming your application is deployed as `https://frequi.freqtrade.io/home/` - this would mean that the following configuration becomes necessary: - -```jsonc -{ - //... - "jwt_secret_key": "somethingrandom", - "CORS_origins": ["https://frequi.freqtrade.io"], - //... -} -``` - -In the following (pretty common) case, FreqUI is accessible on `http://localhost:8080/trade` (this is what you see in your navbar when navigating to freqUI). -![freqUI url](assets/frequi_url.png) - -The correct configuration for this case is `http://localhost:8080` - the main part of the URL including the port. - -```jsonc -{ - //... - "jwt_secret_key": "somethingrandom", - "CORS_origins": ["http://localhost:8080"], - //... -} -``` - -!!! Note - We strongly recommend to also set `jwt_secret_key` to something random and known only to yourself to avoid unauthorized access to your bot. +--8<-- "includes/cors.md"