Running freckles

There are several ways any of the available frecklets (or your own) can be executed. The most common way, at least initially, will be via one of the command-line interfaces: freckles or frecklecute .

Over time, new interface types and client libraries will be added, and examples on how to use them will be posted here.

Command-line

Local execution, no freckles install

The most simple option: all we need is either curl or wget on our machine:

curl https://freckles.sh | bash -s -- frecklecute user-exists --group wheel admin
# or
wget -O- https://freckles.sh | bash -s -- frecklecute user-exists --group wheel admin

This will download freckles (and frecklecute) into $HOME/.local/share/freckles/bin, then run the user-exists frecklet locally: it will first create the group 'wheel' (if not already present), then the user 'admin' (again, if not present yet), and put that user into the group.

Except for the folders $HOME/.local/share/freckles and $HOME/.cache/freckles, your filesystem will not be touched. Well, except for whatever the frecklet you run does, of course. If you want to delete all traces of freckles after it did it's thing, you can run the above command like:

curl https://freckles.sh | \
   CLEANUP=true bash -s -- frecklecute user-exists --group wheel admin

This is quite convenient when using freckles within a Dockerfile (or cloud-init, ...), for example. No binary or config files to 'ADD', just one string to paste:

FROM ubuntu:18.04
# necessary if no locale is set
ENV LC_CTYPE C.UTF-8
RUN apt update && apt install -y curl

RUN curl https://freckles.sh | bash -s -- CLEANUP=true \
      frecklecute java-lang-installed
...
...

Side-note: currently, Docker images built with freckles are still often larger than they could be, this will be addressed in the future.

If you end up using this way of running freckles a lot, I'd recommend hosting the bootstrap script yourself.

frecklets used:

Local execution, freckles installed

We can do the same thing with freckles already installed, and present in the users $PATH. In this case, we do:

frecklecute user-exists --group wheel admin

As you can see, this is the exact same command, with the curly bash part removed.

frecklets used:

user-exists

Local controller, remote target

We can do the same thing on a remote host. For that, we need to have (ideally password-less) sudo or root access on that host, otherwise we would lack the permission to create a new user.

Here's how we run frecklecute in this scenario:

frecklecute --target [email protected] user-exists --group wheel admin
# or, if not installed:
curl https://freckles.sh | bash -s -- frecklecute --target [email protected] \
       user-exists --group wheel admin

As you can see, the invocation is mostly the same, except for the additional --target command-line argument. The target format follows the usual ssh convention: <user>@<hostname_or_ip>.

frecklets used:

user-exists

Python

Pycklets

The default and community frecklets are used to auto-generate Python wrapper classes (using this template) which are collected in the pycklets Python library. If you add this library to your project dependencies, you can run all of those from within your code.

Create EC2 instance, install Wordpress on it

This example assumes you have an AWS account, an IAM user that can create ec2 instances, and a security group called 'web-traffic' that allows incoming http traffic.

from pycklets import Ec2InstanceExists, WordpressStandalone
from pyckles import create_pyckles_context

ec2 = Ec2InstanceExists()
ec2.instance_name = "wordpress_server"
ec2.aws_access_key = "<your aws access key>"
ec2.aws_secret_key = "<your aws secret key>"
ec2.key_name = "yubi"               # ssh-key-pair name
ec2.region = "eu-west-1"
ec2.register_var = "wp_box"
ec2.image_id = "ami-440d4837"          # Debian stretch
ec2.security_groups = ["web-traffic"]  # already exists

# create the instance
run_context = create_pyckles_context(pyckles_packages="pycklets", debug=True)
ec2_details = run_context.run_pycklets(ec2)

ec2_ip = ec2_details["wp_box"]["public_ip_address"]

wps = WordpressStandalone()
wps.wp_title = "My wordpress site"
wps.webserver = "nginx"
wps.hostname = ec2_ip
wps.wp_admin_email = "[email protected]"
wps.wp_admin_password = "password123"
wps.wp_db_password = "wordpress_db_pw"

# install Wordpress
# this Debian image has a default user called 'admin'
run_context.run_pycklets(wps, run_config="admin@{}".format(ec2_ip))

print("Finished. Visit: http://{}".format(ec2_ip))

Note: This uses the default debug context to execute our frecklets. For more control you would usually create such a context manually.