Skip to content

Commit fe8e595

Browse files
zacModedekobon
zacMode
authored and
dekobon
committed
Format env variables as table
This documents which env variables are optional (resolves #61 ), based on my recent experience trying to use this. I reformatted some of the inline metadata (allowed values, and default values) as separate columns, only using previously provided content. Something that was confusing to me when i was first trying to get this running a few days ago, and remains confusing - what does `default` mean when the variable is required? For example, `ALLOW_DIRECTORY_LIST` claims to a default value of `false`, but i was required to provide it.
1 parent 1aaacc3 commit fe8e595

File tree

1 file changed

+24
-35
lines changed

1 file changed

+24
-35
lines changed

‎docs/getting_started.md

Lines changed: 24 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -13,41 +13,30 @@
1313
The following environment variables are used to configure the gateway when
1414
running as a Container or as a Systemd service.
1515

16-
* `ALLOW_DIRECTORY_LIST` - Flag (true/false) enabling directory listing (default: false)
17-
* `PROVIDE_INDEX_PAGE` - Flag (true/false) which returns the index page if there is one when requesting a directory. Cannot be enabled with `ALLOW_DIRECTORY_LIST`. (default: false)
18-
* `APPEND_SLASH_FOR_POSSIBLE_DIRECTORY` - Flag (true/false) enabling the return a 302 with a `/` appended to the path. This is independent of the behavior selected in `ALLOW_DIRECTORY_LIST` or `PROVIDE_INDEX_PAGE`. (default: false)
19-
* `AWS_SIGS_VERSION` - AWS Signatures API version - either 2 or 4
20-
* `DNS_RESOLVERS` - (optional) DNS resolvers (separated by single spaces) to configure NGINX with
21-
* `S3_ACCESS_KEY_ID` - Access key
22-
* `S3_BUCKET_NAME` - Name of S3 bucket to proxy requests to
23-
* `S3_DEBUG` - Flag (true/false) enabling AWS signatures debug output (default: false)
24-
* `S3_REGION` - Region associated with API
25-
* `S3_SECRET_KEY` - Secret access key
26-
* `S3_SERVER_PORT` - SSL/TLS port to connect to
27-
* `S3_SERVER_PROTO` - Protocol to used connect to S3 server - `http` or `https`
28-
* `S3_SERVER` - S3 host to connect to
29-
* `S3_STYLE` - The S3 host/path method - `virtual`, `path` or `default`. `virtual` is
30-
the method that that uses DNS-style bucket+hostname:port.
31-
This is the `default` value. `path` is a method that appends the bucket name
32-
as the first directory in the URI's path. This method is used by many S3
33-
compatible services. See this
34-
[AWS blog article](https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/)
35-
for further information.
36-
* `PROXY_CACHE_VALID_OK` - Sets caching time for response code 200 and 302
37-
* `PROXY_CACHE_VALID_NOTFOUND` - Sets caching time for response code 404
38-
* `PROXY_CACHE_VALID_FORBIDDEN` - Sets caching time for response code 403
39-
* `JS_TRUSTED_CERT_PATH` - (optional) Enables the `js_fetch_trusted_certificate` directive when retrieving AWS credentials and sets the path (on the container) to the specified path
40-
* `HEADER_PREFIXES_TO_STRIP` - (optional) a list of HTTP header prefixes that exclude headers client responses. List should be specified in lower-case and a semicolon (;) should be used to as a deliminator between values. For example: `x-goog-;x-something-`
41-
* `CORS_ENABLED` - Flag (true/false) that enables CORS headers on GET
42-
requests and enables pre-flight OPTIONS requests. If enabled, this will
43-
add CORS headers for "fully open" cross domain requests by default,
44-
meaning all domains are allowed, similar to the settings show in
45-
[this example](https://enable-cors.org/server_nginx.html).
46-
CORS settings can be fine-tuned by overwriting the
47-
[`cors.conf.template`](/common/etc/nginx/templates/gateway/cors.conf.template) file. (default: false)
48-
* `CORS_ALLOWED_ORIGIN` - (optional) value to set to be returned from the
49-
CORS `Access-Control-Allow-Origin` header. This value is only used if
50-
CORS is enabled. (default: *)
16+
| Name | Required? | Allowed Values | Default | Description |
17+
| ------------------------------------- | --------- | ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18+
| `ALLOW_DIRECTORY_LIST` | Yes | `true`, `false` | `false` | Flag enabling directory listing |
19+
| `AWS_SIGS_VERSION` | Yes | 2, 4 | | AWS Signatures API version |
20+
| `S3_ACCESS_KEY_ID` | Yes | | | Access key |
21+
| `S3_SECRET_KEY` | Yes | | | Secret access key |
22+
| `S3_BUCKET_NAME` | Yes | | | Name of S3 bucket to proxy requests to |
23+
| `S3_REGION` | Yes | | | Region associated with API |
24+
| `S3_SERVER_PORT` | Yes | | | SSL/TLS port to connect to |
25+
| `S3_SERVER_PROTO` | Yes | `http`, `https` | | Protocol to used connect to S3 server |
26+
| `S3_SERVER` | Yes | | | S3 host to connect to |
27+
| `S3_STYLE` | Yes | `virtual`, `path`, `default` | `default` | The S3 host/path method. <li>`virtual` is the method that that uses DNS-style bucket+hostname:port. This is the `default` value. <li>`path` is a method that appends the bucket name as the first directory in the URI's path. This method is used by many S3 compatible services. <br/><br/>See this [AWS blog article](https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/) for further information. |
28+
| `S3_DEBUG` | No | `true`, `false` | `false` | Flag enabling AWS signatures debug output |
29+
| `APPEND_SLASH_FOR_POSSIBLE_DIRECTORY` | No | `true`, `false` | `false` | Flag enabling the return a 302 with a `/` appended to the path. This is independent of the behavior selected in `ALLOW_DIRECTORY_LIST` or `PROVIDE_INDEX_PAGE`. |
30+
| `DNS_RESOLVERS` | No | | | DNS resolvers (separated by single spaces) to configure NGINX with |
31+
| `PROXY_CACHE_VALID_OK` | No | | | Sets caching time for response code 200 and 302 |
32+
| `PROXY_CACHE_VALID_NOTFOUND` | No | | | Sets caching time for response code 404 |
33+
| `PROXY_CACHE_VALID_FORBIDDEN` | No | | | Sets caching time for response code 403 |
34+
| `PROVIDE_INDEX_PAGE` | No | `true`, `false` | `false` | Flag which returns the index page if there is one when requesting a directory. Cannot be enabled with `ALLOW_DIRECTORY_LIST`. |
35+
| `JS_TRUSTED_CERT_PATH` | No | | | Enables the `js_fetch_trusted_certificate` directive when retrieving AWS credentials and sets the path (on the container) to the specified path |
36+
| `HEADER_PREFIXES_TO_STRIP` | No | | | A list of HTTP header prefixes that exclude headers client responses. List should be specified in lower-case and a semicolon (;) should be used to as a deliminator between values. For example: `x-goog-;x-something-` |
37+
| `CORS_ENABLED` | No | `true`, `false` | `false` | Flag that enables CORS headers on GET requests and enables pre-flight OPTIONS requests. If enabled, this will add CORS headers for "fully open" cross domain requests by default, meaning all domains are allowed, similar to the settings show in [this example](https://enable-cors.org/server_nginx.html). CORS settings can be fine-tuned by overwriting the [`cors.conf.template`](/common/etc/nginx/templates/gateway/cors.conf.template) file. |
38+
| `CORS_ALLOWED_ORIGIN` | No | | | value to set to be returned from the CORS `Access-Control-Allow-Origin` header. This value is only used if CORS is enabled. (default: \*) |
39+
5140

5241
If you are using [AWS instance profile credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html),
5342
you will need to omit the `S3_ACCESS_KEY_ID` and `S3_SECRET_KEY` variables from

0 commit comments

Comments
 (0)