Usage

There are two ways to use potion:

1. You can use potion to run a recipe. A recipe is a script which contains the description of the configuration that you want to apply.
2. You can use potion to create a standalone autoexecutable recipe, so you don’t need potion to run a potion file.

potion run Potionfile Otherrecipe.potion

potion create Potionfile > recipe.sh

potion -q create Potionfile | ssh -tt hostname

potion run https://miremotehost/remoterecipe.potion

potion run ssh+git://myremoterepohost/mirepo.git

export POTION_DEFAULT_SOURCE="ssh+git://myremoterepohost/mirepo.git"
potion run

Using potion to run periodically

Potion does not support daemon mode, but you can use systemd timers or cron jobs to run potion every hour or when you prefer. Please note that potion requires some environment variables like HOME. Is a good practice tu run potion with sudo as unprivileged user, for example:

$ id
uid=1000(user) gid=1000(user) groups=1000(user)
$ sudo -i potion run script.potion

Writing recipes

Potion recipes are, in fact, bash scripts, so any thing that you can create with a bash script could be used in recipe, nevertheless we recommend you to use potion API to more common situations, and create new modules over them. Recipes are evaluated in order, but you parallelize actions using context (read more below).

context @foo
{
  # do some actions
}

context @bar
{
  # do other actions
}

file::present /etc/config.json \
  data="artifact://config.json"

potion run -a ./artifacts_dir Potionfile

artifact::load ./path/to/artifactsdir

Secrets

Secrets are intented to keep some variables of your config in secret. Potion will add secret variables using module secret, documented in the API. The secret file is just another potion file which contains secret::add commands, which define secret values in plain.

There are three different ways to use secrets:

1. Keep you secret file out of the recipes, and copy on each host individually. The run potion with -s (--secret) flag pointing to the secret file.

2. Use symmetric encryption (recommended method). Potion will read a passphrase from /etc/potion.key (or where SECRET_MASTERKEY environment variable defines) and use that passphrase to decrypt the secret file (using AES256 via openssl).

3. Using asymetric encyption via GnuPG, using different keyfiles for each host. This is the most secure way, but hard to maintain.

Recomended option is to set a plain secret.potion file outside your recipes repository and encrypt it with:

openssl enc -e -a -aes256 -in secret.potion -out secret.potion.aes

And keep secret.potion.aes (encrypted file) under version control system (The -a flag in openssl indicates to encode the file using base64, which is used by potion too). This methid provide a reasonable security and a goo way to manage the secrets from central repository.

Of course, you can load secrets programatically, for example:

secret::load "crypt+file://$PWD/secrets.potion.aes"

This example using openssl encrypt (crypt) method to decrupt secrets file. In API documentation, under module secret you can see different load formats, including plain and gpg ones.

Including other potion files

You can split your config in different modules, and you can load them from the starting potion file (init.potion if you are loading recipes from repository). See the include module to learn in which ways you can include other modules, but in general you will use the following:

include::path ./modules/\*.potion

Testing changes

Before to apply changes, you probably want to test the changes, to do that you can run potion with --pretend flag. If you are running and self-executable potion, you can use the environment variable $PRETEND=true to ensure that the potion just pretending instead on real running.

Bonus: How structure your recipes

There is no unique way to structure your recipes, depends of how complex your configuration is, but in general, this is a good approach:

1. Put your artifacts under artifacts/ directory
2. Create modules under modules/ to configure some software (i.e. module nginx). Module should have a ::present, ::exists and ::absent functions.
3. Create modules under profiles/ to help you to group core actions. For example profile webserver will use module nginx and other to configure a webserver.
4. Create modules under roles/ to group profiles. For example frontend role will use webserver and others to configure what a frontend server is.
5. Finally modules under nodes/ and named like FQDN of the node, will include roles that defined those server.

Of course, you can follow any other approach that be convenient for you, this is just a recommendation.