netbox-ansible/README.md

# NetBox Ansible Deployment

This Ansible project deploys NetBox using Docker Compose on Ubuntu servers. It follows Ansible best practices with modular roles, idempotent operations, and comprehensive configuration management.

## Features

- **Modular Design**: Separate roles for system updates, Docker installation, and NetBox deployment
- **Idempotent**: Safe to run multiple times without side effects
- **Ubuntu Only**: Specifically designed for Ubuntu distributions (Focal, Jammy, Noble)
- **Docker Compose**: Uses the official NetBox Docker repository
- **Configuration Management**: Templated environment files with Ansible variables
- **Security**: Support for Ansible Vault for sensitive data
- **Backup Support**: Built-in backup playbook for data protection

## Project Structure

```
netbox-ansible/
├── ansible.cfg                 # Ansible configuration
├── inventory/
│   └── hosts.yml              # Inventory file
├── group_vars/
│   ├── netbox.yml             # Group variables
│   └── netbox/
│       └── vault.yml          # Encrypted sensitive variables
├── playbooks/
│   ├── deploy-netbox.yml      # Main deployment playbook
│   ├── update-netbox.yml      # Update NetBox playbook
│   └── backup-netbox.yml      # Backup NetBox playbook
├── roles/
│   ├── system-update/         # System package updates
│   ├── docker-install/        # Docker and Docker Compose installation
│   └── netbox-deploy/        # NetBox deployment and configuration
└── templates/                 # Additional templates if needed
```

## Prerequisites

- Ansible 2.9 or later
- Target servers running Ubuntu (Focal, Jammy, or Noble)
- SSH access to target servers with sudo privileges
- Python 3 on target servers

## Quick Start

1. **Configure Inventory**
   ```bash
   # Edit inventory/hosts.yml
   vim inventory/hosts.yml
   ```
   Add your server(s):
   ```yaml
   [netbox]
   netbox-server ansible_host=192.168.1.100 ansible_user=ubuntu
   ```

2. **Configure Variables**
   ```bash
   # Edit group variables
   vim group_vars/netbox.yml
   
   # Encrypt sensitive variables
   ansible-vault encrypt group_vars/netbox/vault.yml
   ```

3. **Deploy NetBox**
   ```bash
   # Run the deployment playbook
   ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml
   ```

## Configuration

### Group Variables (`group_vars/netbox.yml`)

Key configuration options:

- `netbox_install_dir`: Directory for NetBox installation (default: `/opt/netbox-docker`)
- `netbox_data_dir`: Directory for persistent data (default: `/opt/netbox-data`)
- `netbox_backup_dir`: Directory for backups (default: `/opt/netbox-backups`)
- `netbox_allowed_hosts`: Allowed hosts for NetBox
- `netbox_superuser_*`: Superuser configuration
- `netbox_db_*`: Database configuration
- `netbox_redis_*`: Redis configuration

### Vault Variables (`group_vars/netbox/vault.yml`)

Sensitive data should be encrypted:

```bash
# Encrypt vault file
ansible-vault encrypt group_vars/netbox/vault.yml

# Edit encrypted vault file
ansible-vault edit group_vars/netbox/vault.yml
```

### Docker Compose Overrides

Customize Docker Compose configuration via `netbox_docker_compose_overrides`:

```yaml
netbox_docker_compose_overrides:
  services:
    netbox:
      ports:
        - "8000:8080"
    db:
      volumes:
        - "/opt/netbox-data/postgres:/var/lib/postgresql/data"
```

## Playbooks

### Main Deployment (`deploy-netbox.yml`)

Deploys NetBox from scratch:
- Updates system packages
- Installs Docker and Docker Compose
- Clones NetBox Docker repository
- Configures environment files
- Starts NetBox services
- Creates superuser account

### Update NetBox (`update-netbox.yml`)

Updates existing NetBox installation:
- Updates repository
- Pulls latest Docker images
- Restarts services

### Backup NetBox (`backup-netbox.yml`)

Creates comprehensive backup:
- Database dump
- Media files
- Configuration files

## Roles

### system-update
- Updates apt package cache
- Upgrades all packages
- Installs required packages
- Optional reboot if needed

### docker-install
- Adds Docker GPG key and repository
- Installs Docker CE and Docker Compose
- Configures Docker daemon
- Adds users to docker group

### netbox-deploy
- Creates necessary directories
- Clones NetBox Docker repository
- Generates configuration files
- Starts NetBox services
- Creates superuser account

## Usage Examples

### Deploy NetBox
```bash
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml
```

### Update NetBox
```bash
ansible-playbook -i inventory/hosts.yml playbooks/update-netbox.yml
```

### Backup NetBox
```bash
ansible-playbook -i inventory/hosts.yml playbooks/backup-netbox.yml
```

### Run with Vault
```bash
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --ask-vault-pass
```

### Run Specific Tags
```bash
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --tags "docker-install"
```

## Security Considerations

1. **Encrypt Sensitive Data**: Use `ansible-vault` for passwords and secrets
2. **SSH Key Authentication**: Use SSH keys instead of passwords
3. **Firewall Rules**: Configure appropriate firewall rules
4. **Regular Updates**: Keep NetBox and dependencies updated
5. **Backup Strategy**: Implement regular backup procedures

## Troubleshooting

### Common Issues

1. **Permission Denied**: Ensure user has sudo privileges
2. **Docker Not Found**: Check Docker installation and user group membership
3. **Port Conflicts**: Verify port 8000 is available
4. **Database Connection**: Check database configuration and connectivity

### Logs and Debugging

```bash
# Enable verbose output
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml -vvv

# Check Docker Compose logs
ansible netbox -i inventory/hosts.yml -m shell -a "cd /opt/netbox-docker && docker compose logs"
```

## Contributing

1. Follow Ansible best practices
2. Ensure idempotency
3. Add appropriate tags
4. Update documentation
5. Test on multiple Ubuntu versions

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Check NetBox documentation: https://docs.netbox.dev/
- NetBox Community: https://github.com/netbox-community/netbox
- NetBox Docker: https://github.com/netbox-community/netbox-docker