{"id":40933386,"url":"https://github.com/xooooooooox/radp-vagrant-framework","last_synced_at":"2026-02-12T14:20:39.150Z","repository":{"id":333173471,"uuid":"1136400937","full_name":"xooooooooox/radp-vagrant-framework","owner":"xooooooooox","description":"A YAML-driven framework for managing multi-machine Vagrant environments with configuration inheritance and modular provisioning.","archived":false,"fork":false,"pushed_at":"2026-02-05T19:41:17.000Z","size":724,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T03:41:08.976Z","etag":null,"topics":["homelab","ruby","vagrant","virtualbox","virtualization","vmware"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xooooooooox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-17T16:17:28.000Z","updated_at":"2026-02-05T19:41:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xooooooooox/radp-vagrant-framework","commit_stats":null,"previous_names":["xooooooooox/radp-vagrant-framework"],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/xooooooooox/radp-vagrant-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xooooooooox%2Fradp-vagrant-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xooooooooox%2Fradp-vagrant-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xooooooooox%2Fradp-vagrant-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xooooooooox%2Fradp-vagrant-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xooooooooox","download_url":"https://codeload.github.com/xooooooooox/radp-vagrant-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xooooooooox%2Fradp-vagrant-framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29271901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T13:47:44.167Z","status":"ssl_error","status_checked_at":"2026-02-09T13:47:43.721Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["homelab","ruby","vagrant","virtualbox","virtualization","vmware"],"created_at":"2026-01-22T04:13:02.354Z","updated_at":"2026-02-09T16:08:40.516Z","avatar_url":"https://github.com/xooooooooox.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RADP Vagrant Framework\n\n```\n    ____  ___    ____  ____     _    _____   __________  ___    _   ________\n   / __ \\/   |  / __ \\/ __ \\   | |  / /   | / ____/ __ \\/   |  / | / /_  __/\n  / /_/ / /| | / / / / /_/ /   | | / / /| |/ / __/ /_/ / /| | /  |/ / / /\n / _, _/ ___ |/ /_/ / ____/    | |/ / ___ / /_/ / _, _/ ___ |/ /|  / / /\n/_/ |_/_/  |_/_____/_/         |___/_/  |_\\____/_/ |_/_/  |_/_/ |_/ /_/\n\n```\n\n[![GitHub Release](https://img.shields.io/github/v/release/xooooooooox/radp-vagrant-framework?label=Release)](https://github.com/xooooooooox/radp-vagrant-framework/releases)\n[![Copr build status](https://copr.fedorainfracloud.org/coprs/xooooooooox/radp/package/radp-vagrant-framework/status_image/last_build.png)](https://copr.fedorainfracloud.org/coprs/xooooooooox/radp/package/radp-vagrant-framework/)\n[![OBS package build status](https://build.opensuse.org/projects/home:xooooooooox:radp/packages/radp-vagrant-framework/badge.svg)](https://build.opensuse.org/package/show/home:xooooooooox:radp/radp-vagrant-framework)\n\n[![CI: Check](https://img.shields.io/github/actions/workflow/status/xooooooooox/radp-vagrant-framework/ci.yml?label=CI)](https://github.com/xooooooooox/radp-vagrant-framework/actions/workflows/ci.yml)\n[![CI: COPR](https://img.shields.io/github/actions/workflow/status/xooooooooox/radp-vagrant-framework/build-copr-package.yml?label=CI%3A%20COPR)](https://github.com/xooooooooox/radp-vagrant-framework/actions/workflows/build-copr-package.yml)\n[![CI: OBS](https://img.shields.io/github/actions/workflow/status/xooooooooox/radp-vagrant-framework/build-obs-package.yml?label=CI%3A%20OBS)](https://github.com/xooooooooox/radp-vagrant-framework/actions/workflows/build-obs-package.yml)\n[![CI: Homebrew](https://img.shields.io/github/actions/workflow/status/xooooooooox/radp-vagrant-framework/update-homebrew-tap.yml?label=Homebrew%20tap)](https://github.com/xooooooooox/radp-vagrant-framework/actions/workflows/update-homebrew-tap.yml)\n\n[![COPR packages](https://img.shields.io/badge/COPR-packages-4b8bbe)](https://download.copr.fedorainfracloud.org/results/xooooooooox/radp/)\n[![OBS packages](https://img.shields.io/badge/OBS-packages-4b8bbe)](https://software.opensuse.org//download.html?project=home%3Axooooooooox%3Aradp\u0026package=radp-vagrant-framework)\n\nA YAML-driven framework for managing multi-machine Vagrant environments with configuration inheritance and modular\nprovisioning.\n\n## Features\n\n- **Declarative YAML Configuration** - Define VMs, networks, provisions, and triggers in YAML\n- **Multi-File Configuration** - Base config + environment-specific overrides (`vagrant.yaml` or `config.yaml` +\n  `{base}-{env}.yaml`)\n- **Configuration Inheritance** - Global → Cluster → Guest with automatic merging\n- **Run Anywhere** - No need to `cd` to Vagrantfile directory; run commands from anywhere with `-c` flag\n- **Template System** - Initialize projects from predefined templates (`base`, `single-node`, `k8s-cluster`)\n- **Builtin Provisions \u0026 Triggers** - Reusable components with `radp:` prefix\n- **Plugin Support** - vagrant-hostmanager, vagrant-vbguest, vagrant-proxyconf, vagrant-bindfs\n- **Convention-Based Defaults** - Automatic hostname, provider name, and group-id generation\n- **Debug Support** - Dump merged config, generate standalone Vagrantfile for inspection\n\n## Prerequisites\n\n- Ruby 2.7+\n- Vagrant 2.0+\n- VirtualBox (or other supported provider)\n- [radp-bash-framework](https://github.com/xooooooooox/radp-bash-framework) (required, installed automatically via\n  Homebrew/package managers)\n\n## Installation\n\n### Homebrew (Recommended)\n\n```shell\nbrew tap xooooooooox/radp\nbrew install radp-vagrant-framework\n```\n\n### Script (curl)\n\n```shell\ncurl -fsSL https://raw.githubusercontent.com/xooooooooox/radp-vagrant-framework/main/install.sh\n| bash\n```\n\nInstall from a specific branch or tag:\n\n```shell\nbash install.sh --ref main\nbash install.sh --ref v1.0.0-rc1\n```\n\n### Portable Binary\n\nDownload a self-contained portable binary\nfrom [GitHub Releases](https://github.com/xooooooooox/radp-vagrant-framework/releases):\n\n```shell\n# macOS Apple Silicon\ncurl -fsSL https://github.com/xooooooooox/radp-vagrant-framework/releases/latest/download/radp-vf-portable-darwin-arm64 -o radp-vf\nchmod +x radp-vf\n./radp-vf --help\n\n# Linux x86_64\ncurl -fsSL https://github.com/xooooooooox/radp-vagrant-framework/releases/latest/download/radp-vf-portable-linux-amd64 -o radp-vf\nchmod +x radp-vf\n./radp-vf --help\n```\n\n\u003e **Note**: Portable binary requires [radp-bash-framework](https://github.com/xooooooooox/radp-bash-framework) to be\n\u003e installed.\n\nSee [Installation Guide](docs/installation.md) for more options (manual install, upgrade, shell completion).\n\n### Recommended: Use homelabctl\n\nFor a more feature-rich CLI experience, consider [homelabctl](https://github.com/xooooooooox/homelabctl):\n\n```shell\nbrew tap xooooooooox/radp\nbrew install homelabctl\n\nhomelabctl vf init myproject\nhomelabctl vg status\n```\n\n## Quick Start\n\n### 1. Initialize a Project\n\n```shell\n# Default template\nradp-vf init myproject\n\n# With specific template\nradp-vf init myproject --template k8s-cluster\n\n# With variables\nradp-vf init myproject --template k8s-cluster \\\n  --set cluster_name=homelab \\\n  --set worker_count=3\n```\n\n### 2. Configure Your VMs\n\n```yaml\n# config/vagrant.yaml\nradp:\n  env: dev\n  extend:\n    vagrant:\n      config:\n        common:\n          box:\n            name: generic/ubuntu2204\n```\n\n```yaml\n# config/vagrant-dev.yaml\nradp:\n  extend:\n    vagrant:\n      config:\n        clusters:\n          - name: my-cluster\n            guests:\n              - id: node-1\n                provider:\n                  mem: 2048\n                  cpus: 2\n```\n\n### 3. Run Vagrant Commands\n\nUnlike standard Vagrant which requires `cd` to the Vagrantfile directory, radp-vf can run from anywhere:\n\n```shell\n# From project directory\ncd myproject\nradp-vf vg status\nradp-vf vg up\n\n# Or run from anywhere with -c option\nradp-vf vg -c ~/myproject/config status\nradp-vf vg -c ~/myproject/config up\n\n# Or set environment variable\nexport RADP_VAGRANT_CONFIG_DIR=\"$HOME/myproject/config\"\nradp-vf vg status\nradp-vf vg ssh dev-my-cluster-node-1\nradp-vf vg halt\nradp-vf vg destroy\n```\n\n### 4. Target VMs by Cluster\n\nInstead of typing full machine names, use `--cluster` (`-C`) to target VMs by cluster:\n\n```shell\n# Start all VMs in a cluster\nradp-vf vg up -C gitlab-runner\n\n# Start specific guests in a cluster\nradp-vf vg up -C gitlab-runner -G 1,2\n\n# Multiple clusters\nradp-vf vg up -C gitlab-runner,develop-centos9\n\n# Original syntax still works\nradp-vf vg up homelab-gitlab-runner-1\n```\n\nShell completion is supported for cluster names, guest IDs, and machine names:\n\n```bash\n# Complete cluster names\nradp-vf vg -c /path/to/config --cluster \u003ctab\u003e\n\n# Complete guest IDs (requires --cluster)\nradp-vf vg -c /path/to/config --cluster develop --guest-ids \u003ctab\u003e\n\n# Complete machine names (positional args)\nradp-vf vg -c /path/to/config status \u003ctab\u003e\n```\n\nConfig resolution for completion (in order):\n\n1. `-c` / `--config` from command line\n2. `RADP_VAGRANT_CONFIG_DIR` environment variable\n3. `./config` directory (if exists)\n\n## Commands\n\n| Command         | Description                             |\n|-----------------|-----------------------------------------|\n| `init [dir]`    | Initialize a project from template      |\n| `vg \u003ccmd\u003e`      | Run vagrant commands                    |\n| `list`          | List clusters and guests                |\n| `info`          | Show environment information            |\n| `validate`      | Validate YAML configuration             |\n| `dump-config`   | Export merged configuration (JSON/YAML) |\n| `generate`      | Generate standalone Vagrantfile         |\n| `template list` | List available templates                |\n| `template show` | Show template details                   |\n\n### Option Placement\n\n```\nradp-vf [framework-options] \u003ccommand\u003e [command-options] [arguments]\n```\n\n**Framework options** (before command):\n\n| Option       | Description            |\n|--------------|------------------------|\n| `-v`         | Enable verbose logging |\n| `--debug`    | Enable debug logging   |\n| `-h, --help` | Show help              |\n| `--version`  | Show version           |\n\n**Command options** (after command, before arguments):\n\n| Option               | Description                                   |\n|----------------------|-----------------------------------------------|\n| `-c, --config \u003cdir\u003e` | Configuration directory (default: `./config`) |\n| `-e, --env \u003cname\u003e`   | Override environment name                     |\n| `-h, --help`         | Show help for command                         |\n\n**`vg` command specific options:**\n\n| Option                  | Description                                       |\n|-------------------------|---------------------------------------------------|\n| `-C, --cluster \u003cnames\u003e` | Cluster names (comma-separated for multiple)      |\n| `-G, --guest-ids \u003cids\u003e` | Guest IDs (comma-separated, requires `--cluster`) |\n\n**Examples:**\n\n```shell\n# Framework option before command\nradp-vf -v list\n\n# Command options after command name\nradp-vf list -c ./config -e prod\nradp-vf vg -c ./config status\nradp-vf dump-config -f yaml -o config.yaml\n\n# Target VMs by cluster (vg command)\nradp-vf vg status -C my-cluster\nradp-vf vg up -C gitlab-runner -G 1,2\nradp-vf vg halt -C cluster1,cluster2\n```\n\n### Environment Variables\n\n| Variable                            | Description                                              |\n|-------------------------------------|----------------------------------------------------------|\n| `RADP_VF_HOME`                      | Framework installation directory                         |\n| `RADP_VAGRANT_CONFIG_DIR`           | Configuration directory path                             |\n| `RADP_VAGRANT_ENV`                  | Override environment name                                |\n| `RADP_VAGRANT_CONFIG_BASE_FILENAME` | Override base config filename (supports any custom name) |\n\n## Configuration Overview\n\n### Multi-File Loading\n\nBase configuration file is auto-detected (or set via `RADP_VAGRANT_CONFIG_BASE_FILENAME`):\n\n1. `vagrant.yaml` or `config.yaml` - Base configuration (must contain `radp.env`)\n2. `{base}-{env}.yaml` - Environment-specific clusters (e.g., `vagrant-dev.yaml` or `config-dev.yaml`)\n\n### Inheritance Hierarchy\n\nSettings inherit: **Global common → Cluster common → Guest**\n\n| Config                   | Merge Behavior                                                               |\n|--------------------------|------------------------------------------------------------------------------|\n| box, provider, network   | Deep merge (guest overrides)                                                 |\n| provisions               | Phase-aware: `global-pre → cluster-pre → guest → cluster-post → global-post` |\n| triggers, synced-folders | Concatenate                                                                  |\n\n### Builtin Provisions\n\n```yaml\nprovisions:\n  - name: radp:nfs/external-nfs-mount\n    enabled: true\n    env:\n      NFS_SERVER: \"nas.example.com\"\n      NFS_ROOT: \"/volume1/nfs\"\n```\n\nAvailable: `radp:crypto/gpg-import`, `radp:crypto/gpg-preset-passphrase`, `radp:git/clone`,\n`radp:nfs/external-nfs-mount`, `radp:ssh/host-trust`, `radp:ssh/cluster-trust`, `radp:time/chrony-sync`,\n`radp:yadm/clone`\n\n### Builtin Triggers\n\n```yaml\ntriggers:\n  - name: radp:system/disable-swap\n    enabled: true\n```\n\nAvailable: `radp:system/disable-swap`, `radp:system/disable-selinux`, `radp:system/disable-firewalld`\n\n### User-Defined Provisions \u0026 Triggers\n\nDefine reusable components with `user:` prefix in your project:\n\n```\nmyproject/\n└── config/\n    ├── provisions/\n    │   ├── definitions/\n    │   │   └── docker/setup.yaml    # -\u003e user:docker/setup\n    │   └── scripts/\n    │       └── docker/setup.sh\n    └── triggers/\n        ├── definitions/\n        │   └── system/cleanup.yaml  # -\u003e user:system/cleanup\n        └── scripts/\n            └── system/cleanup.sh\n```\n\nUsage:\n\n```yaml\nprovisions:\n  - name: user:docker/setup\n    enabled: true\n\ntriggers:\n  - name: user:system/cleanup\n    enabled: true\n```\n\n### User Templates\n\nCreate custom templates in `~/.config/radp-vagrant/templates/`:\n\n```\n~/.config/radp-vagrant/templates/\n└── my-template/\n    ├── template.yaml              # Metadata and variables\n    └── files/                     # Files to copy\n        ├── config/\n        │   ├── vagrant.yaml\n        │   └── vagrant-{{env}}.yaml\n        ├── provisions/\n        └── triggers/\n```\n\nSee [Templates Guide](docs/user-guide/templates.md) for detailed template creation guide.\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md) - Quick start guide\n- [Installation Guide](docs/installation.md) - Full installation options, upgrade, shell completion\n- [Configuration Reference](docs/configuration.md) - Box, provider, network, provisions, triggers, plugins\n- [User Guide](docs/user-guide/) - Provisions, triggers, plugins, templates\n- [Developer Guide](docs/developer/) - Architecture, extending the framework\n- [CLI Reference](docs/reference/cli-reference.md) - Complete CLI command reference\n\n## Related Projects\n\n- [radp-bash-framework](https://github.com/xooooooooox/radp-bash-framework) - Bash engineering \u0026 CLI framework (\n  dependency)\n- [homelabctl](https://github.com/xooooooooox/homelabctl) - Homelab infrastructure CLI (uses this framework)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and release process.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxooooooooox%2Fradp-vagrant-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxooooooooox%2Fradp-vagrant-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxooooooooox%2Fradp-vagrant-framework/lists"}