realbook v0.1.0 Realbook View Source

A simple, imperative DSL for remotely provisioning and setting up linux-based servers.

Objectives:

  • convenience
  • idempotency
  • inspectability

Guides

See Guides for information on how to get started.

Connecting to remote servers

Realbook provides be default two connection APIs, one of which (:local) can be used to provision locally. The other (:ssh) can be used to provision a remote host. In order to use the SSH api, generally, you must have passwordless ssh keys installed in the remote server. This default can be overridden in the connect!/2 function by providing options that correspond to SSH.connect/2 options.

Link to this section Summary

Functions

initiates a connection, bound to this process, using the specified module. You may also use a shorthand for the connection.

generates an Elixir module corresponding to a realbook script string or iodata; then evaluates the module, bound to this process.

retrieves a value from the Realbook dictionary by its corresponding key.

loads a script from the suppiled path, compiles it into a Realbook module and executes it.

puts keys into the Realbook dictionary.

Link to this section Functions

Link to this function

connect!(module!, opts \\ [])

View Source

Specs

connect!(atom() | module(), keyword()) :: :ok

initiates a connection, bound to this process, using the specified module. You may also use a shorthand for the connection.

Examples

using explicit naming

Realbook.connect!(Realbook.Adapters.Local)

using shorthand names

Realbook.connect!(:ssh, host: host_ip, user: "admin")
Link to this function

eval(realbook, file \\ "nofile")

View Source

Specs

eval(iodata(), Path.t()) :: :ok

generates an Elixir module corresponding to a realbook script string or iodata; then evaluates the module, bound to this process.

If you provide only the script without a file, then the module will be an anonymous realbook module.

It is generally not recommended to use this function directly, but it may be useful for user debugging purposes or ad-hoc testing via the Elixir REPL.

Only use this function if you know what you are doing.

Link to this function

get(key, default \\ nil)

View Source

Specs

get(atom(), any()) :: term()

retrieves a value from the Realbook dictionary by its corresponding key.

See set/1 for details on how the key/values are stored.

Specs

run(Path.t()) :: :ok | no_return()

loads a script from the suppiled path, compiles it into a Realbook module and executes it.

If the module already exists, then the existing module will be run without recompilation.

Warning:

This does not currently check if the script has changed prior to deciding not to recompile, but that safety check may be revised in the future.

Specs

set(keyword()) :: :ok

puts keys into the Realbook dictionary.

This is a key-value store which stores "variables" for your Realbook scripts. Note that these key/values are stored in the erlang Process dictionary (see Process.put/2) and therefore are tied to the process running the Realbook and will not persist beyond the execution of a single realbook.

Typically, you will run set/1 prior to executing the Realbook script to satisfy all parameters that the it must have at runtime. The Realbook script performs a compile-time check to identify all necessary parameters and will refuse to run unless these parameters have been assigned.

Note that a spawned task will not have access to the Realbook key/value store of its parent. This may change in the future.