From fc2f02e4ee1c7a036a21ec1f1f65bf1374ed2260 Mon Sep 17 00:00:00 2001 From: Rui Carmo Date: Wed, 28 Dec 2022 20:30:08 +0000 Subject: [PATCH] add docs for caching --- docs/ENV.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/ENV.md b/docs/ENV.md index 44dfcaa..ecd5fb3 100644 --- a/docs/ENV.md +++ b/docs/ENV.md @@ -14,7 +14,7 @@ You can configure deployment settings by placing special variables in an `ENV` f * `NODE_VERSION`: installs a particular version of node for your app if `nodeenv` is found on the path. -**Note**: you will need to stop and re-deploy the app to change the node version in a running app. +> **NOTE**: you will need to stop and re-deploy the app to change the `node` version in a running app. ## Network Settings @@ -33,17 +33,39 @@ You can configure deployment settings by placing special variables in an `ENV` f * `UWSGI_GEVENT`: enable the Python 2 `gevent` plugin * `UWSGI_ASYNCIO` (integer): enable the Python 2/3 `asyncio` plugin and set the number of tasks * `UWSGI_INCLUDE_FILE`: a uwsgi config file in the app's dir to include - useful for including custom uwsgi directives. -* `UWSGI_IDLE` (integer): set the `cheap`, `idle` and `die-on-idle` options to have workers spawned on demand and killed after _n_ seconds of inactivity. +* `UWSGI_IDLE` (integer): set the `cheap`, `idle` and `die-on-idle` options to have workers spawned on demand and killed after _n_ seconds of inactivity. -## Nginx Settings +> **NOTE:** `UWSGI_IDLE` applies to _all_ the workers, so if you have `UWSGI_PROCESSES` set to 4, they will all be killed simultaneously. Support for progressive scaling of workers via `cheaper` and similar uWSGI configurations will be added in the future. + +## `nginx` Settings * `NGINX_SERVER_NAME`: set the virtual host name associated with your app +* `NGINX_STATIC_PATHS` (string, comma separated list): set an array of `/url:path` values that will be served directly by `nginx` * `NGINX_CLOUDFLARE_ACL` (boolean, defaults to `false`): activate an ACL allowing access only from Cloudflare IPs -* `NGINX_STATIC_PATHS`: set an array of `/url:path` values * `NGINX_HTTPS_ONLY` (boolean, defaults to `false`): tell `nginx` to auto-redirect non-SSL traffic to SSL site. > **NOTE:** if used with Cloudflare, `NGINX_HTTPS_ONLY` will cause an infinite redirect loop - keep it set to `false`, use `NGINX_CLOUDFLARE_ACL` instead and add a Cloudflare Page Rule to "Always Use HTTPS" for your server (use `domain.name/*` to match all URLs). +### `nginx` Caching + +When `NGINX_CACHE_PREFIXES` is set, `nginx` will cache requests for those URL prefixes to the running application (`uwsgi`-like or `web` workers) and reply on its own for `NGINX_CACHE_TIME` to the outside. This is meant to be used for compute-intensive operations like resizing images or providing large chunks of data that change infrequently (like a sitemap). + +The behavior of the cache can be controlled with the following variables: + +* `NGINX_CACHE_PREFIXES` (string, comma separated list): set an array of `/url` values that will be cached by `nginx` +* `NGINX_CACHE_SIZE` (integer, defaults to 1): set the maximum size of the `nginx` cache, in GB +* `NGINX_CACHE_TIME` (integer, defaults to 8): set the amount of time (in hours) that valid backend replies will be cached. +* `NGINX_CACHE_EXPIRY` (integer, defaults to 1): set the amount of time (in days) that cache entries will be kept on disk. +* `NGINX_CACHE_PATH` (string, detaults to `~piku/.piku//cache`): location for the `nginx` cache data. + +> **NOTE:** `NGINX_CACHE_PATH` will be _completely managed by `nginx` and cannot be removed by Piku when the application is destroyed_. This is because `nginx` sets the ownership for the cache to be exclusive to itself, and the `piku` user cannot remove that file tree. So you will either need to clean it up manually after destroying the app or store it in a temporary filesystem (or set the `piku` user to the same UID as `www-data`, which is not recommended). + +Right now, there is no provision for cache revalidation (i.e., `nginx` asking your backend if the cache entries are still valid), since that requires active application logic that varies depending on the runtime--`nginx` will only ask your backend for new content when `NGINX_CACHE_TIME` elapses. If you require that kind of behavior, that is still possible via `NGINX_INCLUDE_FILE`. + +Also, keep in mind that using `nginx` caching with a `static` website worker will _not_ work (and there's no point to it either). + +### `nginx` Overrides + * `NGINX_INCLUDE_FILE`: a file in the app's dir to include in nginx config `server` section - useful for including custom `nginx` directives. * `NGINX_ALLOW_GIT_FOLDERS`: (boolean) allow access to `.git` folders (default: false, blocked)