A modular, extensible Ansible-based solution for setting up Debian/Ubuntu VPS servers.

• Single Configuration File: Edit only config.yml before running
• Modular Roles: Each component is a separate, reusable role
• Flexible Installation: Enable/disable components via flags
• Secure by Default: UFW firewall, SSH hardening, CrowdSec protection
• Modern Stack: Docker, Node.js, Python, PostgreSQL, Redis, Nginx

1. Configure your VPS settings:

   cp config.yml.example config.yml
   # Edit config.yml with your VPS details
   nano config.yml

2. Run the setup:

   ./run.sh setup -k

3. Optional: Install VNC desktop:

   ./run.sh vnc

Edit config.yml to customize your setup. This is the only file you need to edit.

install_common_packages: true
install_nodejs: true
install_nginx: true
install_python: true
install_postgresql: true
install_redis: true
install_docker: true
install_zsh: true
install_crowdsec: true
install_tailscale: true
install_homebrew: true
install_mysql: false  # Set to true if needed

./run.sh setup -k

./run.sh docker    # Install Docker only
./run.sh nginx     # Install Nginx only
./run.sh nodejs    # Install Node.js only

./run.sh vnc

./run.sh backup    # Backup all MySQL and PostgreSQL databases to local machine

# Decompress and restore
gunzip < backup/2026-02-17/mysql_dbname_*.sql.gz | mysql -u root -p dbname

# Or in one command
gunzip < backup/2026-02-17/mysql_dbname_*.sql.gz | mysql -u root -p dbname

# Decompress and restore
gunzip < backup/2026-02-17/postgresql_dbname_*.sql.gz | psql -U postgres dbname

# Or create database first if needed
createdb dbname
gunzip < backup/2026-02-17/postgresql_dbname_*.sql.gz | psql -U postgres dbname

./run.sh check

./run.sh setup -v

ansible/
├── config.yml           # Main configuration (EDIT THIS)
├── run.sh               # Runner script
├── ansible.cfg          # Ansible configuration
├── inventory            # Generated inventory
├── playbooks/
│   ├── setup.yml        # Main setup playbook
│   └── vnc.yml          # VNC installation playbook
└── roles/
    ├── common/
    ├── security/
    ├── user/
    ├── docker/
    ├── nodejs/
    ├── python/
    ├── nginx/
    ├── postgresql/
    ├── redis/
    ├── database/
    ├── zsh/
    ├── crowdsec/
    ├── tailscale/
    └── vnc/

After installing VNC, connect securely via SSH tunnel:

1. Create SSH tunnel from your local machine:

   ssh -L 5901:localhost:5901 user@your-vps -p 22

2. Connect with VNC client to:

   localhost:5901
   

   note: or use tailscale to connect vnc

1. Create role directory:

   mkdir -p roles/newrole/{tasks,handlers,defaults}

2. Create roles/newrole/tasks/main.yml

3. Add to playbooks/setup.yml if needed

4. Add to run.sh command list

• Ansible 2.9+ on your local machine
• Fresh Debian 11+ or Ubuntu 20.04+ VPS
• SSH access to VPS (root or sudo user)

MIT