@installdoc/ansible-gas-station v2.1.0

A no-stone-unturned Ansible playbook you can use to set up the ultimate home lab or on-premise addition to your cloud!

Table of Contents

• Introduction
• Quick Start
  • Vagrant (Recommended)
  • macOS/Linux
  • Windows
• Supported Operating Systems
• Requirements
  • Host Requirements
    • Easier Method of Installing the Host Requirements
  • Operating System
  • Connection
  • MAS on Mac OS X
• Software
  • Binaries
  • NPM Packages
  • Python Packages
  • Ruby Gems
  • Visual Studio Code Extensions
  • Chrome Extensions
  • Homebrew Formulae (macOS and Linux only)
  • Homebrew Casks (macOS only)
  • Go, Rust, and System-Specific Packages
• Web Applications
  • Helm Charts
  • Host Applications
    • HTPC
• Philosophy
• Architecture
• Managing Environments
  • Switching Between Environments
• Contributing
• License

Introduction

Welcome to a new way of doing things. Born out of complete paranoia and a relentless pursuit of the best of GitHub Awesome lists, Gas Station aims to add the capability of being able to completely wipe whole networks and restore them on a regular basis. It takes a unique approach to network provisioning because it supports desktop provisioning as a first-class citizen. By default, without much configuration, it is meant to provision and maintain the state of a network that includes development workstations and servers. One type of user that might benefit from this project is a web developer who wants to start saving the state of their desktop as code. Another type of user is one who wants to start hosting RAM-intensive web applications in their home-lab environment to save huge amounts on cloud costs. This project is also meant to be maintainable by a single person. Granted, if you look through our eco-system you will see we are well-equipped for supporting entire teams as well.

Gas Station a collection of Ansible playbooks, configurations, scripts, and roles meant to provision computers and networks with the "best of GitHub". By leveraging Ansible, you can provision your whole network relatively fast in the event of a disaster or scheduled network reset. This project is also intended to increase the security of your network by allowing you to frequently wipe, reinstall, and re-provision your network, bringing it back to its original state. This is done by backing up container storage volumes (like database files and Docker volumes) to encrypted S3 buckets, storing configurations in encrypted git repositories, and leveraging GitHub-sourced power tools to make the job easy-peasy.

This project started when a certain somebody changed their desktop wallpaper to an cute picture of a cat 🐱 when, all of a sudden, their computer meowed. Well, it actually started before that but no one believes someone who claims that time travelers hacked them on a regular basis. Tip: If you are stuck in spiritual darkness involving time travelers, save yourself some headaches by adopting an other-people first mentality that may include volunteering, tithing, and surrendering to Jesus Christ. Anyway, enough preaching!

Gas Station is:

• Highly configurable - most roles come with optional variables that you can configure to change the behavior of the role
• Highly configured - in-depth research is done to ensure each software component is configured with bash completions, plugins that are well-received by the community, and integrated with other software used in the playbook
• Compatible with all major operating systems (i.e. Windows, Mac OS X, Ubuntu, Fedora, CentOS, Debian, and even Archlinux)
• The product of a team of experts
• An amazing way to learn about developer tools that many would consider to be "the best of GitHub"
• Open to new ideas - feel free to open an issue or contribute with a pull request!

Quick Start

The easiest way to run the entire playbook, outlined in the main.yml file, is to run the appropriate command listed below. These commands will run the playbook on the machine you run the command on. This is probably the best way to get your feet wet before you decide to give us a ⭐ and customize the playbook for your own needs. Ideally, this command should be run on the machine that you plan on running Ansible with to provision the other computers on your network. It is only guaranteed to work on fresh installs so testing it out with Vagrant is highly encouraged.

Vagrant (Recommended)

To test it out with Vagrant, you can run the following commands which will open up an interactive dialog where you can pick which operating system and virtualization provider you wish to test the installation with:

bash .config/scripts/start.sh # Only required if you do not have the dependencies (i.e. Task) already installed
task ansible:test:vagrant

macOS/Linux

curl -sS https://gitlab.com/megabyte-labs/gas-station/-/raw/master/files/quickstart.sh | bash

Windows

In an administrative PowerShell session, run:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://gitlab.com/megabyte-labs/gas-station/-/raw/master/files/quickstart.ps1'))

Supported Operating Systems

The following chart shows the operating systems that have been tested for compatibility using the environments/dev/ environment. This chart is automatically generated using the Ansible Molecule tests you can view in the molecule/default/ folder. We currently have logic in place to automatically handle the testing of Windows, Mac OS X, Ubuntu, Fedora, CentOS, Debian, and Archlinux. If your operating system is not listed but is a variant of one of the systems we test (i.e. a Debian-flavored system or a RedHat-flavored system) then it might still work.

compatibility_matrix

Requirements

• Python >=3.7
• Ansible >=2.9
• Ansible controller should be a macOS/Linux environment (WSL/Docker can be used on Windows)

Host Requirements

There are Python and Ansible package requirements need to be installed by running the following command (or equivalent) in the root of this repository:

if type poetry &> /dev/null; then poetry install --no-root; else pip3 install -r .config/requirements.txt; fi
ansible-galaxy install requirements.yml

Easier Method of Installing the Host Requirements

You can also run bash .config/scripts/start.sh if you do not mind development dependencies being installed as well. This method will even handle installing Python 3 and Ansible.

Operating System

This playbook is built and tested to run on fresh installs of Windows, Mac OS X, Ubuntu, Fedora, Debian, CentOS, and Archlinux. It may still be possible to run the playbook on your current machine. However, installing the playbook on a fresh install is the only thing we actively support. That said, if you come across an issue with an environment that already has configurations and software present, please do not hesitate to open an issue.

Connection

SSH (or WinRM in the case of Windows) and Python should be available on the target systems you would like to provision. If you are attempting to provision a Windows machine, you can ensure that WinRM is enabled and configured so that you can remotely provision the Windows target by running the following command with PowerShell:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://gitlab.com/megabyte-labs/gas-station/-/raw/master/files/client.ps1'))

MAS on Mac OS X

We use mas to install apps from the App Store in some of our roles. Sadly, automatically signing into the App Store is not possible on OS X 10.13+ via mas. This is because mas no longer supports login functionality on OS X 10.13+.

There is another caveat with mas. In order to install an application using mas, the application has to have already been added via the App Store GUI. This means that the first time around you will have to install the apps via the App Store GUI so they are associated with your App Store account.

Software

This project breaks down software into a role (found in the subdirectories of the roles/ folder) if the software requires anything other than being added to the PATH variable. Below is a quick description of what each role does. Browsing through this list, along with the conditions laid out in main.yml, you will be able to get a better picture of what software will be installed by the default main.yml playbook.

role_descriptions

We encourage you to browse through the repositories that are linked to in the table above to learn about the configuration options they support.

Binaries

A lot of nifty software does not require any configuration other than being added to the PATH or being installed with an installer like brew. For this kind of software that requires no configuration, we list the software we would like installed by the playbook as a variable in group_vars/ or host_vars/ as an array of keys assigned to the software variable (example here). With those keys, we install the software using the [professormanhattan.genericinstaller](https://galaxy.ansible.com/professormanhattan/genericinstaller) role which determines how to install the binaries by looking up the keys against the software_package object (example here). For your convienience, the software we recommend and install by default is listed below:

NPM Packages

NPM provides a huge catalog of useful CLIs and libraries so we also include a useful and interesting default set of NPM-hosted CLIs for hosts in the desktop group (defined here, for example):