spire

Pragmatic Provisioning Using Clojure

A Clojure domain specific language tailored to idempotently orchestrate machines in parallel over SSH.

Overview

This is a work in progress. Consider everything liable to change at any time.

Spire is a single executable binary you can use to provision and configure remote Unix systems. It runs a Clojure domain specific language that is:

Idempotent - Consists of a suite of idempotent operations that are easy to reason about.
Just SSH - Machines don't need anything on them other than to have ssh running and have the standard Unix tools.
Fast - Fast startup. Fast provisioning. For both low bandwidth and high latency connections.
Simple - Separate, uncomplected parts that you can roll together in many different ways.
Pragmatic - Operations performed in order. No graph building or ideological purity. Just do this. Then this. Then this.
Easy Installation - Distributed as a single executable binary.
Multiple Platforms - Can be used to provision any UNIX like system, from FreeBSD on a Rasberry Pi to Ubuntu on EC2 to a MacOS laptop. [WIP]
Clojure Power - Access to all the Clojure tools and data processing.
Open Source - Access to the source code for ultimate peace of mind.

Quickstart

$ curl -O https://raw.githubusercontent.com/epiccastle/spire/master/scripts/install
$ bash install
$ spire -e '(ssh "localhost" (get-fact))'

Installation

For Linux and MacOS:

$ curl -O https://raw.githubusercontent.com/epiccastle/spire/master/scripts/install
$ bash install

Usage

Run a spire script from a file:

$ spire FILE

Evaluate spire expression on the command line:

$ spire -e EXPRESSION

Start a spire nREPL:

$ spire --nrepl-server PORT

Tutorial

Build your own VPS based VPN proxy service with spire and wireguard.

How To

Find examples to solve common problems.

Module Reference

Built in modules.

Discussion

Higher level discussion of the use of spire

Babashka pod usage

Source Code

You can find the source code to Spire on github here.

Build

Install graalvm-ce-java11-20.1.0-dev in your home directory. Add the native image bundle to it. Then:

$ make clean all

Or specify a path to the graal directory to build with a different graal:

$ make clean all GRAALVM=/path/to/my/graal

After a long wait it should write a binary executable spire. Test it.

$ ./spire --help

Install it.

$ mv spire ~/bin/
$ spire --help

Note: graalvm-ce-java8-20.1.0-dev should also work. Earlier versions of graalvm, up to and including 20.0.0 do not work.

Running as a jar

$ make jar
$ java -jar spire-0.1.0-standalone.jar FILE

Running with lein

Use trampoline to run with leiningen so libspire.so can read the correct terminal settings:

$ lein trampoline run -- --help

Running tests

The test suite consists of some unit tests and some module tests that issue a full ssh connection to localhost. These tests will test both the ssh functionality and module functionality just on the running OS. By running this test suite on different architectures, compatability of the modules can be ascertained. The lack of external connections in the test makes setting up test environments easier.

$ lein test

Running as a babashka pod

Load the pod first. Then require the pod.epiccastle.spire namespaces.

(ns my-project.core
  (:require [babashka.pods :as pods]))

(pods/load-pod "spire" {:transport :socket})

(require '[pod.epiccastle.spire.transport :as transport]
         '[pod.epiccastle.spire.module.shell :as shell])

(transport/ssh "user@hostname"
    (prn (shell/shell {:cmd "hostname"})))

Platforms

Native Client

This is the binary spire program you run on your local machine.

Linux 64 bit
MacOS 64 bit
Windows 64 bit

Target Systems

This is the operating systems you will be provisioning, that the spire modules and operations will work against.

Ubuntu Linux
FreeBSD
MacOS

Bugs

There will be many bugs at this early stage. Especially on different target machines. Please open tickets for any issues you find.

Financial Contributors

Babashka Pod Support

The work to make spire available as a babashka pod was genorously funded by:

OpenCollective

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

License

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0.

This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at https://www.gnu.org/software/classpath/license.html.

epiccastle/spire

epiccastle

Reviews

Repository Details