ilia
69a39e5e5b
## Summary This PR adds comprehensive support for deploying the **POTE** application project via Ansible, along with improvements to IP conflict detection and a new app stack provisioning system for Proxmox-managed LXC containers. ## Key Features ### 🆕 New Roles - **`roles/pote`**: Python/venv deployment role for POTE (PostgreSQL, cron jobs, Alembic migrations) - **`roles/app_setup`**: Generic app deployment role (Node.js/systemd) - **`roles/base_os`**: Base OS hardening role ### 🛡️ Safety Improvements - IP uniqueness validation within projects - Proxmox-side IP conflict detection - Enhanced error messages for IP conflicts ### 📦 New Playbooks - `playbooks/app/site.yml`: End-to-end app stack deployment - `playbooks/app/provision_vms.yml`: Proxmox guest provisioning - `playbooks/app/configure_app.yml`: OS + application configuration ## Security - ✅ All secrets stored in encrypted vault.yml - ✅ Deploy keys excluded via .gitignore - ✅ No plaintext secrets committed ## Testing - ✅ POTE successfully deployed to dev/qa/prod environments - ✅ All components validated (Git, PostgreSQL, cron, migrations) Co-authored-by: ilia <ilia@levkin.ca> Reviewed-on: #3
129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
# Tailscale VPN Setup Guide
|
|
|
|
Tailscale provides secure mesh networking across all your machines with zero-config VPN connectivity.
|
|
|
|
## Prerequisites
|
|
- Tailscale account (free at https://tailscale.com)
|
|
- Auth key from Tailscale admin console
|
|
|
|
## Quick Setup (3 Steps)
|
|
|
|
### 1. Get Your Auth Key
|
|
1. Visit https://login.tailscale.com/admin/settings/keys
|
|
2. Click "Generate auth key"
|
|
3. Configure key:
|
|
- **Reusable**: Yes (for multiple machines)
|
|
- **Expiration**: 90 days or longer
|
|
4. Copy the key (starts with `tskey-auth-`)
|
|
|
|
### 2. Store Key Securely
|
|
```bash
|
|
make create-vault
|
|
```
|
|
Add this content when prompted:
|
|
```yaml
|
|
---
|
|
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
|
|
```
|
|
|
|
### 3. Deploy Tailscale
|
|
```bash
|
|
# Preview changes (dry run)
|
|
make tailscale-check
|
|
|
|
# Install on all machines
|
|
make tailscale
|
|
|
|
# Check status
|
|
make tailscale-status
|
|
```
|
|
|
|
## Deployment Options
|
|
|
|
### Target Specific Machines
|
|
```bash
|
|
# Development machines only
|
|
make tailscale-dev
|
|
|
|
# Specific hosts
|
|
ansible-playbook playbooks/tailscale.yml --limit "dev01,bottom"
|
|
```
|
|
|
|
### Manual Installation
|
|
```bash
|
|
# With custom auth key (not recommended - use vault instead)
|
|
ansible-playbook playbooks/tailscale.yml -e "tailscale_auth_key=your-key"
|
|
|
|
# As part of existing playbooks
|
|
ansible-playbook playbooks/development.yml --tags tailscale
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Global Settings (`inventories/production/group_vars/all/main.yml`)
|
|
```yaml
|
|
tailscale_auth_key: "{{ vault_tailscale_auth_key }}" # From vault
|
|
tailscale_accept_routes: true # Accept subnet routes
|
|
tailscale_accept_dns: true # Accept DNS settings
|
|
tailscale_ssh: true # Enable SSH over Tailscale
|
|
```
|
|
|
|
### Host-Specific Settings (`inventories/production/host_vars/<hostname>.yml`)
|
|
```yaml
|
|
tailscale_hostname: "custom-name" # Override hostname
|
|
tailscale_advertise_routes: "192.168.1.0/24" # Share local subnet
|
|
tailscale_shields_up: false # Block incoming connections
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Check Service Status
|
|
```bash
|
|
# Via Ansible
|
|
make tailscale-status
|
|
|
|
# On target machine
|
|
sudo systemctl status tailscaled
|
|
tailscale status
|
|
```
|
|
|
|
### View Logs
|
|
```bash
|
|
sudo journalctl -u tailscaled -f
|
|
```
|
|
|
|
### Manual Connection
|
|
If auth key wasn't provided during setup:
|
|
```bash
|
|
sudo tailscale up
|
|
```
|
|
|
|
### Reset Connection
|
|
```bash
|
|
ansible-playbook playbooks/tailscale.yml -e "tailscale_reset=true"
|
|
```
|
|
|
|
## Security Best Practices
|
|
- Always use Ansible Vault for auth keys
|
|
- Consider ephemeral keys for one-time setups
|
|
- Authorize machines in Tailscale admin console
|
|
- Review SSH settings if enabling Tailscale SSH
|
|
|
|
## Supported Platforms
|
|
- **Ubuntu**: focal, jammy, noble
|
|
- **Debian**: bullseye, bookworm, trixie
|
|
- **Alpine Linux**: all versions
|
|
|
|
The role automatically detects OS and uses appropriate package manager.
|
|
|
|
## How It Works
|
|
|
|
1. **Playbook runs** → looks for `tailscale_auth_key`
|
|
2. **Checks inventory group vars** → finds `{{ vault_tailscale_auth_key }}`
|
|
3. **Decrypts vault** → retrieves actual auth key
|
|
4. **Installs Tailscale** → configures with your settings
|
|
5. **Connects to network** → machine appears in admin console
|
|
|
|
## Related Documentation
|
|
- [Ansible Vault Guide](./vault.md) - Managing secrets securely
|
|
- [Network Architecture](../reference/network.md) - Overall network design |