Documentation Status Updates Join the chat at


freckles is a collection of tools designed to manage your local working environment (workstation, remote server, virtual machine, container, …). It helps you (and your team) to apply best practices – similar to those used in the configuration management and DevOps space, but with a slight twist – to your development (and other) projects. And, hopefully, it saves you time while doing it.

Currently, freckles consists of two main applications:

A tool to facilitate data-centric environment management, which means: it’ll look at a (project) folder, process it’s structure and metadata, then setup a hospitable environment for that project on the host system according to a set of pre-written recipes (which ideally follow best practices for the type of project in question). Imagine Maven, Gradle, Rake, etc., but much more generic. Using any of those build systems internally if necessary.
An interpreter for declarative, idempotent command-line scripts, using any of the existing Ansible modules and roles on Ansible galaxy as building-blocks.

freckles is written in Python, and uses Ansible to do the heavy (system- and state-management) lifting.



freckelize is data-centric (or ‘project-centric’, if you will) configuration management. It supports the quick and easy creation of plug-ins for all sorts of project-types and -data. It comes with a a number of default ones, as well as examples to illustrate it’s workings and capabilities. Here are a few of those:

Python project

The following command can setup a development environment around any Python project. This here sets up one for the freckles project itself. freckles is written in Python and uses a fairly standard project structure.

$ freckelize python-dev -f gh:makkus/freckles
What it does
  • install all necessary package manager if necessary (for example homebrew on Mac OS X)
  • expand gh:makkus/freckles to
  • (git) check-out this repository to $HOME/freckles/freckles
  • install Python (version 2) – using your distributions python2 package as well as any potential dependencies
  • install the virtualenv and pip packages
  • create a virtualenv for the project (called freckles-dev
  • install all project dependencies (from requirements_dev.txt) into the new virtualenv
  • set-up the python project into the virtualenv (using pip install -e <project_folder>)
  • to activate the virtualenv, one only has to issue source $HOME/.virtualenvs/freckles-dev/bin/activate (or use virtualenv-wrapper)
Further information


Here we setup a new Wordpress instance, using a so called blueprint, which is basically a prepared, generic (and in most cases empty) project template with some defaults set, that can optionally ask for user input for some of those defaults and change the project template accordingly.

$ freckelize -r frkl:wordpress -f blueprint:wordpress -t /var/lib/freckles
What it does
  • expand the context repo url frkl:wordpress to and looks for a blueprint called wordpress (wordpress blueprint source)
  • ask the user a few basic questions about the install (according to the configuration of the blueprint)
  • install and configure a MySQL (or MariaDB) server and the PHP and PHP packages necessary for Wordpress
  • download and put into place the Wordpress application
  • install and configure the Nginx web-server for the downloaded Wordpress application
  • if so specified by the user earlier, it’ll also request a “Let’s encrypt” https certificate for the domain running this Wordpress instance, as well as a cronjob to renew that certificate before it expires
  • you’ll end up with a folder under /var/lib/freckles which contains everything relevant to your Wordpress install (both database and Wordpress-site files), which can be easily backed-up, and which can be used to quickly restore your instance on a different, newly installed machine (again, using freckles).


If you use a curated repository of dotfiles to manage your application configurations, the following command can setup your usual development environment on a newly provisioned machine (physical or virtual), without any manual interaction. It uses the structure of the dotfiles repository as well as potentially added metadata to determine which applications to install, and how to configure them (if applicable).

$ freckelize -f gh:makkus/dotfiles-test-simple
What it does
  • expands gh:makkus/dotfiles-test-simple to
  • (git) clones that repository to $HOME/freckles/dotfiles-test-simple
  • parse the downloaded repo and make a list of all applications that need to be installed, as well as the package manager(s) to install them
  • install all necessary package managers
  • install all necessary packages (and their dependencies)
  • install the stow package
  • using stow, symbolically link all configuration files under $HOME/freckles/dotfiles-test-simple to their appropriate place somewhere under $HOME (or $HOME/.config)


To be done. For now, check out:

Project goals

Ok, to be perfectly honest, this is not one of those projects where I had a set of things I wanted to achive, and then go about achieving those things in a structured way. Nope. This is one of those projects where I had the very strong feeling it should exist, in some form or other, but I had no idea how it would end up looking, and what exactly it’d be able to do. One of those where I let the ongoing development lead the way. Don’t go about telling any of my future employers I do that sort of thing though. It doesn’t seem to be considered professional, or something. I’d disagree, but can’t really be bothered.

So, if you really need a list, here’s one. Let’s all pretend that was what I wanted all along, ok? And I hit the nail on the head! The list:

  • encouraging users to record and version control important project metadata (e.g.: type of project, all project requirements: system- as well as framework/language specific)
  • quick (re-)provisioning of project development environments (on both physical as well as virtual machines)
  • replicated, identical development environments for all members of a development team (even if they use different platforms for development) – including the installation and configuration of system-level dependencies
  • provide best-practice blueprints for a wide range of project profiles, in order quickly get started with a well thought-out project structure, developed and agreed upon by the community as best practice
  • allowing the re-use of all existing Ansible modules and roles

Project features

  • one-line setup of a new working environment (including freckles itself)
  • minimal initial requirements: only curl or wget
  • supports Linux & MacOS X (and maybe the Ubuntu subsystem on Windows 10, not tested yet)
  • can use the same configuration for your Linux and MacOS workstation as well as Vagrant machines, containers, etc.
  • support for systems where you don’t have root/sudo access via the conda package manager (or nix, with some limitations)
  • extensible via adapters
  • declarative, idempotent scripting


The examples above assume you have freckles already installed. If that’s not the case, freckles can be bootstrapped using the ‘inaugurate’ bootstrap script (yes, yes, I know, downloading and executing scripts from random websites is often considered a bad idea – so before you actually do, you might want to read this, this, this, and this ). To install freckles and run freckelize straight away to display it’s help, issue:

curl | bash -s -- freckelize --help

or, using wget instead of curl, and executing frecklecute instead of freckles (you can mix and match, of course, and also use the freckles command if that is what you need):

wget -O - | bash -s -- frecklecute --help

This bootstraps (‘inaugurates’) freckelize, frecklecute or freckles and displays its help message (instead of actually doing something useful). All files are installed under $HOME/.local/share/inaugurate/, which can be deleted without affecting anything else.

This command also adds a line to your $HOME/.profile file in order to add freckles to your path (once you re-login, or do a source $HOME/.profile). Set an environment var NO_ADD_PATH=true if you want to prevent that behaviour.

More detailed information on this and other ways to install freckles can be found here.


  • Free software: GNU General Public License v3


For freckles (and the libraries that developed because of it, nsbl and frkl) I am relying on quite a few free libraries, frameworks, ansible-roles and more. Here’s a list for the main dependency libraries, and the first couple of Ansible roles that were used. There are a lot more now, so please forgive me if yours is not included below:

obviously the most important dependency, not much more to say apart from that without it freckles would not exist.
also a very important piece for freckles to use, most of the templating that is not done directly with jinja2 is done using cookiecutter. Also, *freckles (as well as nsbl and frkl) use the audreyr/cookiecutter-pypackage template.
a main dependency of ansible and cookiecutter, but also used on its own by freckles
the library that powers the commandline interfaces of freckles, nsbl, and frkl
a super-cool package manager I use for most of my non-system packages. Also check out NixOS while you’re at it. Ideally freckles wouldn’t be necessary (or at least would look quite different) because everybody would be using Nix!
similarly cool package manager, and the reason freckles can be bootstrapped and run without sudo permissions. This is a bigger deal than you probably realize.
I’m not using MacOS X myself, but I’m told homebrew is cool, which is why I support it. And, of course because MacOS X doesn’t have a native system package manager.
the role that installs homebrew on MacOS X, one of the few external ansible roles that freckles ships with
the role that installs the XCode commandline tools on Mac OS X. Also ships with freckles, and is a dependency of geerlingguy.ansible-role-homebrew
ansible module written by Adam Frey, which I did some more work on. Probably wouldn’t have thought to support nix if I hadn’t found it.
ansible module written by Spencer Gibb for battleschool, can install all sort of packages on a Mac. Can’t tell you how glad I was not to have to write that.