Skip to content

SETUP.md

Latest commit

 

History

History
359 lines (275 loc) · 7.53 KB

SETUP.md

File metadata and controls

359 lines (275 loc) · 7.53 KB
Raw

Dotsible Setup Guide

This guide provides detailed instructions for setting up and configuring Dotsible for your environment.

Quick Start (Fresh Arch Linux Install)

If you just finished installing Arch Linux (with your DE/WM of choice already set up) and haven't touched this repo yet, this is the fastest path to a fully configured machine — no manual pacman -S git ansible ... required:

curl -fsSL https://raw.githubusercontent.com/bitcode/dotfiles/master/install.sh | bash

This installs git if missing, clones the repo to ~/dotfiles, and hands off to ./bootstrap.sh, which installs Python, Ansible, the yay AUR helper, CLI essentials (xclip, xsel, wl-clipboard, github-cli), and the required ansible-galaxy collections automatically. Once it finishes, run:

cd ~/dotfiles
./run-dotsible.sh --profile developer

If you already have the repo cloned, just run ./bootstrap.sh followed by ./run-dotsible.sh directly — no need for the curl one-liner.

Prerequisites

Control Machine Requirements

  • Operating System: Linux, macOS, or Windows (with WSL)
  • Ansible: Version 2.9 or higher
  • Python: Version 3.6 or higher
  • Git: For cloning repositories
  • SSH Client: For remote system management

Target System Requirements

  • Supported OS: Ubuntu 18.04+, Arch Linux, macOS 10.15+, Windows 10+
  • Python: Version 3.6 or higher
  • SSH Server: For remote management (optional for local)
  • Sudo Access: For system-level changes

Installation

1. Install Ansible

Ubuntu/Debian

sudo apt update
sudo apt install ansible python3-pip

Arch Linux

sudo pacman -S ansible python-pip

On Arch, ./bootstrap.sh (see Quick Start above) does this automatically, along with the ansible-galaxy install -r requirements.yml step below — manual installation is only needed if you're skipping bootstrap.sh entirely.

macOS

# Using Homebrew
brew install ansible

# Using pip
pip3 install ansible

Windows (WSL)

# Install WSL first, then use Ubuntu instructions
sudo apt update
sudo apt install ansible python3-pip

2. Clone Dotsible Repository

git clone https://github.com/username/dotsible.git
cd dotsible

3. Install Dependencies

# Install Ansible collections and roles
ansible-galaxy install -r requirements.yml

# Verify installation
ansible --version
ansible-galaxy collection list

Configuration

1. Inventory Setup

Local Development

Copy and edit the local inventory:

cp inventories/local/hosts.yml.example inventories/local/hosts.yml
vim inventories/local/hosts.yml

Example configuration:

all:
  children:
    workstations:
      children:
        ubuntu_workstations:
          hosts:
            localhost:
              ansible_host: localhost
              ansible_connection: local
              profile: developer
              features:
                - gui
                - development
                - docker

Remote Systems

For remote systems, configure SSH access:

ubuntu_workstations:
  hosts:
    remote-dev:
      ansible_host: 192.168.1.100
      ansible_user: developer
      ansible_ssh_private_key_file: ~/.ssh/id_rsa
      profile: developer

2. SSH Configuration

Generate SSH Keys

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Copy SSH Keys to Target Systems

ssh-copy-id user@target-system

Test SSH Connection

ssh user@target-system
ansible all -m ping

3. Dotfiles Configuration

Edit group_vars/all/main.yml to configure your dotfiles:

dotfiles:
  enabled: true
  repository: "https://github.com/yourusername/dotfiles.git"
  branch: "main"
  local_path: "{{ ansible_user_dir }}/.dotfiles"
  backup_existing: true

4. Profile Selection

Choose appropriate profiles for your systems:

  • minimal: Basic tools only
  • developer: Full development environment
  • server: Headless server configuration
  • gaming: Gaming setup
  • designer: Creative tools

Configure in inventory or as extra vars:

# In inventory
hosts:
  my-laptop:
    profile: developer

# Or as command line argument
ansible-playbook site.yml --extra-vars "profile=developer"

First Run

1. Test Connection

ansible all -m ping

2. Bootstrap New Systems

ansible-playbook site.yml --extra-vars "bootstrap=true"

3. Full Configuration

ansible-playbook site.yml

4. Verify Installation

ansible-playbook site.yml --tags "verify"

Advanced Configuration

1. Custom Variables

Create host-specific variables:

# Create host variable file
vim host_vars/hostname.yml

Example host variables:

# host_vars/my-laptop.yml
git_user_name: "John Doe"
git_user_email: "john@example.com"
dotfiles_repo: "https://github.com/johndoe/dotfiles.git"

custom_packages:
  - neovim
  - tmux
  - zsh

2. Environment-Specific Settings

Use different inventories for different environments:

# Development environment
ansible-playbook -i inventories/development/hosts.yml site.yml

# Production environment
ansible-playbook -i inventories/production/hosts.yml site.yml

3. Vault for Secrets

Encrypt sensitive data:

# Create vault file
ansible-vault create group_vars/all/vault.yml

# Edit vault file
ansible-vault edit group_vars/all/vault.yml

# Run with vault password
ansible-playbook site.yml --ask-vault-pass

4. Custom Roles

Create custom application roles:

mkdir -p roles/applications/myapp/{tasks,vars,handlers,templates,meta}

Troubleshooting

Common Issues

Connection Problems

# Test basic connectivity
ansible all -m ping

# Use password authentication
ansible-playbook site.yml --ask-pass

# Specify SSH user
ansible-playbook site.yml --user=myuser

Permission Issues

# Use sudo
ansible-playbook site.yml --ask-become-pass

# Skip privilege escalation
ansible-playbook site.yml --extra-vars "ansible_become=false"

Package Installation Failures

# Update package cache
ansible all -m package -a "update_cache=yes" --become

# Check package availability
ansible all -m package -a "name=git state=present" --check

Debug Mode

Enable verbose output:

# Basic verbose
ansible-playbook site.yml -v

# More verbose
ansible-playbook site.yml -vvv

# Debug mode
ansible-playbook site.yml --check --diff

Log Analysis

Check Ansible logs:

# View log file
tail -f ansible.log

# Filter for errors
grep ERROR ansible.log

# Filter for specific host
grep "hostname" ansible.log

Performance Optimization

1. Parallel Execution

# ansible.cfg
[defaults]
forks = 20

2. SSH Optimization

# ansible.cfg
[ssh_connection]
ssh_args = -C -o ControlMaster=auto -o ControlPersist=60s
pipelining = True

3. Fact Caching

# ansible.cfg
[defaults]
gathering = smart
fact_caching = memory
fact_caching_timeout = 86400

Next Steps

  1. Customize Profiles: Modify existing profiles or create new ones
  2. Add Applications: Create roles for additional applications
  3. Integrate CI/CD: Set up automated testing and deployment
  4. Monitor Systems: Implement monitoring and alerting
  5. Backup Configuration: Set up configuration backups

Support