Configuration Self-Management
To simplify the Padawan experience, we have implemented a self-management feature to allow customers to configure some of the most common site options. To mimic one of the most widely used commercial platforms (Netlify) we have chosen to use a padawan.toml
file to specify custom configs.
Getting Started
Simply create a padawan.toml
file in your code repo's root directory then Padawan will transform it into a custom NGINX config and deploy it along with your built site. Start by copying the Full Example into your padawan.toml
, change the options to suit your site's needs, and deploy your site to staging.
Pipelines and Troubleshooting
Once a padawan.toml
file is at the root of your code repo, the Padawan Pipeline will run a config
stage consisting of a compute-site-config
and validate-site-config
job:
compute-site-config
This job is responsible for parsing your padawan.toml
file into an NGINX location
block specific to your site. To help in debugging, it prints out the location
block, such as:
location ^~ /sites/vanilla-hello-world/ {
add_header Content-Security-Policy "default-src 'self';" always;
add_header X-POWERED-BY "Party Bus Padawan https://padawan-docs.dso.mil/" always;
}
validate-site-config
Since Padawan is a multi-tenant hosting framework, an invalid site config would take down other sites. We have multiple configuration validity checks implemented throughout the build and deploy process. The validate-site-config
job is our "build-time" validation check to ensure that the NGINX configs created by compute-site-config
are valid. The job and your pipeline will fail if the generated config is not valid.
Full Example
Example padawan.toml
file illustrating all the available options:
# The format version of this Padawan config file.
# If omitted, the config parser will assume the latest version.
padawan_config_version = 1
# If disabled, redirects issued by nginx will be relative.
#
# values: on | off
# default: on
#
# see:
# https://nginx.org/en/docs/http/ngx_http_core_module.html#absolute_redirect
absolute_redirect = "on"
# Enable if your site is a SPA (single page application)
# values: true | false
# default: false
#
# if true, will use the nginx try_files directive to account for the site always having the
# entrypoint index.html. when enabled, sites will be responsible for handling their own
# 404 page, as every http request will serve index.html
#
# see:
# https://en.wikipedia.org/wiki/Single-page_application
# https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files
is_single_page_application = false
# Enables custom routing rules.
# Currently only supports the `add_trailing_slash` option
[routing]
# If true, will redirect to a url containing a trailing slash on directory-like urls.
# default: false
# For example, a request to `/my-site/section-a` would redirect to `/my-site/section-a/`. This
# can be important if your `/my-site/section-a/index.html` file uses relative urls, which would
# attempt to load files from completely different directories when a trailing slash is omitted
# from the url.
add_trailing_slash = false
# Allows fine-grained control over the nginx try_files directive.
# Will overwrite the nginx config generated when `is_single_page_application=true`
#
# see:
# https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files
[[try_files]]
for = "/*"
uris = [
"$uri",
"$uri/",
"/404/index.html"
]
# Specify site-specific headers.
# Can be set by site subpath, but the common use case is to use the same headers across the entire
# site with `for = "/*"`
#
# see:
# https://docs.netlify.com/configure-builds/file-based-configuration/#headers
[[headers]]
# Define which paths this specific [[headers]] block will cover.
for = "/*"
[headers.values]
# Note: it is important to use double quotes surrounding your header values and single quotes inside
Content-Security-Policy = "default-src 'self'; base-uri 'self'; script-src 'self' *.dso.mil 'nonce-$cspNonce'; script-src-elem 'self' *.dso.mil 'nonce-$cspNonce'; style-src 'self' *.dso.mil 'nonce-$cspNonce'; style-src-elem 'self' *.dso.mil 'nonce-$cspNonce'; img-src 'self' data: mediastream: blob: *.dso.mil 'nonce-$cspNonce'; connect-src 'self' *.dso.mil 'nonce-$cspNonce'; font-src 'self' *.dso.mil 'nonce-$cspNonce'; object-src 'self' *.dso.mil 'nonce-$cspNonce'; media-src 'self' *.dso.mil 'nonce-$cspNonce'; manifest-src 'self' *.dso.mil; form-action 'self' *.dso.mil; frame-src 'none'; frame-ancestors 'none';"
X-POWERED-BY = "Party Bus Padawan https://padawan-docs.dso.mil/"
FAQs
Q: What environments can I use this feature in?
The configuration self-management feature is currently available in IL2 (staging/production) and IL4 (staging/production).
Q: Does this mean I can specify my own Content-Security-Policy header without reaching out to the Padawan team?
Yes! We created this feature to enable customers to move faster and more independently. We recommend following Content-Security-Policy best practices, but the fact that all sites are "static sites" on Padawan means that much of the XSS risk is already mitigated.
Q: Will you be supporting any more configuration options?
Yes! Let us know in the Padawan Help Channel which additional options you want to be able to set in padawan.toml
. For options that currently aren't supported, we'll work with you to create a custom config and then work to make it a self-management feature so it can be available to every customer.
Q: What if I've already worked with the Padawan team to create a custom config?
No problem! The configs specified in padawan.toml
will override your existing custom configuration. You aren't required to use this new self-management feature if you don't want to; we won't delete your existing custom config.
Q: Will you be updating all the Padawan Example Repos with the padawan.toml
file?
Yes, any example repo that requires a custom site config will be updated to use a padawan.toml
file. We're in the process of doing this now!