Skip to content

README.md

Latest commit

 

History

History
149 lines (98 loc) · 7.83 KB

README.md

File metadata and controls

149 lines (98 loc) · 7.83 KB
Raw

env-setup

env-setup is a workstation provisioner for macOS or Linux. It uses Ansible and Homebrew.

Quickstart

  1. Install the tool: bash <(curl -sL jig.io/env-setup)
    • Or use Homebrew: brew install luciditi/tap/env-setup.
  2. Set the configuration: env-setup -c
    • none: Use an empty configuration.
    • mini: Use a minimum configuration.
    • default: Use a workable default configuration.
    • most: Use all features.
    • custom: Create a new config.yml configuration. Edit this configuration with env-setup -e.
  3. Run the tool: env-setup

Usage

Init

The initialize command makes sure that you have git and an SSH key to download this repository. It installs the tool in your home directory under env-setup.

If you do not have an SSH key, add a new SSH key in GitHub.






Config

The configuration YAML file (config.yml) contains a manifest of Ansible variables. These variables set what the system installs in your environment.

env-setup has five starter configuration templates:

  • none: The tool gives no environment setup. It keeps the env-setup tool for later use.
  • mini: The tool gives basic features (scripts, Homebrew, and Ansible).
  • default: The tool gives a workable default environment setup.
  • most: The tool gives all features for a complete environment setup.
  • custom: You specify a custom config.yml configuration. Read this example config.yml.

Change the values in config.yml to match the needs of your environment setup. If you must manually update a custom configuration, run env-setup -e to edit the file.

Run

When you run env-setup for the first time, it makes sure that you have Ansible. Then, it prompts you to select an Ansible playbook.

To specify a playbook, run the command with the playbook name. To run the configuration playbook, run env-setup 01-config. To run all playbooks in sequence, run env-setup all.






Updating

Run env-setup -u to update the installed repository and the installed dotfiles repository.

Playbooks

An Ansible playbook is a series of tasks. The tasks run to build your setup. env-setup has 8 main playbooks and other optional playbooks.

  • 01-config: Configures your dotfiles for your app and CLI configuration. It defaults to env-setup-dotfiles when not overridden.
  • 02-cli: Installs CLI tools with Homebrew formulas.
  • 03-apps: Installs GUI applications with Homebrew casks. It also uses the Linux package manager and the App Store via mas.
  • 04-packages: Installs common programming language dependencies for development tooling. It supports Go, Node, PHP, Ruby, Rust, and Python.
  • 05-repos: Clones Git repositories for active development projects or reference vendors.
  • 06-os: Configures the OS settings.
  • 07-cloud: Configures the host for cloud file sync.
  • 08-prefs: Configures other app settings.

To add other playbooks, read the Custom Playbook section.

Task Info

To see a list of tasks in a playbook, run env-setup -i with the playbook name. For example, run env-setup -i 03-apps.

The tool prints an ordered task list. The list contains a description and tags for each task in the playbook.

Skipping Tasks

Each task has associated tags.

To select tags, use the -t option. To skip tags, use the -s option. To specify multiple tags, separate them with a comma.

For example:

  • To install only Node and Python packages, run env-setup -t node,python 04-packages.
  • To install all packages except PHP packages, run env-setup -s php 04-packages.

Environment Variable Overrides

You can override these environment variables to change behavior.

Init:

  • ENVSETUP_INTERACT: Enables interactive prompts during initialization. The default is 1.
  • ENVSETUP_KEY_FILE: Sets the SSH key path that the tool creates during initialization. The default is $HOME/.ssh/id_rsa.
  • ENVSETUP_KEY_FILE_COMMENT: Sets the SSH key comment that the tool creates during initialization. The default is env-setup:$USER@$(hostname).
  • ENVSETUP_INSTALL_DIR: Sets the path to install env-setup during initialization. The default is $HOME/env-setup.

RunTime:

  • ENVSETUP_INSTALL_DIR: Sets the path where env-setup looks for its config.yml files. The default is $HOME/env-setup.
  • ANSIBLE_SUDO: env-setup runs Ansible with a sudo prompt (-K by default). A value of -n disables the prompt.
  • ANSIBLE_CHECK: env-setup runs Ansible with a dry-run check. A value of -C enables the check.
  • ANSIBLE_STDOUT_CALLBACK: env-setup runs Ansible with a different status update. The options are unixy, dense, debug, yaml, or selective. The default is unixy.
  • ANSIBLE_PLAYBOOK_INFO: env-setup runs Ansible with a display of playbook steps. A value of --list-tasks enables the display.
  • ANSIBLE_SKIPPED_TAGS: env-setup runs Ansible and skips specified tags. The value is a comma-delimited list of tags.
  • ANSIBLE_TAGS: env-setup runs Ansible and runs specific tags. The value is a comma-delimited list of tags.
  • ANSIBLE_VERBOSE: env-setup runs Ansible with verbosity. A value of -vvv enables verbosity.

Testing

env-setup has tools to install an environment for testing.

Docker

The docker directory contains a Dockerfile. The Dockerfile builds an Ubuntu Linux docker image with env-setup and all playbooks.

You can find pre-built images on ghcr.io/luciditi/env-setup.

To test with a quick command, run source <(curl -sL jig.io/dev-aliases) && dev-env. This command installs an alias for docker run ... ghcr.io/luciditi/env-setup.

Terraform

The terraform directory is a Terraform module. The module builds an SSH key and EC2 VMs for Linux (Ubuntu 20) and macOS (Sonoma).

After you build the VMs, use the scripts to test env-setup in the new VMs.

VMs in Tart

The vm directory has scripts to build Linux (Ubuntu) and macOS (Sonoma) VMs in Tart.

To use these scripts, do these steps:

  1. Run eval "$(env-setup -A)" to create env-vm-* aliases.
  2. Run env-vm-create to create a new VM.
  3. Run env-vm-start to start the VM.
  4. Run env-vm-init to initialize the VM with env-setup.
  5. Run env-vm-ssh to open a shell in the VM.
  6. Run env-vm-env-setup to run env-setup in the VM.
  7. Run env-vm-stop to stop the VM.

Custom Playbook

To create a custom playbook, run ./scripts/add-playbook 09-my-playbook.

This command builds the directory structure in the ansible directory. The new playbook is selectable in the env-setup tool.

To add your playbook tasks, edit ansible/*/09-my-playbook/main.yml. To add ansible-galaxy dependencies, edit ansible/*/09-my-playbook/requirements.yml.

Development

Read the development README.