# Reference: applications

URL: https://scalws.com/docs/reference/applications/
Source: `docs/reference/schema` in the ScalWS repository

<h3 id="tenants-.applications"><code>tenants[].applications</code></h3>

| | |
|---|---|
| Syntax | `applications: [{...}, ...]` |
| Default | `[]` |
| Context | `tenants[]` |
| Reload | applies on reload |

Applications of the tenant.


<h3 id="tenants-.applications-.acme"><code>tenants[].applications[].acme</code></h3>

| | |
|---|---|
| Syntax | `acme: true \| false` |
| Default | `false` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Obtain and renew a certificate for all `domains` via ACME (ADR-0018).


<h3 id="tenants-.applications-.cache"><code>tenants[].applications[].cache</code></h3>

| | |
|---|---|
| Syntax | `cache: {...}` |
| Default | `none` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Response cache for this application (ADR-0012); absent: no caching.


<h3 id="tenants-.applications-.cache.bypass_cookies"><code>tenants[].applications[].cache.bypass_cookies</code></h3>

| | |
|---|---|
| Syntax | `bypass_cookies: [<string>, ...]` |
| Default | `[]` |
| Context | `tenants[].applications[].cache` |
| Reload | applies on reload |

Cookie-name prefixes that mark a personalised request (added to the profile's).


<h3 id="tenants-.applications-.cache.bypass_paths"><code>tenants[].applications[].cache.bypass_paths</code></h3>

| | |
|---|---|
| Syntax | `bypass_paths: [<string>, ...]` |
| Default | `[]` |
| Context | `tenants[].applications[].cache` |
| Reload | applies on reload |

Path prefixes that are never cached (added to the profile's).


<h3 id="tenants-.applications-.cache.bypass_query"><code>tenants[].applications[].cache.bypass_query</code></h3>

| | |
|---|---|
| Syntax | `bypass_query: [<string>, ...]` |
| Default | `[]` |
| Context | `tenants[].applications[].cache` |
| Reload | applies on reload |

Query parameters that disable caching (added to the profile's).


<h3 id="tenants-.applications-.cache.default_ttl"><code>tenants[].applications[].cache.default_ttl</code></h3>

| | |
|---|---|
| Syntax | `default_ttl: <duration> (e.g. 30s)` |
| Default | `none` |
| Context | `tenants[].applications[].cache` |
| Reload | applies on reload |

Freshness for `200` responses that carry no caching headers at all. Default: none (only explicitly cacheable responses are stored).


<h3 id="tenants-.applications-.cache.enabled"><code>tenants[].applications[].cache.enabled</code></h3>

| | |
|---|---|
| Syntax | `enabled: true \| false` |
| Default | `true` |
| Context | `tenants[].applications[].cache` |
| Reload | applies on reload |

Cache this application's responses.


<h3 id="tenants-.applications-.cache.stale_while_revalidate"><code>tenants[].applications[].cache.stale_while_revalidate</code></h3>

| | |
|---|---|
| Syntax | `stale_while_revalidate: <duration> (e.g. 30s)` |
| Default | `none` |
| Context | `tenants[].applications[].cache` |
| Reload | applies on reload |

Serve stale entries this long while refreshing in the background.


<h3 id="tenants-.applications-.domains"><code>tenants[].applications[].domains</code></h3>

| | |
|---|---|
| Syntax | `domains: [<string>, ...]` |
| Default | `required` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Domains served by the application; `*.example.com` matches one label, `**.example.com` one or more; `"*"` (at most one application per listener) serves the hosts no other domain matches; a domain may be served once per listener.


<h3 id="tenants-.applications-.htaccess"><code>tenants[].applications[].htaccess</code></h3>

| | |
|---|---|
| Syntax | `htaccess: true \| false` |
| Default | `false` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Read Apache `.htaccess` files below `root` (ADR-0031).


<h3 id="tenants-.applications-.https_redirect"><code>tenants[].applications[].https_redirect</code></h3>

| | |
|---|---|
| Syntax | `https_redirect: true \| false` |
| Default | `none` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Answer plain-HTTP requests with a 301 to the same URL over HTTPS (ACME HTTP-01 challenges are still answered over HTTP).


<h3 id="tenants-.applications-.listeners"><code>tenants[].applications[].listeners</code></h3>

| | |
|---|---|
| Syntax | `listeners: [<string>, ...]` |
| Default | `none` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Listeners (by name) that serve the application; empty: every listener.


<h3 id="tenants-.applications-.name"><code>tenants[].applications[].name</code></h3>

| | |
|---|---|
| Syntax | `name: <string>` |
| Default | `required` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Application name, unique within the tenant: 1-63 characters of a-z, 0-9, `-`, `_`.


<h3 id="tenants-.applications-.profile"><code>tenants[].applications[].profile</code></h3>

| | |
|---|---|
| Syntax | `profile: <string>` |
| Default | `none` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Application profile (ADR-0011), e.g. `wordpress`. Supplies the runtime when `runtime` is omitted (static profiles only) and defaults such as health checks.


<h3 id="tenants-.applications-.root"><code>tenants[].applications[].root</code></h3>

| | |
|---|---|
| Syntax | `root: <string>` |
| Default | `none` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Application root directory; default document root for `static` runtimes.


<h3 id="tenants-.applications-.root_symlinks"><code>tenants[].applications[].root_symlinks</code></h3>

| | |
|---|---|
| Syntax | `root_symlinks: follow \| refuse` |
| Default | `none` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Symbolic links in the path of the document roots (`root` and the runtimes' own `root`): `follow` (default) or `refuse`. With `refuse` a root must be an absolute path without `.`, `..` or a symbolic link in any component; it is opened without following links, so the owner of a directory on the way cannot point the site at another directory. For roots inside home directories of other users (hosting panels).


<h3 id="tenants-.applications-.runtime"><code>tenants[].applications[].runtime</code></h3>

| | |
|---|---|
| Syntax | `runtime: {...}` |
| Default | `none` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Handles every request no route matches. Required unless a `profile` supplies it or `routes` is not empty; then unmatched requests get 404.


<h3 id="tenants-.applications-.security"><code>tenants[].applications[].security</code></h3>

| | |
|---|---|
| Syntax | `security: {...}` |
| Default | `none` |
| Context | `tenants[].applications[]` |
| Reload | applies on reload |

Per-application deny paths and rate limits.


<h3 id="tenants-.applications-.security.deny_paths"><code>tenants[].applications[].security.deny_paths</code></h3>

| | |
|---|---|
| Syntax | `deny_paths: [<string>, ...]` |
| Default | `[]` |
| Context | `tenants[].applications[].security` |
| Reload | applies on reload |

Denied paths (added to the profile's); `*` matches any characters.


<h3 id="tenants-.applications-.security.ignore_profile_rules"><code>tenants[].applications[].security.ignore_profile_rules</code></h3>

| | |
|---|---|
| Syntax | `ignore_profile_rules: true \| false` |
| Default | `false` |
| Context | `tenants[].applications[].security` |
| Reload | applies on reload |

Do not apply the profile's deny rules.


<h3 id="tenants-.applications-.security.rate_limits"><code>tenants[].applications[].security.rate_limits</code></h3>

| | |
|---|---|
| Syntax | `rate_limits: [{...}, ...]` |
| Default | `[]` |
| Context | `tenants[].applications[].security` |
| Reload | applies on reload |

Request rates per client address for matching paths (first match applies).


<h3 id="tenants-.applications-.security.rate_limits-.burst"><code>tenants[].applications[].security.rate_limits[].burst</code></h3>

| | |
|---|---|
| Syntax | `burst: <integer>` |
| Default | `none` |
| Context | `tenants[].applications[].security.rate_limits[]` |
| Reload | applies on reload |

Token-bucket burst (default: equal to the rate).


<h3 id="tenants-.applications-.security.rate_limits-.path"><code>tenants[].applications[].security.rate_limits[].path</code></h3>

| | |
|---|---|
| Syntax | `path: <string>` |
| Default | `required` |
| Context | `tenants[].applications[].security.rate_limits[]` |
| Reload | applies on reload |

Path prefix the limit applies to.


<h3 id="tenants-.applications-.security.rate_limits-.requests_per_second"><code>tenants[].applications[].security.rate_limits[].requests_per_second</code></h3>

| | |
|---|---|
| Syntax | `requests_per_second: <integer>` |
| Default | `required` |
| Context | `tenants[].applications[].security.rate_limits[]` |
| Reload | applies on reload |

Sustained requests per second per client address on this path.