Skip to content

README.md

Latest commit

 

History

History
242 lines (174 loc) · 6.95 KB

README.md

File metadata and controls

242 lines (174 loc) · 6.95 KB

Debian Development Machine Setup

This directory contains Ansible automation scripts to set up a consistent development environment on Debian. The automation installs and configures common development tools, applications, and settings to create a ready-to-use development environment.

Features

  • APT Package Management: Installs essential development tools and applications
  • Flatpak Package Management: Installs GUI applications via Flatpak
  • Python Setup: Bootstraps uv via pipx and installs Python CLI tools via uv
  • Node.js Setup: Installs npm global packages
  • VS Code Extensions: Configures VS Code with essential development extensions
  • Git Setup: Configures Git with user information, Git LFS, and Git Credential Manager
  • AppImage Support: Installs applications via AppImage with desktop integration
  • Custom Script Support: Allows for additional customization via custom scripts

Prerequisites

  • Debian 13 (Trixie) or later
  • Internet connection
  • Administrator (sudo) privileges

System Compatibility

This setup has been tested and confirmed to work on:

  • Debian 13 (Trixie)
  • WSL Debian

Quick Start

  1. Get the script:

    # Clone the repository if you haven't already
git clone https://github.com/ryanspletzer/dev-machine-setup.git
cd dev-machine-setup/debian

# Allow the setup.sh script to run
chmod +x ./setup.sh

  2. Run the setup script:

    # Run the script
./setup.sh -e "your.email@example.com"

Setup Options

The setup.sh script accepts several options:

Usage: ./setup.sh [-v] [-e git_email] [-n git_name] [-p] [-c] [playbook_file]
  -v              Enable verbose output (can be repeated for more verbosity, e.g. -vv or -vvv)
  -e git_email    Specify Git user email
  -n git_name     Specify Git user name
  -p              Install prerequisites only (Ansible), don't run Ansible playbook
  -c              CI mode: skip interactive sudo prompts (assumes passwordless sudo)
  playbook_file   Optional playbook file name (defaults to setup.yaml)

Examples

  • Basic installation with Git email:

    ./setup.sh -e "your.email@example.com"

  • Install with verbose output and custom Git name:

    ./setup.sh -v -e "your.email@example.com" -n "Your Name"

  • Install prerequisites only (Ansible):

    ./setup.sh -p

  • Use a custom playbook file:

    ./setup.sh custom_setup.yaml

Customization

Modifying Installed Packages

Edit vars.yaml to customize which packages get installed:

System Packages

# Command-line tools and libraries via APT (object format)
apt_packages:
  - name: git
  - name: curl
  - name: cmake
  - name: golang-go
  - name: code

# GUI applications via Flatpak (currently empty by default)
flatpak_packages: []

Development Tools

# PowerShell modules
powershell_modules:
  - AWS.Tools.Common
  - Terminal-Icons

# Bootstrap uv via pipx
pipx_packages:
  - uv

# Python CLI tools via uv
uv_tools:
  - poetry
  - ruff

# VS Code extensions
vscode_extensions:
  - ms-vscode.powershell
  - github.copilot

WSL Specific Settings

If you're running in WSL, set is_wsl: true in vars.yaml to enable WSL-specific configurations.

Adding Custom Commands

You can add custom commands to be executed during setup by adding entries to custom_commands_user and custom_commands_elevated in vars.yaml.

Adding Custom Scripts

To add additional setup steps:

  1. Create a custom script in the examples/ directory or elsewhere
  2. Set the custom_script variable in vars.yaml to point to your script
  3. Make sure the script is executable (chmod +x your_script.sh)

Components

  • setup.sh: Main setup script that installs prerequisites and runs the Ansible playbook
  • setup.yaml: Ansible playbook that performs the installation and configuration
  • vars.yaml: Configuration variables defining what gets installed
  • examples/: Directory containing example custom scripts

Additional Resources

For comprehensive documentation and examples:

Notable Default Packages

The default setup includes a curated selection of popular development tools and applications:

Developer Tools

  • Git and Git LFS
  • Visual Studio Code
  • Go

Applications

  • Visual Studio Code
  • Flatpak applications (configurable)

See vars.yaml for the complete list of installed packages.

Ansible Tags

The playbook uses tags to allow selective execution of tasks:

  • system: System-level tasks
    • architecture: Architecture detection
    • wsl: WSL-specific configuration
  • apt: All APT-related tasks
    • update: Only update APT cache
    • upgrade: Only upgrade packages
    • packages: Only install packages
    • prereqs: Only prerequisite packages
    • repositories: Only add repositories
  • flatpak: Flatpak package installation
  • appimage: AppImage package installation
  • powershell: PowerShell installation and module setup
  • pipx: Python package installation via pipx (bootstraps uv)
  • uv: Python CLI tool installation via uv
  • npm: Node.js package installation
  • dotnet: .NET SDK and tools installation
  • vscode: VS Code extension installation
  • cursor: Cursor extension installation
  • git: Git configuration tasks
  • custom: Custom commands and script execution
    • user-commands: User-level commands
    • elevated-commands: Commands requiring sudo

You can run the playbook with specific tags using the -t option:

ansible-playbook -t apt,git setup.yaml

Troubleshooting

  • Logs: All installation logs are saved to a timestamped log file in the current directory.
  • Verbosity: Use the -v flag (can be repeated for more detail) to see more information during setup.
  • Failed Tasks: You can safely rerun the setup script - it will skip already completed tasks.
  • Dependencies: If you encounter errors about missing dependencies, try running with the -p flag first to install prerequisites, then run the script again normally.

Security Notes

  • The setup script securely handles your sudo password.
  • All sudo operations are performed via Ansible which is safer than multiple direct sudo calls.
  • The script only runs commands defined in the Ansible playbook or in your custom commands / custom script.

WSL Notes

If you're using WSL (Windows Subsystem for Linux), make sure to:

  1. Set is_wsl: true in vars.yaml
  2. Consider whether you need all the GUI applications since WSL is primarily a terminal environment
  3. Some features like Docker might be better installed on the Windows host when using WSL 2