Repository files navigation

THIS IS BETA SOFTWARE UNDER ACTIVE DEVELOPMENT. APIs AND FEATURES WILL CHANGE.

consist - (noun): a set of railroad vehicles forming a complete train.

consist is the one person framework server scaffolder. It is stone age tech.

You can use it to quickly baseline a raw server using a given recipe providedby Consist. I use it to baseline new Droplets to be ready to run Kamal insingle server setup for a Rails monolith. While Kamal will setup Dockerfor you, it does not do anything else related to configuring the underlyingserver, such as firewalls, general hardening, enabling swapfile etc.

• Minimal tool specific language / knowledge required to use Consist
• Procedural declaration execution - no converging, orchestration orevent driven operation
• If you can shell script it, you canconsist it directly
• Encouraging sharing of portableConsistfiles across the community

• Quick start
• Support
• Rationale
• Key Concepts
  • Recipes
  • Steps
  • Files
  • Consistfile
  • Artifacts
  • .consist directory
• Community Consistfiles
• Is It Good?
• License
• Code of conduct
• Contribution guide

Make sure theconsist gem is installed:

gem install consist

You must be already authenticated with the server you want to scaffold.consist will use your account's SSH id to perform actions.

The main way of usingconsist is to go with aConsistfile inyour project root that describes the recipe and steps. Then you can say:

consist up<ip_address> [--consistfile=/path/to/consistfile] [--consistdir=/path/to/.consistdir]

Andconsist will do it's thing with that given IP address.

To create a blankConsistfile in your project, execute:

consistinit

Other commands available:

• consist init [account/repo] - initialize your project with a new Consist file. Optionally,you can specify a Githubaccount/repo path and that location will be used to clone down aConsistfile, and any associated artifacts needed by the Consistfile.
• consist ping <ip_address> - checks you can connect and authenticate with the given IP

• Simple Ruby based DSL
• ERB interpolation of config on shell commands and file contents
• Small API surface area - quick to learn

I wanted a super-simple tool, that was baked in Ruby, for setting uprandom servers to specific configurations. This is the result.

On a scale of 1 to 10, with 10 being Terraform, this tool is basicallyas low-rent you can get to hand running scripts yourself, so about a 3on the scale.

If you know how to shell script what you want, you can stick it in a step,and add it to a recipe.

The more I work in this industry, the less I see using other people's codeand tools as a benefit, and more of a liability. I appreciate the paradox I'mcreating here for you 😅

I think they are bad tools for my needs. I wanted something simpleI could hack on, grow only when needed, and will work specificallywithout ambiguity. For example, Ansible has a lot of nonsense with case sensitivity,Terraform doesweird unexpected things.

I didn't want to keep maintaining specific knowledge of these infrastructureas code tools in my brain anymore, along with all of their peculiarities and oddities.

If you prefer those tools, go ahead and use them.

Ain't nobody stopping you.

Consist leans on three primary ideas: recipes, steps and files. Recipes containone or more steps. Steps tend to be atomic and idempotent.

Example of a recipe:

name"Kamal Single Server"description"Sets up a single server to run Kamal"user:rootstepsdostep:update_apt_packagesstep:install_apt_packagesend

Example of a step:

name"Install APT packages"required_user:rootshell"Installing essential packages"do<<~EOS    apt-get -y remove systemd-timesyncd    timedatectl set-ntp no    apt-get -y install build-essential curl fail2ban git ntp vim    apt-get autoremove    apt-get autoclean  EOSendshell"Start NTP and Fail2Ban"do<<~EOS    service ntp restart    service fail2ban restart  EOSend

Example of a file:

file:hostnamedo<<~EOS  <%= hostname %>  EOSend

AConsistfile is a portable giant file of a recipe and all itssteps. Something like (this is afull example, in practice youwould reference some of Consists' built in steps):

# This is a shortened non-complete example.consistdoconfig:hostname,"testexample.com"config:site_fqdn,"textexample.com"config:admin_email,"j@jmd.fm"config:swap_size,"2G"config:swap_swappiness,"60"config:timezone,"UTC"file:apt_auto_upgradedo<<~EOS      APT::Periodic::AutocleanInterval "7";      APT::Periodic::Update-Package-Lists "1";      APT::Periodic::Unattended-Upgrade "1";    EOSendfile:hostnamedo<<~EOS      <%= hostname %>    EOSendfile:timezonedo<<~EOS      <%= timezone %>    EOSendrecipe:kamal_single_serverdoname"Kamal Single Server Scaffold"stepsdostep:set_hostnamedoupload_filemessage:"Setting hostname",local_file::hostname,remote_path:"/etc/hostname"shelldo<<~EOS            hostname <%= Consist.config[:hostname] %>          EOSendmutate_filemode::replace,target_file:"/etc/hosts",match:"^127.0.0.1 localhost$",target_string:"127.0.0.1 localhost <%= hostname %>"endstep:setup_timezonedoshelldo<<~EOS            rm /etc/localtime          EOSendupload_filemessage:"Setting Timezone",local_file::timezone,remote_path:"/etc/timezone"shelldo<<~EOS            chmod 0644 /etc/timezone            ln -s /usr/share/zoneinfo/<%= timezone %> /etc/localtime            chmod 0644 /etc/localtime            DEBIAN_FRONTEND=noninteractive dpkg-reconfigure -f noninteractive tzdata          EOSendendendendend# vim: filetype=ruby

Given aConsistfile you could then sayconsist up <ip_address> andit would just work.

Artifacts allow you to split out yourConsistfile into separate files.

You can create blocks in theConsistfile as shown above, but you can also onlyspecify anid, and thatid will be used to try and attempt to load a file of thatname in the.consist/<type>/<id> directory. For example, referencing a file:

file:apt_auto_upgrade

Will attempt to load a file in.consist/files/apt_auto_upgrade. The same ispossible for any of the main types:files,steps, andrecipes

The.consist directory is assumed to be in the root of your project, and shouldcontain three subdirectories for each of the types:files,steps,recipes.

You can specify an alternate directory location by passing the--consistdir switchto theup command.

If you create a Github repo, and all it contains is aConsistfile and any associatedartifacts under a.consist directory, other people will be able to use it byexecutingconsist init <gh_repo_path> in their project root.

If you create one, please open a PR to include it here:

I think so. But I don't know, use your own brain or something. Don't listen tome.

If you want to report a bug, or have ideas, feedback or questions about the gem,let me know via GitHub issuesand I will do my best to provide a helpful answer.

The gem is available as open source under the terms of theLGPLv3 License.

Everyone interacting in this project’s codebases, issue trackers, chatrooms and mailing lists is expected to follow thecode of conduct.

Pull requests are welcome, but I want you to open an Issue first to discuss yourideas. Thanks.

1. Clone the repo
2. Runbundle install
3. Runbin/dev to execute consist locally without having to build and install.

Make sure any PRs have been formatted withstandard.