README.md

Status: under active development, targetting a v1 milestone.

🙏Help wanted🙏: There are plenty of issues to work on, of all sizes and difficulty. Getting a dev environment setup takes less than 5 minutes, so you can get your first PR easily!

resonance

A configuration management tool with novel features to Ansible, Chef or Puppet:

• Stateful: Persistent host state enables deletion of old resources, rollback to previous state (on failures) and detection of external changes.
• Transactional changes: things such as APT packages are done "all together or nothing" (single apt call), eliminating isses with conflicting packages.
• Painless refresh: no need to manually tell "please restart the service after changes" as these are implicitly declared so things "just work".
• Painless dependencies: declared order is always respected.
• Speed: read-only checks and possible changes happen concurrently; a lightweight agent is used so things fly even via SSH.

Install

Pick the latest release with:

GOARCH=$(case $(uname -m) in i[23456]86) echo 386;; x86_64) echo amd64;; armv6l|armv7l) echo arm;; aarch64) echo arm64;; *) echo Unknown machine $(uname -m) 1>&2 ; exit 1 ;; esac) && wget -O- https://github.com/fornellas/resonance/releases/latest/download/resonance.$(uname -s | tr A-Z a-z).$GOARCH.gz | gunzip > resonance && chmod 755 resonance
./resonance --help

Development

Getting started is super easy: just run these commands under Linux or MacOS:

git clone git@github.com:fornellas/resonance.git
cd resonance/
./build.sh ci # runs linters, tests and build

That's it! The local build happens inside a Docker, so it is easily reproducible on any machine.

If you're running an old Arm Mac (eg: M1), Docker is very slow, you should consider a no container build (see below).

Shell

You can start a development shell, which gives you access to the whole build environemnt, including all build tools with the correct versions. Eg:

./build.sh shell
make ci
go get -u

No container

You may also run the unofficial¹ build, without a container. This requires Installing GNU Make:

• Ubuntu: apt install make.
• MacOS: brew install make²

Then:

make ci # on MacOS, gmake ci

Or start a bash³ development shell:

make shell

Using gopls, the Go Language Server

Your editor may already support using gopls, and you should follow its documentation on how to set it up. This may require having the correct go (and gopls) versions installed and available for your editor. This can be annoying and error prone.

In this scenario, you should leverage the "no container" option:

make shell
make ci # installs all development tools

And then start you code editor from the development shell (eg: for Sublime, do subl .). This enables the code editor to have access to all the exact versions of tools required.

Faster builds

The default build with ci reproduces the official build, but this may be too slow during development. You can use one of the *-dev targets to do a "dev build": bulid is a lot faster, at the expense of minimal signal loss:

./build.sh ci-dev # or "make ci-dev"

Automatic builds on Linux

The build system is integrated with rrb, which enables the build to run automatically as you edit the files.

First, start rrb:

./build.sh rrb # or "make rrb"

then just edit the files with your preferred editor. As soon as you save any file, the build will be automatically run, interrupting any ongoing build, so you always get a fresh signal.

There's also a rrb-dev target, which yields faster builds during development.

Footnotes

1. unnofficial in the sense that it is not the same as it happens on CI, as unforeseen environment differences may impact the signal. Additionally, a lot of code / tests is Linux only (eg: *_linux.go), so none of this signal will be available on MacOS. ↩

2. note that brew install the command as gmake. Apple's ancient make shipped with MacOS will NOT work. ↩

3. bash must be installed separately, eg, under MacOS, brew install bash. ↩