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

   # Edit inventory/hosts.yml
   vim inventory/hosts.yml
   

   Add your server(s):

   [netbox]
   netbox-server ansible_host=192.168.1.100 ansible_user=ubuntu
   

2. Configure Variables

   # Edit group variables
   vim group_vars/netbox.yml
   
   # Encrypt sensitive variables
   ansible-vault encrypt group_vars/netbox/vault.yml
   

3. Deploy NetBox

   # 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:

# 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:

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

ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml

Update NetBox

ansible-playbook -i inventory/hosts.yml playbooks/update-netbox.yml

Backup NetBox

ansible-playbook -i inventory/hosts.yml playbooks/backup-netbox.yml

Run with Vault

ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --ask-vault-pass

Run Specific Tags

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

# 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