eef01d87d0
- Add roles/pote: Python/venv deployment role with PostgreSQL, cron jobs - Add playbooks/app/: Proxmox app stack provisioning and configuration - Add roles/app_setup: Generic app deployment role (Node.js/systemd) - Add roles/base_os: Base OS hardening role - Enhance roles/proxmox_vm: Split LXC/KVM tasks, improve error handling - Add IP uniqueness validation: Preflight check for duplicate IPs within projects - Add Proxmox-side IP conflict detection: Check existing LXC net0 configs - Update inventories/production/group_vars/all/main.yml: Add pote project config - Add vault.example.yml: Template for POTE secrets (git key, DB, SMTP) - Update .gitignore: Exclude deploy keys, backup files, and other secrets - Update documentation: README, role docs, execution flow guides Security: - All secrets stored in encrypted vault.yml (never committed in plaintext) - Deploy keys excluded via .gitignore - IP conflict guardrails prevent accidental duplicate IP assignments
236 lines
4.5 KiB
Markdown
236 lines
4.5 KiB
Markdown
# Initial Setup Guide
|
|
|
|
Complete guide for setting up your Ansible infrastructure management system.
|
|
|
|
## Prerequisites
|
|
|
|
- **Control Machine Requirements:**
|
|
- Linux/macOS/WSL
|
|
- Python 3.x installed
|
|
- Git installed
|
|
- SSH client
|
|
|
|
- **Target Machine Requirements:**
|
|
- SSH server running
|
|
- Python 3.x installed
|
|
- User with sudo privileges
|
|
|
|
## Step 1: Clone Repository
|
|
|
|
```bash
|
|
git clone <your-repo-url>
|
|
cd ansible
|
|
```
|
|
|
|
## Step 2: Install Ansible
|
|
|
|
### Ubuntu/Debian
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install ansible python3-pip
|
|
```
|
|
|
|
### macOS
|
|
```bash
|
|
brew install ansible
|
|
```
|
|
|
|
### Python pip
|
|
```bash
|
|
pip3 install ansible
|
|
```
|
|
|
|
## Step 3: Install Dependencies
|
|
|
|
```bash
|
|
# Install required Ansible collections
|
|
make bootstrap
|
|
|
|
# Or manually:
|
|
ansible-galaxy collection install -r collections/requirements.yml
|
|
```
|
|
|
|
## Step 4: Configure Inventory
|
|
|
|
Edit `hosts` file to match your infrastructure:
|
|
|
|
```ini
|
|
[dev]
|
|
dev01 ansible_host=192.168.1.100
|
|
bottom ansible_host=192.168.1.101
|
|
debianDesktopVM ansible_host=192.168.1.102
|
|
|
|
[local]
|
|
localhost ansible_connection=local
|
|
|
|
[gitea]
|
|
giteaVM ansible_host=192.168.1.110
|
|
|
|
[portainer]
|
|
portainerVM ansible_host=192.168.1.111
|
|
```
|
|
|
|
## Step 5: Set Up SSH Access
|
|
|
|
### Generate SSH Key (if needed)
|
|
```bash
|
|
ssh-keygen -t ed25519 -C "ansible@control"
|
|
```
|
|
|
|
### Copy Key to Hosts
|
|
```bash
|
|
ssh-copy-id user@dev01
|
|
ssh-copy-id user@bottom
|
|
# Repeat for all hosts
|
|
```
|
|
|
|
### Test Connection
|
|
```bash
|
|
make status
|
|
# Or:
|
|
ansible all -m ping
|
|
```
|
|
|
|
## Step 6: Configure Vault
|
|
|
|
Vault stores sensitive data like passwords and API keys.
|
|
|
|
### Create Vault Password
|
|
```bash
|
|
# Option 1: Password file (recommended)
|
|
echo "your-secure-password" > ~/.ansible-vault-pass
|
|
chmod 600 ~/.ansible-vault-pass
|
|
|
|
# Option 2: Use interactive prompt (add --ask-vault-pass to commands)
|
|
```
|
|
|
|
### Create Vault File
|
|
```bash
|
|
make create-vault
|
|
```
|
|
|
|
### Add Required Secrets
|
|
Add these variables when the editor opens:
|
|
```yaml
|
|
---
|
|
# Tailscale (if using VPN)
|
|
vault_tailscale_auth_key: "tskey-auth-..."
|
|
|
|
# Proxmox (if creating VMs)
|
|
vault_proxmox_host: "192.168.1.10"
|
|
vault_proxmox_user: "root@pam"
|
|
vault_proxmox_password: "proxmox-password"
|
|
vault_vm_cipassword: "vm-default-password"
|
|
|
|
# SSH Keys
|
|
vault_ssh_public_key: "ssh-ed25519 AAAA..."
|
|
```
|
|
|
|
## Step 7: Configure Variables
|
|
|
|
### Global Settings
|
|
Edit `inventories/production/group_vars/all/main.yml`:
|
|
```yaml
|
|
# Timezone and locale
|
|
timezone: "America/New_York" # Your timezone
|
|
locale: "en_US.UTF-8"
|
|
|
|
# User configuration
|
|
default_user: "your-username"
|
|
default_shell: "/usr/bin/zsh"
|
|
|
|
# Security settings
|
|
ssh_port: 22
|
|
ssh_permit_root_login: "no"
|
|
```
|
|
|
|
### Host-Specific Settings
|
|
Create/edit `inventories/production/host_vars/<hostname>.yml` for host-specific configuration.
|
|
|
|
## Step 8: Test Configuration
|
|
|
|
Always test before applying changes:
|
|
|
|
```bash
|
|
# Dry run on all hosts
|
|
make check
|
|
|
|
# Dry run on specific host
|
|
make check HOST=dev01
|
|
|
|
# Check specific role
|
|
ansible-playbook playbooks/development.yml --check --tags docker
|
|
```
|
|
|
|
## Step 9: Deploy
|
|
|
|
### Full Deployment
|
|
```bash
|
|
# Deploy to all development hosts
|
|
make apply
|
|
|
|
# Deploy to specific host
|
|
make dev HOST=dev01
|
|
```
|
|
|
|
### Selective Deployment
|
|
```bash
|
|
# Install only Docker
|
|
make docker
|
|
|
|
# Configure only shell
|
|
make shell
|
|
|
|
# Deploy Tailscale VPN
|
|
make tailscale
|
|
```
|
|
|
|
## Step 10: Verify Installation
|
|
|
|
```bash
|
|
# Check system status
|
|
make status
|
|
|
|
# Gather facts
|
|
make facts
|
|
|
|
# Check specific services
|
|
ansible dev -m shell -a "docker --version"
|
|
ansible dev -m shell -a "tailscale status"
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
### SSH Connection Failed
|
|
- Verify SSH keys are copied: `ssh-copy-id user@host`
|
|
- Check SSH service: `ssh user@host`
|
|
- Verify inventory file has correct IP/hostname
|
|
|
|
### Vault Password Issues
|
|
- Check vault password file exists and has correct permissions
|
|
- Verify password is correct: `ansible-vault view inventories/production/group_vars/all/vault.yml`
|
|
|
|
### Python Not Found
|
|
- Install Python on target: `sudo apt install python3`
|
|
- Set Python interpreter in inventory:
|
|
```ini
|
|
dev01 ansible_host=192.168.1.100 ansible_python_interpreter=/usr/bin/python3
|
|
```
|
|
|
|
### Sudo Password Required
|
|
- Configure passwordless sudo for automation user
|
|
- Or use `--ask-become-pass` flag
|
|
|
|
## Next Steps
|
|
|
|
1. [Configure Tailscale VPN](./tailscale.md) for secure networking
|
|
2. [Set up security hardening](./security.md)
|
|
3. [Deploy monitoring](./monitoring.md)
|
|
4. [Create custom roles](./custom-roles.md) for your specific needs
|
|
|
|
## Getting Help
|
|
|
|
- Run `make help` for available commands
|
|
- Check role README files in `roles/*/README.md`
|
|
- Review example playbooks in repository
|
|
- Check Ansible documentation at https://docs.ansible.com |