Currently, I'd consider freckles early beta-grade software/proof-of-concept. Most of its features work, the API itself won't change much anymore, except for some small bits and pieces.

The format of the frecklets (the little scriptlets that freckles uses) is fixed, except that the schema might be extended, which would not break compatibility. The naming of a few default frecklets might change still, and the overall nomenclature of how to best name frecklets to describe their purpose might also change dependent on input from users.

The code itself has a few pockets of complexity that I'd like to disentangle at some stage, but this will only happen after sufficient documentation and tests exist.

Current issues

Here's what is currently missing, or not working:

Unit/integration tests

Over the last 2 years, I re-wrote freckles at least 4 times. This is really the only way for me to create software I'll end up being happy with (and that does not have very very clear requirements). I would not have done that if I had worked for anybody else, but because I did it in my own time, living off my own money, I had the luxury to do it that way.

That means though, it would have been a waste for me to write tests for code that will never really be used in anger. Now, in a perfect world I'd probably re-write freckles again, twice. Well, in a perfect world I'd be a good enough developer so I'd manage to produce something decent on my first go. But you know what I mean... Anyway. Tests are in the works now.

Code docs
Although I'm happy with how the user-facing documentation is coming along (still big holes there too, though), the code itself lacks good enough documentation to be useful for other people. Same problem as with unit/integration tests: so far the code I used did not live long enough to warrant documentation.
Multi-platform/distribution support:

Up until now, I only used Debian Stretch (and up to a point Ubuntu LTS) to develop and test freckles itself, and the frecklets from the default and community repository.

The Mac OS X version of freckles is working fine as a controller machine, and installation of important packages like 'osx-commandline-tools' and 'homebrew' is working too. Binaries are code-signed with an Apple developer certificate. But since I don't own a Mac myself there are probably issues I would have discovered had I developed on Mac OS X itself. Please do report those bugs if you are a Mac user.

The same applies to guest systems that are used as targets of freckles runs: I mainly used Debian Stretch as the host platform, because it would have been just too time-consuming to do testing on several platforms. A lot of the Ansible roles that are used support other platforms, so the frecklets that call them should work fine. But currently there is no way for an end-user to figure that out easily. This will be implemented before a version 1.0 release. And I hope there will be a community around freckles that will help in developing and testing other platforms in the long run. That is not up to me though.

Run results

Currently, freckles is mainly a tool to get an environment into a certain, fixed state. That means you don't really need to know any details from your run itself: either it worked, which means the state you specified exists now, and you can get everything you need from your input. Or it did not work, in which case you get the exit code, and an error message.

Now, in some cases it's not that clear-cut. For example, imagine you want to create a virtual server on DigitalOcean, or Hetzner, or Amazon. Then you want to use that to host a website. It's impossible (with a few exceptions) to know which public IP address your server will end up with. Which makes it impossible to set your DNS records, get your Letsencrypt certificate. And actually connect to your virtual server that you just created to deploy your web server in the first place.

So, for those cases, freckles needs to be able to deal with output from tasks, to be fed into the subsequent ones. There is already redimentary support for this, and it works to a degree. It's not documented yet, and not well enough tested for me to feel comfortable with it. Since this will be a really central feature for some of the more interesting use-cases for freckles, I want to get it right.

Error messages
Even though by now most do, not all errors in a freckles run display an error message. Sometimes there are still stack-traces instead of nice to look at error output including a solution if possible.
Other backends/adapters
At the moment, only Ansible is supported as a backend for freckles. It's probably hard to see at the moment how that will work, but some of the main value of freckles, should it ever be adopted, will come from other adapters to 3rd party technologies. I'll do a write-up about all this at some stage, and explain in more details.
Code contributions
Up until now, I am the only contributor to freckles. I intend to open up the possibility for other people to send pull-requests, and do bug-fixes. I just did not have the time to come up with how exactly to do that, and which license to ues for those outside contributions. This will also be done, hopefully in the near future.
Factoring out some sub-systems
I intend to factor out some of the freckles sub-systems into their own projects (esp. the configuration one, which I think could be use-full for others), and release them with a less restrictive license. No guarantee when that will happen, low on my list of priorities.
I want to provide lots and lots of examples on how to use freckles, in which ways it can be used, and what can be done with it. Not there yet at all, I'll work on this bit by bit, whenever I come across something noteworthy (and don't forget to record it).

The current website at, and esp. the docs are not 100% ready for mobile usage. Some of the navigation disappears when viewed on a phone.

Also, the frecklet indexes (and probably other parts too) need a search function. Not my top-priority, but I do consider it important.


Before a version 1.0.0 release, those things will be done:

  • decent test coverage, and documentation
  • make sure all errors are displayed, have easy to understand error messages, and if possible solutions
  • a working, but probably not really full-featured freckles shell adapter backend

Out of scope for version 1, but planned for later releases:

  • a testing framework for frecklets
  • first-rate support to build container images (Docker, lxc)
  • frecklet visioning
  • speed improvements (there are a few easy wins there, I think)
  • support for other backends (Terraform, Kubernetes, ...)
  • a Python library to easily allow the creation and execution of frecklets from within a script/application
  • markers and strategies for 100% non-sudo frecklets
  • other language bindings
  • a (self-hosted) REST (or other, not sure yet) API to allow the execution of frecklets from other languages and services, maybe a managed hosted version of this as well
  • a dynamically generated graphical (maybe also web-) user-interface
  • (maybe) a frecklet 'compiler', to create self-contained executables that don't need any dependencies at all to get a machine into a pre-defined state