|
| 1 | +--- |
| 2 | +sidebar_position: 3 |
| 3 | +--- |
| 4 | + |
| 5 | +# Advanced topics |
| 6 | + |
| 7 | +## Routing requests to specific path |
| 8 | + |
| 9 | +Since Traefik supports routing requests to specific path, you can also do that with Exoframe. |
| 10 | +By default, Exoframe generates the following frontend string: |
| 11 | + |
| 12 | +```js |
| 13 | +// where config is project config json |
| 14 | +Labels[`traefik.http.routers.${name}.rule`] = config.domain.includes('Host(') |
| 15 | + ? // if string already contains Host() - use it as is |
| 16 | + config.domain |
| 17 | + : // otherwise - wrap it into Host() |
| 18 | + `Host(\`${config.domain}\`)`; |
| 19 | +``` |
| 20 | + |
| 21 | +You can route requests to path instead by using Traefik [router rules](https://docs.traefik.io/routing/routers/#rule) and using them inside of `domain` field in config. |
| 22 | +For example, you can route requests from `http://bots.domain.com/myhook` to your service. |
| 23 | +To achieve this, you will need to simply set `domain` field in the config file to ``Host(`bots.domain.com`) && Path(`/myhook`)``. |
| 24 | +This will route all requests from `bots.domain.com/myhook` to `your.service.host/myhook`. |
| 25 | + |
| 26 | +If you need to strip or replace path, you have to provide additional label for Traefik. |
| 27 | +E.g. the following config will route `domain.com/myprefix` to `your.service.host`: |
| 28 | + |
| 29 | +```json |
| 30 | +{ |
| 31 | + "domain": "Host(`domain.com`) && Path(`/myprefix`)", |
| 32 | + "labels": { |
| 33 | + "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes": "/myprefix" |
| 34 | + } |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +For more info and options see the aforementioned Traefik [router rules](https://docs.traefik.io/routing/routers/#rule) as well as [middlewares](https://docs.traefik.io/middlewares/overview/) docs. |
| 39 | + |
| 40 | +## Docker-compose based deployment |
| 41 | + |
| 42 | +Deploying using docker compose works almost the same as using a normal docker compose file, but there are a few labels you should use to ensure Traefik can correctly access your application. |
| 43 | + |
| 44 | + version: '2' |
| 45 | + services: |
| 46 | + web: |
| 47 | + build: . |
| 48 | + labels: |
| 49 | + traefik.http.routers.web.rule: 'Host(`test.dev`)' |
| 50 | + redis: |
| 51 | + image: "redis:alpine" |
| 52 | + |
| 53 | +Any of the [configuration options](https://docs.traefik.io/reference/dynamic-configuration/docker/) for the default Traefik docker setup can be used. |
| 54 | + |
| 55 | +If you have a docker-compose.yml file, **any domain set in exoframe.json will be ignored**. |
| 56 | + |
| 57 | +For the most part, Exoframe doesn't pass anything from `exoframe.json` to the compose. |
| 58 | +However, one thing that is being passed is environmental variables. |
| 59 | +You can use any variables defined in `exoframe.json` in your compose file. |
| 60 | +First, define them in your `exoframe.json`: |
| 61 | + |
| 62 | +```json |
| 63 | +{ |
| 64 | + "name": "test-compose-deploy", |
| 65 | + "env": { |
| 66 | + "CUSTOM_LABEL": "custom-value", |
| 67 | + "CUSTOM_SECRET": "@test-secret" |
| 68 | + } |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +Then use them inside your `docker-compose.yml`: |
| 73 | + |
| 74 | +```yaml |
| 75 | +version: '2' |
| 76 | +services: |
| 77 | + web: |
| 78 | + build: . |
| 79 | + labels: |
| 80 | + traefik.http.routers.web.rule: 'Host(`test.dev`)' |
| 81 | + custom.envvar: '${CUSTOM_LABEL}' |
| 82 | + custom.secret: '${CUSTOM_SECRET}' |
| 83 | + redis: |
| 84 | + image: 'redis:alpine' |
| 85 | +``` |
| 86 | +
|
| 87 | +## Rate limiting |
| 88 | +
|
| 89 | +Exoframe allows you to enable basic IP-based rate-limiting integrated into Traefik. |
| 90 | +To do that, simply specify the following fields in the project config file: |
| 91 | +
|
| 92 | +```js |
| 93 | +{ |
| 94 | + // adding this object will enable IP-based rate-limiting |
| 95 | + "rate-limit": { |
| 96 | + // average request rate over given time period |
| 97 | + // defaults to 1 if not specified |
| 98 | + "average": 5, |
| 99 | + // maximal burst request rate over given time period |
| 100 | + // defaults to 5 if not specified |
| 101 | + "burst": 10 |
| 102 | + } |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +This will define how many requests (`average`) over given time (`period`) can be performed from one IP address. |
| 107 | +For the example above - an average of 5 requests every second is allowed with busts of up to 10 requests. |
| 108 | + |
| 109 | +For more information, see [Traefik rate-limiting docs](https://docs.traefik.io/middlewares/ratelimit/). |
| 110 | + |
| 111 | +## Secrets |
| 112 | + |
| 113 | +Exoframe allows you to create server-side secret values that can be used during service deployments. |
| 114 | +To use secrets you first need to create one. This can be done by running: |
| 115 | + |
| 116 | +``` |
| 117 | +$ exoframe secret new |
| 118 | +``` |
| 119 | + |
| 120 | +Once you specify the name and value, Exoframe server will create new secret _for your current user_. |
| 121 | +After creation the secret can be used in `exoframe.json` config file by using secret name and prefixing it with `@`, like so (in this example the secret was name `my-secret`): |
| 122 | + |
| 123 | +```json |
| 124 | +"env": { |
| 125 | + "SECRET_KEY": "@my-secret" |
| 126 | +}, |
| 127 | +``` |
| 128 | + |
| 129 | +Current caveats: |
| 130 | + |
| 131 | +- Currently secrets only work for environment variables |
| 132 | +- Currently secrets work only for normal deployments (any template or recipe that uses `startFromParams` won't have secrets expanded) |
| 133 | + |
| 134 | +## Accessing Exoframe data from within the deployed application |
| 135 | + |
| 136 | +Exoframe provides a set of environment variables that are set on each deployment to allow getting project info and settings. |
| 137 | +Currently those are: |
| 138 | + |
| 139 | +```bash |
| 140 | +# owner of current deployment |
| 141 | +EXOFRAME_USER=admin |
| 142 | +# project of current deployment |
| 143 | +EXOFRAME_PROJECT=projectName |
| 144 | +# full deployment ID |
| 145 | +EXOFRAME_DEPLOYMENT=exo-admin-deployName-ID |
| 146 | +# host used to expose current deployment (if any) |
| 147 | +EXOFRAME_HOST=exo-admin-deployName-ID.baseDomain |
| 148 | +``` |
| 149 | + |
| 150 | +## Plugins |
| 151 | + |
| 152 | +Exoframe-Server supports extension of core features using plugins. |
| 153 | +Plugins are installed and loaded automatically once corresponding config is added to [server configuration](./server.md). |
| 154 | +Refer to specific plugins docs to see how to configure them. |
0 commit comments