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 `trailing_slash` OR `add_trailing_slash` options.
[routing]
  # If "remove", will redirect to a url without a trailing slash on all urls.
  # If "add", will redirect to a url with a trailing slash on directory-like urls.
  # If "ignore", will not affect trailing slashes for any urls.
  # default: "ignore"
  trailing_slash = "ignore"

  # If true, will redirect to a url containing a trailing slash on directory-like urls.
  # default: false
  # Example (true): 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!