🧪 devalchemy

devalchemy is a cross-platform development environment automation toolkit powered by Ansible. It turns fresh and also existing machines into fully-configured dev setups — whether you're on macOS, Linux, or Windows.

"Transform your system into a dev powerhouse — with a touch of automation magic."

✨ Features

• ✅ Unified setup for macOS, Linux, and Windows
• 📦 Install development tools, CLIs, languages, and more
• ⚙️ Easily extensible Ansible roles and playbooks
• 💻 Consistent dev experience across all platforms
• 🔒 Minimal privileges needed (no full root where not required)
• 🐳 Automated cross-platform testing via Docker and VMs

---

Evolutionary Background

devalchemy was born out of the need for a streamlined, consistent development environment across different platforms. As developers ourselves, we understand the pain points of setting up and maintaining development environments. With devalchemy, we aim to simplify this process, allowing developers to focus on what they do best: writing code.

Painpoints addressed:

• Inconsistent setups across different OSes
• Time-consuming manual installations
• Faster onboarding of new team members
• Difficulty in maintaining and updating dev environments
• Failing development setups are not reproducible.
• Over-reliance on OS-specific scripts
• Security concerns with elevated privileges

Base Concepts

The core idea of devalchemy is to use Ansible playbooks and roles to define and automate the setup of development environments. This includes installing essential tools, configuring settings, and managing dependencies.
Every role is platform independent and can be applied to macOS, Linux, and Windows. The playbooks are designed to be modular, allowing users to pick and choose which components they want to install.
The setup is idempotent, meaning you can run the playbooks multiple times without causing issues or duplications. This ensures that your development environment remains consistent and up-to-date.
Despite the common use of Ansible in server environments where changes are pushed from a central location, devalchemy is designed for local pull based execution on individual machines. This approach allows developers to maintain control over their own environments while still benefiting from automation. Every ansible run can be simulated with --check to see what changes would be applied.

---

🚀 Getting Started

1. Clone the repo

git clone https://github.com/csautter/dev-alchemy.git
cd dev-alchemy

2. Install Ansible

Make sure Ansible is installed on your system.

macOS (via Homebrew):

brew install ansible

Ubuntu / Debian:

sudo apt update && sudo apt install ansible

Windows:

For the most native Windows experience, use cygwin and install ansible via pip:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
choco install -y cygwin --params \"/InstallDir:C:\cygwin64 /NoAdmin /NoStartMenu\"
choco install -y cyg-get
cyg-get python39 python39-pip python39-cryptography openssh git make gcc-core gcc-g++ libffi-devel openssl-devel sshpass
C:\\cygwin64\\bin\\python3.9.exe -m pip install ansible
C:\\cygwin64\\bin\\python3.9.exe -m pip install pywinrm

ℹ️ For Windows there are two options to connect to the target host: via SSH or via WinRM.

The WinRM option is more native to Windows, but requires some additional setup on the target host. It might also be blocked by company policies.

# Enable WinRM
Set-Item -Path WSMan:\localhost\Service\AllowUnencrypted -Value $true; \
Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true; \
Enable-PSRemoting -Force

The SSH option requires an SSH server to be installed on the target host, but is easier to set up.

# Enable SSH Server
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0; \
Start-Service sshd; Set-Service -Name sshd -StartupType 'Automatic';

In both cases you might need to adjust the firewall settings to allow incoming connections. Also make sure to use a user with admin privileges. Create a new user if needed.

# ⚠️ OPTIONAL - use your existing user if possible
# Create new user
# And of course set a secure password!
net user ansible 'Secret123!@#' /add; \
net localgroup Administrators ansible /add

---

3. Run the Playbook

Run the Playbook on localhost

Dry run to check for issues:

ansible-playbook playbooks/setup.yml -i inventory/localhost.yml --check

ansible-playbook playbooks/setup.yml -i inventory/localhost.yml

Run the Playbook on a remote host or in a VM

Dry run to check for issues:

HOST="192.168.179.21"
# write to inventory file
cat <<EOF > inventory/remote.yml
all:
  hosts:
    $HOST:
      ansible_user: admin
EOF
ansible-playbook playbooks/setup.yml -i inventory/remote.yml -l "$HOST" --ask-pass --ask-become-pass --check

Apply the playbook:

ansible-playbook playbooks/setup.yml -i inventory/remote.yml -l "$HOST" --ask-pass --ask-become-pass

You can customize the inventory or pass variables via CLI.

Run the Playbook on Windows

Apply the playbook via WinRM:

$DevAlchemyPath = "C:\path\to\dev-alchemy"
C:\\cygwin64\\bin\\bash.exe -l -c "$DevAlchemyPath && ansible-playbook playbooks/setup.yml -i inventory/localhost_windows.yml -l windows_host"

Apply the playbook via SSH:

$DevAlchemyPath = "C:\path\to\dev-alchemy"
C:\\cygwin64\\bin\\bash.exe -l -c "$DevAlchemyPath && ansible-playbook playbooks/setup.yml -i inventory/localhost_windows_ssh.yml -l windows_host --ask-pass -vvv"

🧩 Structure

devalchemy/
├── roles/
│   ├── role/
│   ├── role2/
│   └── role3/
├── inventory/
│   └── localhost.yml
├── playbooks/
│   └── setup.yml
└── README.md

---

🛠️ Customization

• Add or tweak roles in roles/

• Use tags to run specific parts:

  ansible-playbook playbooks/setup.yml --tags "dotfiles,python"

• Pass variables:

  ansible-playbook playbooks/setup.yml -e "install_docker=true"

---

Testing

🧪 Cross-Platform Testing Matrix

Host OS	Test Linux	Test macOS	Test Windows
macOS	Docker	Tart VM	VM (e.g., UTM)
Linux	Docker	---	VM (e.g., VirtualBox)
Windows	WSL/Docker	---	Docker Desktop (Windows Containers)/VM

• Docker: Used for lightweight Linux container testing on macOS, Linux, and Windows.
• Windows Containers: Used for lightweight Windows container testing on Windows hosts with Docker Desktop.
• Tart VM: Used for macOS VM testing on macOS hosts.
• UTM VM: Used for Windows VM testing on macOS hosts.
• WSL: Windows Subsystem for Linux, enables Linux testing on Windows.
• VM: Generic virtual machine solutions (e.g., VirtualBox, Hyper-V) for cross-platform testing.

Note: macOS VM testing is only supported on macOS hosts due to Apple licensing restrictions. There might exist workarounds, but they are not covered here.

Local tests for ubuntu (on linux, WSL, windows or macos)

To test ansible roles for ubuntu, you can use the provided docker-compose setup:

docker compose -f deployments/docker-compose/ansible/docker-compose.yml up

The container will run the ansible playbook within itself. This is a good way to test changes locally without affecting your host system.

To cleanup afterwards, simply run:

docker compose -f deployments/docker-compose/ansible/docker-compose.yml down

Local tests for macOS (on macos)

To test changes locally on macOS, you can use the provided script:

./scripts/macos/test-ansible-macos.sh

The script will run the ansible playbook against a temporary virtual machine managed by Tart. Tart is a lightweight VM manager for macOS. You can find more information about Tart here.

To cleanup afterwards, run:

tart delete sequoia-base

This will delete the temporary VM.

---

Local tests for windows (on macos)

On macOS there is currently no fully automated test setup for ansible on windows. I recommend to use a Windows VM. Check Windows on UTM for a guide to install windows in UTM on macos.

Local tests for windows (on windows)

To test changes locally on windows, you can use the provided docker-compose setup:

docker compose -f deployments/docker-compose/ansible-windows/docker-compose.yml up

The container will run the ansible playbook against itself.

To cleanup afterwards, run:

docker compose -f deployments/docker-compose/ansible-windows/docker-compose.yml down

Check the README in the deployments/docker-compose/ansible-windows/ folder for more details.

📦 Supported Tools

Out-of-the-box roles can install (depending on platform):

• java
• jetbrains
• k9s
• kind
• kubectl
• kubelogin
• spotify

Full list in roles/ and tagged tasks

---

🌍 Cross-Platform Notes

Platform	Status	Notes
macOS	✅ Supported	via Homebrew
Linux	✅ Supported	tested on Ubuntu
Windows	✅ Supported	via cygwin

---

🤝 Contributing

Contributions welcome! Feel free to:

• Add new roles (e.g., Rust, Java, etc.)
• Improve cross-platform support
• Fix bugs or enhance docs

---

📜 License

MIT License — see LICENSE file.

---

💡 Inspiration

This project was born from a need to simplify dev environment onboarding across multiple systems, without resorting to OS-specific scripts. With Ansible and a touch of Dev Alchemy, setup becomes reproducible and delightful.

---

🧪 Happy hacking with devalchemy!