Added readmes to roles

galaxy.yml

@@ -1,7 +1,7 @@
 ---
 namespace: serversideup
 name: spin
-version: 2.0.2
+version: 2.0.3
 readme: README.md
 authors:
   - Jay Rogers (https://x.com/jaydrogers)

roles/create_server/README.md

@@ -0,0 +1,98 @@
+# Server Creation Ansible Role
+
+Easily create and configure servers across multiple cloud providers (DigitalOcean, Hetzner, and Vultr). This role handles server provisioning, SSH key management, and firewall configuration automatically.
+
+## Requirements
+
+For now, this role supports the following cloud providers:
+- DigitalOcean
+- Hetzner Cloud
+- Vultr
+
+You'll need API credentials for whichever provider you choose to use.
+
+## Role Variables
+
+The role expects server configurations to be defined in your playbook or inventory. Here's an example structure:
+
+```yaml
+servers:
+  - server_name: "web-1"
+    hardware_profile: "standard-2gb"  # Must match a profile in hardware_profiles
+    environment: "production"         # Must match an environment name
+    backups: true                    # Optional, defaults to true
+
+hardware_profiles:
+  - name: "standard-2gb"
+    provider: "digitalocean"         # One of: digitalocean, hetzner, vultr
+    profile_config:
+      region: "nyc1"                 # Provider-specific configuration
+      size: "s-2vcpu-2gb"           # Varies by provider
+      image: "ubuntu-22-04-x64"
+
+providers:
+  - name: "digitalocean"
+    api_token: "your_token_here"     # Can also use DO_API_TOKEN env var
+```
+
+## Environment Variables
+
+The role supports the following environment variables for API authentication:
+
+- `DO_API_TOKEN` - DigitalOcean API token
+- `HCLOUD_TOKEN` - Hetzner Cloud API token
+- `VULTR_API_KEY` - Vultr API key
+
+## Dependencies
+
+Required Ansible collections (see `requirements.yml`):
+- `hetzner.hcloud`
+- `vultr.cloud`
+- `community.digitalocean`
+
+To install dependencies:
+```bash
+ansible-galaxy install -r requirements.yml
+```
+
+## Features
+
+- Multi-provider support (DigitalOcean, Hetzner, Vultr)
+- Automatic SSH key management
+- Standard firewall configuration across providers
+- IPv4 and IPv6 support
+- Configurable hardware profiles
+- Environment tagging
+- Backup configuration
+
+## Example Playbook
+
+```yaml
+- hosts: localhost
+  roles:
+    - role: create_server
+  vars:
+    servers:
+      - server_name: "web-1"
+        hardware_profile: "standard-2gb"
+        environment: "production"
+    
+    hardware_profiles:
+      - name: "standard-2gb"
+        provider: "digitalocean"
+        profile_config:
+          region: "nyc1"
+          size: "s-2vcpu-2gb"
+          image: "ubuntu-22-04-x64"
+```
+
+## Firewall Configuration
+
+The role automatically configures a standard firewall for web applications with the following rules:
+
+- ICMP (ping) from anywhere
+- SSH (port 22) from anywhere
+- HTTP (port 80) from anywhere
+- HTTPS (port 443) from anywhere
+- SSH tunnel (port 2222) from anywhere
+- All outbound traffic allowed 

roles/docker_user/README.md

@@ -0,0 +1,88 @@
+# Docker User Ansible Role
+
+Create and configure a dedicated user for Docker operations with proper permissions and SSH access. This role handles user creation, group management, and SSH key configuration.
+
+## Requirements
+
+This role is designed to work on Unix-like systems that support user and group management. It requires:
+- Ansible 2.9 or higher
+- Root or sudo access on the target system
+
+## Role Variables
+
+All configuration is handled through the `docker_user` dictionary in `defaults/main.yml`:
+
+```yaml
+docker_user:
+  username: deploy            # Username for the Docker user
+  uid: 9999                  # User ID
+  group: deploy              # Primary group name
+  secondary_groups: "docker" # Additional groups (comma-separated)
+  gid: 9999                 # Group ID
+  # Optional: Configure SSH keys directly in vars
+  # authorized_ssh_keys: 
+  #   - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKNJGtd7a4DBHsQi7HGrC5xz0eAEFHZ3Ogh3FEFI2345 fake@key"
+```
+
+The role also supports these additional variables:
+- `deploy_public_key`: SSH public key added via "spin configure" command
+- `users`: List of admin/sudo users whose SSH keys should be added to the Docker user
+
+## Dependencies
+
+Required Ansible collections (see `requirements.yml`):
+```yaml
+collections:
+  - name: ansible.posix
+```
+
+To install dependencies:
+```bash
+ansible-galaxy install -r requirements.yml
+```
+
+## Features
+
+- Creates a dedicated user for Docker operations
+- Configures primary and secondary group memberships
+- Manages SSH key access through multiple methods:
+  - Direct configuration via `authorized_ssh_keys`
+  - Integration with "spin configure" command
+  - Automatic import of admin/sudo users' SSH keys
+- Customizable user/group IDs and home directory
+- Bash shell configuration
+
+## Example Playbook
+
+Basic usage:
+```yaml
+- hosts: servers
+  roles:
+    - role: docker_user
+```
+
+With custom configuration:
+```yaml
+- hosts: servers
+  roles:
+    - role: docker_user
+      vars:
+        docker_user:
+          username: dockerops
+          uid: 8888
+          group: dockerops
+          secondary_groups: "docker,www-data"
+          gid: 8888
+          authorized_ssh_keys:
+            - "ssh-ed25519 AAAAC3... user@host"
+```
+
+## SSH Key Management
+
+The role supports three methods for SSH key management, in order of precedence:
+
+1. Keys specified in `docker_user.authorized_ssh_keys`
+2. Key provided via `deploy_public_key` variable
+3. SSH keys from users with sudo privileges
+
+All valid keys will be added to the Docker user's `authorized_keys` file. 

roles/update_server/README.md

@@ -0,0 +1,77 @@
+# Server Update Ansible Role
+
+A simple but robust role to safely update Ubuntu servers, handling package updates and automatic reboots when required. This role includes connection checking and proper wait times to ensure system stability.
+
+## Requirements
+
+- Target system must be Ubuntu/Debian-based (uses `apt` package manager)
+- SSH access with sudo privileges
+- Ansible 2.9 or higher
+
+## Role Features
+
+- Updates package cache
+- Performs full system upgrade
+- Removes unnecessary packages (autoremove)
+- Cleans package cache (autoclean)
+- Automatically handles required reboots
+- Includes connection checking before and after updates
+- Configurable timeout values
+
+## Role Behavior
+
+1. Verifies SSH connection is available (5-minute timeout)
+2. Updates and upgrades all system packages
+3. Checks if a system reboot is required
+4. Performs automatic reboot if necessary
+5. Waits for system to come back online
+6. Verifies SSH connection is re-established
+
+## Configuration
+
+The role uses these default timeout values:
+```yaml
+# Initial connection timeout (in seconds)
+connection_timeout: 300
+
+# Package manager lock timeout (in seconds)
+lock_timeout: 600
+
+# Reboot timeout (in seconds)
+reboot_timeout: 600
+```
+
+## Example Playbook
+
+Basic usage:
+```yaml
+- hosts: servers
+  roles:
+    - role: update_server
+```
+
+With custom timeouts:
+```yaml
+- hosts: servers
+  roles:
+    - role: update_server
+      vars:
+        connection_timeout: 600    # 10 minutes
+        lock_timeout: 1200         # 20 minutes
+        reboot_timeout: 900        # 15 minutes
+```
+
+## Important Notes
+
+- The update process may take several minutes depending on:
+  - Server performance
+  - Network connection speed
+  - Number of packages to update
+  - Whether a reboot is required
+- The role includes appropriate wait times and connection checks to prevent SSH disconnection issues
+- If the server requires a reboot, the role will handle it automatically
+- The role is idempotent and can be run multiple times safely
+
+## Dependencies
+
+This role has no external dependencies beyond core Ansible modules.