Layering Debugging Tips

Lono layering is a powerful ability. While some folks love layering, some dislike it. Think this is because layers are so powerful that they can get complex, especially when abused. It’s up to the welder of the sword. This doc tries to help you debug layering, even when abused. 🤣

Seeing Layers Clearly

Probably the best tip is to configure config.layering.show so you can see the layers.

config/app.rb

Lono.configure do |config|
  config.layering.show = true
end

This will show the found layers. Example:

$ lono build demo
Params Layers:
    config/blueprints/demo/params/base.env
    config/blueprints/demo/params/dev.env

All Layering

To see all the possible layers is to set LONO_LAYERS_ALL=1.

export LONO_LAYERS_ALL=1

There are many layers, so we’ll only show the params one.

app/blueprints/demo/config/params.env
app/blueprints/demo/config/params/base.env
app/blueprints/demo/config/params/dev.env
app/blueprints/demo/config/params/us-west-2.env
app/blueprints/demo/config/params/base/us-west-2.env
app/blueprints/demo/config/params/dev/us-west-2.env
app/blueprints/demo/config/params/111111111111.env
app/blueprints/demo/config/params/base/111111111111.env
app/blueprints/demo/config/params/dev/111111111111.env
app/blueprints/demo/config/params/111111111111/us-west-2.env
app/blueprints/demo/config/params/base/111111111111/us-west-2.env
app/blueprints/demo/config/params/dev/111111111111/us-west-2.env
config/blueprints/demo/params.env
config/blueprints/demo/params/base.env
config/blueprints/demo/params/dev.env
config/blueprints/demo/params/us-west-2.env
config/blueprints/demo/params/base/us-west-2.env
config/blueprints/demo/params/dev/us-west-2.env
config/blueprints/demo/params/111111111111.env
config/blueprints/demo/params/base/111111111111.env
config/blueprints/demo/params/dev/111111111111.env
config/blueprints/demo/params/111111111111/us-west-2.env
config/blueprints/demo/params/base/111111111111/us-west-2.env
config/blueprints/demo/params/dev/111111111111/us-west-2.env

As you can see, layering can be pretty powerful but also complex.

Separate Layers

You can have your layer files defined in the blueprint itself or at the project level. Example:

Blueprint Layers: These layers ship with the blueprint. Think of them as defaults that ship with the blueprint itself. IE: app/blueprints/demo/config. These layers are processed first and take lower precedence.
Project Layers: These layers are your project-specific settings. IE: config/blueprints/demo. These layers are processed later and take higher precedence. They override previous layer values.

It is recommended to define layers at the project-level, config/blueprints. This allow blueprints to be even more reusable.

Simple Layering Mode

If you do not need to use multiple regions or accounts layers, you can use simple layering mode.

config/app.rb

Lono.configure do |config|
  config.layering.mode = "simple"
end

It’ll look like this.

app/blueprints/demo/config/params.env
app/blueprints/demo/config/params/base.env
app/blueprints/demo/config/params/dev.env
config/blueprints/demo/params.env
config/blueprints/demo/params/base.env
config/blueprints/demo/params/dev.env

Useful With

Showing layers to debug them is particularly useful when using:

Getting Started