Rinse, Wash, Repeat (RWR)

⚠️

Rinse, Wash, Repeat (RWR) is currently in alpha stage. While the core functionality is in place, not all features have been thoroughly tested and validated across all platforms. Please refer to the Road to 1.0 checklist in this README to check the status of confirmed functionality. Use at your own risk, and expect potential bugs or incomplete features.

Introduction

Rinse, Wash, Repeat (RWR) is a powerful and flexible configuration management tool designed for those who like to hop around and reinstall frequently, regardless of whether it’s Linux, macOS, or Windows. It aims to simplify the process of setting up and maintaining your system, making it easy to rebuild and reproduce configurations across multiple machines.

Features

• Blueprint-based Configuration: RWR uses configuration files called blueprints (similar to Chef cookbooks or Ansible playbooks) to define and manage your system’s configuration.

• Multi-format Support: Blueprints can be written in YAML, JSON, or TOML format, providing flexibility and compatibility with your preferred configuration format.

• Package Management: RWR integrates with various package managers, allowing you to easily install, remove, and manage packages across different Linux distributions, macOS, and Windows. Now supports specifying additional arguments for package installation.

• File and Directory Management: RWR provides functionality to manage files and directories, including copying, moving, deleting, creating, and modifying permissions and ownership. Supports URL sources for files and intelligent renaming.

• Service Management: RWR allows you to manage system services, including starting, stopping, enabling, and disabling services across different operating systems.

• Repository Management: RWR supports managing repositories for different package managers, such as apt, brew, dnf, zypper, and more.

• User and Group Management: RWR allows you to create and manage user accounts and groups on your system.

• Template Rendering: RWR supports rendering templates with variable substitution, making your configurations more dynamic and reusable.

• Git Repository Management: RWR can clone and manage Git repositories as part of the configuration process.

• Script Execution: RWR allows you to execute scripts as part of the configuration process, providing additional flexibility and customization options.

• Bootstrap Process: RWR includes a bootstrap process that can be used to set up the initial system configuration, including installing essential packages, creating directories, and setting permissions.

• Variable Substitution: Use variables in your blueprints to make your configurations more dynamic and reusable.

• Extensible Architecture: RWR is built with extensibility in mind, allowing you to easily add support for new package managers, file synchronization backends, and more.

• SSH Key Management: RWR can generate and manage SSH keys, including copying public keys to GitHub and setting a key as the default RWR SSH key for operations.

Quick Install

For a quick installation of RWR, you can use the following one-liners:

Unix-based Systems (Linux and macOS)

curl -sSL https://raw.githubusercontent.com/FynxLabs/rwr/main/install.sh | sudo bash

Windows

Open PowerShell as an administrator and 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://raw.githubusercontent.com/FynxLabs/rwr/main/install.ps1'))

These scripts will download and install the latest version of RWR appropriate for your system. They will also set up the necessary paths and permissions.

Note	Always review scripts before running them with elevated privileges. The install scripts are available for inspection in the RWR repository.

Installation

Packages

RWR packages are available for various platforms and architectures through goreleaser. You can find the pre-built packages on the releases page of the RWR repository.

The following package types are available:

• Binary archives (.tar.gz, .zip)

• Debian packages (.deb)

• RPM packages (.rpm)

• Homebrew taps

• Scoop buckets

From Releases

To install RWR, follow these steps:

1. Download the latest release of RWR from the releases page.

2. Extract the downloaded archive to a directory of your choice.

3. Add the directory to your system’s PATH environment variable.

Getting Started

To get started with RWR, follow these steps:

1. Initialize the RWR configuration by running rwr config init. This will prompt you to enter your preferences and create a default configuration file.

2. Set up your blueprints' repository:

   • If you’re using a Git repository, provide the repository URL during the configuration initialization.

   • If you’re using local blueprints, place your blueprint files in the specified local path.

3. Run rwr init to initialize your system based on the blueprints.

Commands

RWR provides the following commands:

• rwr config: Manage RWR configuration settings.

  • rwr config --create: Initialize the RWR configuration.

• rwr all: Initialize the system by running all blueprints.

• rwr validate: Validate the RWR blueprints.

• rwr run: Run individual processors.

  • rwr run package: Run the package processor.

  • rwr run repository: Run the repository processor.

  • rwr run services: Run the services processor.

  • rwr run files: Run the files processor.

  • rwr run directories: Run the directories processor.

  • rwr run configuration: Run the configuration processor.

  • rwr run git: Run the Git repository processor.

  • rwr run scripts: Run the scripts processor.

  • rwr run users: Run the users and groups processor.

  • rwr run ssh_keys: Run the SSH key processor.

Blueprint Structure

RWR blueprints are organized in a structured directory hierarchy. Here’s the current blueprint structure:

.
├── bootstrap.yaml
├── files
│   ├── dots.yaml
│   ├── files.yaml
│   └── src
│       ├── .config
│       ├── desktop
│       ├── dotFiles
│       ├── ssh
│       └── Wallpapers
├── git
│   ├── org.yaml
│   └── personal.yaml
├── init.yaml
├── packages
│   ├── apt.yaml
│   ├── brew.yaml
│   └── cargo.yaml
├── repositories
│   └── apt.yaml
├── scripts
│   ├── files
│   │   └── nerd.sh
│   └── scripts.yaml
├── services
│   └── services.yaml
└── users
    └── users.yaml

In this structure:

• bootstrap.yaml: Defines the initial setup tasks, such as installing essential packages and creating directories.

• init.yaml: The main entry point that defines the blueprint configuration and order of execution.

• files/: Contains blueprints for managing files, dotfiles, and related resources.

• git/: Manages Git repositories for both organizational and personal use.

• packages/: Defines packages to be installed using different package managers (apt, brew, cargo).

• repositories/: Manages package repositories (currently for apt).

• scripts/: Contains scripts to be executed and their configurations.

• services/: Manages system services.

• users/: Manages user accounts and groups.

This structure allows for a clean separation of concerns and makes it easy to maintain and extend your system configuration.

Note	All configuration files (.yaml, .json, or .toml) can be in YAML, JSON, or TOML format, depending on your preference. The examples shown use the .yaml extension, but you can use .json or .toml as well.

Blueprint Types

RWR supports the following blueprint types:

• packages: Defines packages to be installed or removed using various package managers. Supports additional arguments for installation.

• repositories: Defines repositories to be managed for different package managers.

• Files Blueprints (All fall under files processor)

  • files: Defines files to be copied, moved, deleted, created, or modified. Supports URL sources and intelligent renaming.

  • directories: Defines directories to be managed, including creation, deletion, and modification of permissions and ownership.

  • templates: Defines template files to be processed and rendered during the execution of the blueprints.

• services: Defines services to be managed, including starting, stopping, enabling, and disabling services.

• configuration: Defines configuration settings to be applied to the system.

• git: Defines Git repositories to be cloned or managed.

• scripts: Defines scripts to be executed as part of the configuration process.

• users: Defines user accounts and groups to be created or managed.

• bootstrap: Defines the initial setup tasks for the system.

• ssh_keys: Defines SSH keys to be generated and managed, with the ability to set a key as the default RWR SSH key.

Documentation Wiki

For detailed documentation on how to use RWR, please refer to our Wiki. Here’s an overview of the topics covered:

Getting Started

• Home

• Quick Start Guide

• What are Blueprints?

• Init File - The Entrypoint

• Bootstrap - System Prerequisites

RWR Command Line Interface

• CLI & Flags

• Config File

Blueprints

• Blueprint Best Practices

• Blueprint Types

  • Packages Blueprint

  • Repositories Blueprint

  • Configuration Blueprint

  • Files Blueprint

  • Directories Blueprint

  • Services Blueprint

  • Users and Groups Blueprint

  • Git Blueprint

  • Scripts Blueprint

  • SSH Keys Blueprint

Advanced Topics

• Template Variables

For more detailed information on each topic, please visit the corresponding Wiki page.

Road to 1.0

• For Beta/MVP (0.1.0):

  • Linux Tested/Validate - Ubuntu/Fedora/Arch are goal for tested support

• For 0.2.0:

  • Test/Validate macOS or Windows

• For 0.3.0:

  • Test/Validate final OS macOS or Windows

• For 1.0.0:

  • All items listed in the "Road to 1.0" section need to be tested and validated across all platforms (Linux, macOS, and Windows)

Linux (Debian/Ubuntu, Fedora, Arch)

• ✓ Bootstrap Processor

• ✓ Package Manager Processor

• ✓ Repositories Processor

• ✓ Configuration Processor

• ✓ Packages Processor

• ✓ Services Processor

• ✓ Files Processor

• ✓ Directories Processor

• ✓ Git Repository Processor

• ✓ Scripts Processor

• ✓ Users and Groups Processor

• ✓ SSH Keys

• ✓ Fonts Processor

macOS

• ❏ Bootstrap Processor

• ❏ Package Manager Processor

• ❏ Repositories Processor

• ❏ Configuration Processor

• ❏ Packages Processor

• ❏ Services Processor

• ❏ Files Processor

• ❏ Directories Processor

• ❏ Git Repository Processor

• ❏ Scripts Processor

• ❏ Users and Groups Processor

• ❏ SSH Keys

• ❏ Fonts Processor

Windows

• ❏ Bootstrap Processor

• ❏ Package Manager Processor

• ❏ Repositories Processor

• ❏ Configuration Processor

• ❏ Packages Processor

• ❏ Services Processor

• ❏ Files Processor

• ❏ Directories Processor

• ❏ Git Repository Processor

• ❏ Scripts Processor

• ❏ Users and Groups Processor

• ❏ SSH Keys

• ❏ Fonts Processor

Contributing

Contributions to RWR are welcome! If you’d like to contribute, please follow these steps:

1. Fork the repository on GitHub.

2. Create a new branch for your feature or bug fix.

3. Make your changes and commit them with descriptive commit messages.

4. Push your changes to your forked repository.

5. Submit a pull request to the main repository.

Please ensure that your code follows the project’s coding style and includes appropriate tests.

License

RWR is open-source software licensed under the MIT License.

Contact

If you have any questions, suggestions, or feedback, please open an issue on the GitHub repository or contact the maintainers directly.

Happy distrohopping with RWR!