From f68a8289d4e6a247bce4307693e94b3c1c572366 Mon Sep 17 00:00:00 2001
From: rezayaghobi-dev <rezay5639@gmail.com>
Date: Sun, 16 Aug 2026 23:58:39 +0330
Subject: [PATCH]  updated the main readme and added vagrant

---
 README.md            | 16 ++++++++++++----
 vagrant/README.md    | 34 ++++++++++++++++++++++++++++++++++
 vagrant/Vagrantfile  | 16 ++++++++++++++++
 vagrant/bootstrap.sh |  5 +++++
 4 files changed, 67 insertions(+), 4 deletions(-)
 create mode 100644 vagrant/README.md
 create mode 100644 vagrant/Vagrantfile
 create mode 100644 vagrant/bootstrap.sh

diff --git a/README.md b/README.md
index 624ae78..09a9a61 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,10 @@ A self-hosted homelab running on Docker Compose, built and maintained on an Ubun
 ![Prometheus](https://img.shields.io/badge/Prometheus-E6522C?style=flat&logo=prometheus&logoColor=white)
 ![Grafana](https://img.shields.io/badge/Grafana-F46800?style=flat&logo=grafana&logoColor=white)
 ![Loki](https://img.shields.io/badge/Loki-F5A623?style=flat&logo=grafana&logoColor=white)
-![Kubernetes](https://img.shields.io/badge/K3s-326CE5?style=flat&logo=kubernetes&logoColor=white)
+![Kubernetes](https://img.shields.io/badge/Kubernetes-326CE5?style=flat&logo=kubernetes&logoColor=white)
+![K3s](https://img.shields.io/badge/K3s-FFC61C?style=flat&logo=k3s&logoColor=white)
+![Vagrant](https://img.shields.io/badge/Vagrant-1868F2?style=flat&logo=vagrant&logoColor=white)
+![GitLab](https://img.shields.io/badge/GitLab-FC6D26?style=flat&logo=gitlab&logoColor=white)
 
 ## Overview
 
@@ -47,6 +50,7 @@ Not everything in this repo runs permanently. Some folders are kept purely as re
 | Lab | Folder | Purpose |
 |---|---|---|
 | **Elastic Stack (ELK)** | `docker-compose/elk/` | Elasticsearch + Kibana, security-enabled, sized for this hardware — a modern-workflow (Elastic Agent/Fleet) alternative to an older Filebeat/Metricbeat-based course reference. Not run continuously since Loki now covers centralized logging here — see [Elastic Stack (ELK)](docs/ElasticStack.md) |
+| **Vagrant test VM** | `docker-compose/vagrant/` | Disposable Debian 12 VirtualBox VM (`bento/debian-12`) on a private-network IP, for testing provisioning scripts and configuration changes before touching the real host |
 
 ## Repository structure
 
@@ -111,9 +115,13 @@ homelab/
 │   │   │           └── Dockerfile
 │   │   └── backups/
 │   │       └── gitlab-backup.sh
-│   └── elk/
-│       ├── docker-compose.yml
-│       └── .env.example
+│   ├── elk/
+│   │   ├── docker-compose.yml
+│   │   └── .env.example
+│   └── vagrant/
+│       ├── Vagrantfile
+│       ├── bootstrap.sh
+│       └── README.md
 ├── ansible/
 │   └── playbooks/
 │       ├── roles/
diff --git a/vagrant/README.md b/vagrant/README.md
new file mode 100644
index 0000000..9588c50
--- /dev/null
+++ b/vagrant/README.md
@@ -0,0 +1,34 @@
+# Vagrant Test VM
+
+A disposable VirtualBox VM for trying out provisioning scripts and configuration changes before running them against the real host — mistakes here cost a `vagrant destroy`, not a broken production service.
+
+## What it creates
+
+- **Box:** `bento/debian-12`
+- **Hostname:** `test`
+- **Network:** private network, static IP `192.168.56.10` — reachable from the host but isolated from the rest of the LAN
+- **Resources:** 1 vCPU, 1024 MB RAM — enough to exercise a bootstrap script or a small playbook run, not meant to run real workloads
+
+## Usage
+
+```bash
+vagrant up          # create and provision the VM
+vagrant ssh          # log in
+vagrant provision    # re-run bootstrap.sh against a VM that's already up
+vagrant destroy      # tear it down completely
+```
+
+## `bootstrap.sh`
+
+Runs automatically on `vagrant up` via Vagrant's shell provisioner. Currently:
+
+```bash
+apt-get update
+sudo apt install -y vim iptables-persistent bash-completion
+```
+
+Baseline packages for a usable shell environment — `iptables-persistent` in particular anticipates using this VM to test firewall rule changes without risking the real host's `iptables` state.
+
+## Why this exists
+
+Testing changes directly on the host (or worse, in production containers) means a bad `iptables` rule or a broken package install has real consequences. This VM gives a throwaway Debian environment matching the host's OS family, so provisioning changes — Ansible playbook edits, install scripts, firewall rules — get a dry run first. `vagrant destroy && vagrant up` resets to a clean slate in a couple of minutes.
diff --git a/vagrant/Vagrantfile b/vagrant/Vagrantfile
new file mode 100644
index 0000000..af303d0
--- /dev/null
+++ b/vagrant/Vagrantfile
@@ -0,0 +1,16 @@
+IMAGE_Debian_12 = "bento/debian-12"
+
+Vagrant.configure("2") do |config|
+  config.vm.box = IMAGE_Debian_12
+  config.vm.box_check_update = false
+
+  config.vm.hostname = "test"
+
+  config.vm.network "private_network", ip: "192.168.56.10"
+
+  config.vm.provider "virtualbox" do |vb|
+    vb.name = "my_vm"
+    vb.memory = 1024
+    vb.cpus = 1
+  end
+end
diff --git a/vagrant/bootstrap.sh b/vagrant/bootstrap.sh
new file mode 100644
index 0000000..a012061
--- /dev/null
+++ b/vagrant/bootstrap.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+# update and upgrade os
+apt-get update
+sudo apt install -y vim iptables-persistent bash-completion
+#apt-get upgrade -y
\ No newline at end of file