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:
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
homebrewon Mac OS X)
- (git) check-out this repository to
- install Python (version 2) – using your distributions python2 package as well as any potential dependencies
- install the
- create a virtualenv for the project (called
- 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)
project repository used in this example: https://github.com/makkus/freckles (expanded from
metadata used in this example: https://github.com/makkus/freckles/blob/master/.freckle
python-devadapter and (Ansible) role used:
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
https://github.com/freckles-io/wordpress.gitand 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/freckleswhich 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).
context repository used in this example: https://github.com/freckles-io/wordpress (expanded from:
wordpressadapter source: https://github.com/freckles-io/wordpress/tree/master/adapters/wordpress
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¶
- (git) clones that repository to
- 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, symbolically link all configuration files under
$HOME/freckles/dotfiles-test-simpleto their appropriate place somewhere under
dotfiles repository used in this example: https://github.com/makkus/dotfiles-test-simple
metadata used in this example: https://github.com/makkus/dotfiles-test-simple/blob/master/.freckle
dotfilesadapter and (Ansible) role used:
To be done. For now, check out: https://freckles.io/blog/writing-declarative-commandline-scripts
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
- one-line setup of a new working environment (including freckles itself)
- minimal initial requirements: only
- 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 https://freckles.io | bash -s -- freckelize --help
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 - https://freckles.io | bash -s -- frecklecute --help
This bootstraps (‘inaugurates’)
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.