Settings and Configuration in Stallion

All default configuration is in the file conf/stallion.toml. The format for this file is “toml” – Tom’s Obvious, Minimal Language. You can read the basics on how to use this format here.

You can then override this file per-environment. Create a file conf/stallion.<env name>.toml to create overrides per-environment. For instance, keep your default settings in conf/stallion.toml, then put your production database settings and site URL settings in conf/stallion.prod.toml. To have special settings for your local development computer, use conf/stallion.local.toml. Note that if you override any variable from a sub-section of the settings, you must re-enter values for all the variables.

You can also override this file per-user. So if you want to have settings just for your personal machine, that will be different than your coworker’s machines, you can create a file conf/stallion.local.user-myname.toml where “myname” is the user name you are currently logged in as with your shell.

When you create a new site, a bunch of default settings will be created, and others will be commented out, with instructions on how to customize them. Additional information on settings are found in the relevant portion of each documentation. You can see a full list of settings by examining the javadocs: https://docs.stallion.io/javadocs/index.html?io/stallion/settings/Settings.html

Plugin settings

Each plugin gets its own settings file – conf/pluginName.toml. For instance, the Flat-file blog plugin has a settings file called conf/flatBlog.toml. These plugin settings also support overrides. So you can put prod settings at conf/pluginName.prod.toml.

Storing Passwords and Secrets

The stallion.toml file contains settings you might want to keep private, such as email passwords, database passwords, API keys, etc. You can do this by having an encrypted secrets file.

1. Run the command bin/stallion secrets
2. You will be prompted to enter a passphrase. Make it long and hard to guess. Be sure to put this in your password manager, as there will be no way to recover it if you lose it.
3. Use the interactive command-line tool to add key-value pairs for any secrets you wish.
4. You can re-run the command at any time to add or edit secrets.

The secrets file will live in your conf folder as “secrets.json.aes”.

Once you have generated your secrets, anywhere in your stallion.toml file where a string entry is called for, you can instead use the special token “secret:::your_key_name” where “your_key_name” is an entry in your secrets file, as entered above.

# Instead of putting your password in plain text...
[database]
password = "password1"
# ...you can use a secret:
[database]
password = "secret:::mysql_prod_password"

When you deploy, the secrets file will be decrypted and uploaded to your server. When you run locally, you will be prompted for the passphrase is a secret is needed. If you are using a Mac, you can optionally store the passphrase in your keychain so that you do not have to enter it every single time.

Limitations and gotchas

• There is no fine-grained access. A single encrypted secrets file should really only be used on a small team.
• If someone leaves your team, or the passphrase is compromised for any reason, you will need to generate all new secrets along with a passphrase and new file. Your ex-teammate might still have the old encrypted file, the old encrypted file may still live in the git history, etc. You have to assume that all secrets are compromised, so you need to generate new secrets.

If your needs are more sophisticated, you can get in touch, and we can figure out how to support you.