Rusthead

A tool for generating docker compose files for the Samply.Bridgehead based on a simple toml config.

Installation

The rustehead can either be installed by following the installation wizard run with:

bash <(docker run --rm samply/rusthead bootstrap)

Or by manually creating a minimal config file like this:

site_id = "test"
# The hostname under which the bridgehead will be accessible. Can also be an IP address.
hostname = "test-bridgehead.local"

and running:

docker run --rm -v $(pwd):$(pwd) samply/rusthead bootstrap bridgehead --config $(pwd)
# Followed by
sudo ./bridgehead install

After that you have an empty rusthead installation that does not start any services yet. Before adding any services, let's go over the generated files. If you want to skip learning about the generated files, you can skip to Adding Services.

-rwxr-xr-x 1 bridgehead docker 4106 May 11 07:35 bridgehead
-rw-rw-r-- 1 bridgehead docker   18 May 11 07:35 config.local.toml
-rw-rwSr-- 1 bridgehead docker   35 May 11 07:16 config.toml
-rw-rw-r-- 1 bridgehead docker   87 May 11 07:35 .env
drwxrwsr-x 8 bridgehead docker 4096 May 11 07:41 .git
-rw-rw-r-- 1 bridgehead docker   87 May 11 07:35 .gitignore
drwxrwsr-x 2 bridgehead docker 4096 May 11 07:35 services

Why is there a git repository?

All changes to compose files and config.toml are committed to the git repository. This allows you to easily track and revert changes. And makes reviewing changes of updates easier (just inspect them with git diff). You can also enable the git_sync feature in the config to automatically push and pull changes from a git remote repository.

Private files

The .env and config.local.toml files are private and not committed to the git repository. The .env is auto generated based on the config.local.toml file that means edits to the .env file will be overwritten on updates. The config.local.toml contains the credentials for the local basic auth users, oidc configuration and a seed to generate other api keys. The file is mostly autogenerated by the bridgehead update command but will try to preserve sensible modifications you have made. For example it is recommended to remove the plaintext password found under basic_auth_users.<username>.pw and save it to a password manager.

The bridgehead script

bridgehead compose

The bridgehead script is the main entrypoint that you will use to manage your installation. It's most interesting command is bridgehead compose which is just a wrapper around docker compose so it can be used with all the standard docker compose subcommands (e.g. up, down, logs -f).

bridgehead update

This command will update the generated compose files to the latest versions. It will also make a commit to the git repository so you can easily revert to the previous version if needed.

Adding Services

To add services you need to edit the config.toml file with the desired service configuration. For more information on the available options, see the example config. After making changes to the config.toml you need to commit them to the git repository and run the update command.

git commit -am "Added service xyz"
./bridgehead update

Note

When adding services that require a new beam network you need to also run sudo ./bridgehead enroll and follow the provided instructions.

To see what changes were made by the update command by running git diff HEAD~1. After that you can restart the bridgehead by either restarting the systemd unit (sudo systemctl restart bridgehead) or by running ./bridgehead compose down followed by ./bridgehead compose up.