{"id":41773812,"url":"https://github.com/xnok/infra-bootstrap-tools","last_synced_at":"2026-04-20T22:01:04.712Z","repository":{"id":41897635,"uuid":"332002151","full_name":"xNok/infra-bootstrap-tools","owner":"xNok","description":"IaC configurations to bootstrap and manage a small self-hosted project or homelab","archived":false,"fork":false,"pushed_at":"2026-04-19T23:45:38.000Z","size":17574,"stargazers_count":46,"open_issues_count":3,"forks_count":20,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-20T01:20:09.571Z","etag":null,"topics":["ansible","devops","docker","docker-swarm","github","github-actions","learning-by-doing","terraform","vagrant"],"latest_commit_sha":null,"homepage":"https://xnok.github.io/infra-bootstrap-tools/","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/xNok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2021-01-22T16:31:32.000Z","updated_at":"2026-04-19T15:30:59.000Z","dependencies_parsed_at":"2023-11-12T16:25:08.180Z","dependency_job_id":"392c2106-881b-4fd1-b643-00d0f022b3f6","html_url":"https://github.com/xNok/infra-bootstrap-tools","commit_stats":null,"previous_names":[],"tags_count":46,"template":true,"template_full_name":null,"purl":"pkg:github/xNok/infra-bootstrap-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xNok%2Finfra-bootstrap-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xNok%2Finfra-bootstrap-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xNok%2Finfra-bootstrap-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xNok%2Finfra-bootstrap-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xNok","download_url":"https://codeload.github.com/xNok/infra-bootstrap-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xNok%2Finfra-bootstrap-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32067626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T21:26:33.338Z","status":"ssl_error","status_checked_at":"2026-04-20T21:26:22.081Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ansible","devops","docker","docker-swarm","github","github-actions","learning-by-doing","terraform","vagrant"],"created_at":"2026-01-25T03:19:27.727Z","updated_at":"2026-04-20T22:01:04.667Z","avatar_url":"https://github.com/xNok.png","language":"Shell","readme":"# Startup Infra for Small Self-hosted Projects\n\n![Ansible](https://img.shields.io/badge/ansible-%231A1918.svg?style=for-the-badge\u0026logo=ansible\u0026logoColor=white) ![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge\u0026logo=githubactions\u0026logoColor=white) ![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge\u0026logo=docker\u0026logoColor=white) ![Vagrant](https://img.shields.io/badge/vagrant-%231563FF.svg?style=for-the-badge\u0026logo=vagrant\u0026logoColor=white) ![Terraform](https://img.shields.io/badge/terraform-%235835CC.svg?style=for-the-badge\u0026logo=terraform\u0026logoColor=white)\n\nThis repository provides Ansible playbooks to set up a minimal infrastructure for a simple self-hosted application. Ideal for small hobby projects. I made this repository a place to **Learn** about DevOps and Cloud Infrastructure. You have all the tutorial you need to get started.\n\n\n## Development Environment Setup\n\n\nThis project provides a convenient dispatcher command, `ibt`, to help you set up your local development environment and manage project tools. Additionally, a Gitpod configuration is available for a cloud-based, ready-to-use environment.\n\n### Unified Tools Bash script: `ibt`\n\nThe `ibt` command (Infra Bootstrap Tools) is a shell function that provides a unified interface to the main project scripts with subcommands and auto-completion support.\n\n**Subcommands:**\n\n- `ibt setup [tool ...]` \u0026mdash; Install required tools and dependencies (see below)\n- `ibt stacks [args ...]` \u0026mdash; Manage and run infrastructure stacks\n- `ibt tools [args ...]` \u0026mdash; Use Docker-based aliases for Ansible, AWS CLI, etc.\n\n**Auto-completion:**\n\nTab-completion is available for subcommands and for the `setup` tool list (e.g., `ibt setup [TAB]`).\n\n**To enable `ibt` in your shell:**\n\n```bash\nsource ./bin/bash/ibt.sh\n```\n\nYou can add this line to your `~/.bashrc` or `~/.bash_profile` for persistence.\n\n**Example usage:**\n\n```bash\n# Install pre-commit and Ansible\nibt setup pre-commit ansible\n\n# List available stacks\nibt stacks list\n\n# Use Docker-based Ansible\nibt tools dasb --version\n```\n\n\n### Nix Shell\n\n**Prerequisites:** This requires [Nix](https://nixos.org/download.html) to be installed on your system.\n\nFor a fully automated and reproducible development environment using Nix, you have two options:\n\n#### Option 1: Using Traditional Nix Shell (Most Compatible)\n\nUse this option if `nix develop` fails with `experimental Nix feature 'nix-command' is disabled`.\n\n```bash\nnix-shell bin/nix/shell.nix\n\n# Or select a specific shell\nnix-shell bin/nix/shell.nix --argstr shell flux\n```\n\nShell overview:\n- `default`: general development shell with Python, Docker, Git, and pre-commit\n- `ansible`: adds Ansible tooling and installs Galaxy dependencies\n- `flux`: adds `jq`, `kubectl`, `helm`, `kind`, and `flux` for Kubernetes/Flux work\n- `docs`: adds Hugo and Go for website/documentation work\n- `full`: includes everything when you need the broadest environment\n\nThe shells are ready to use after their hooks complete. Python-based shells create and activate a local virtual environment (`.venv`) to avoid conflicts with the Nix-provided Python.\n\n#### Option 2: Using Nix Flakes (Optional)\n\nNix Flakes provide a more modern and reproducible approach, but require the `nix-command` and `flakes` experimental features:\n\n```bash\n# Enable flakes if not already enabled (add to ~/.config/nix/nix.conf or /etc/nix/nix.conf):\n# experimental-features = nix-command flakes\n\n# Enter the default general-purpose development environment\nnix develop\n```\n\nTask-focused shells are also available:\n\n```bash\n# Infrastructure / Ansible work\nnix develop .#ansible\n\n# Flux / Kind / Kubernetes work\nnix develop .#flux\n\n# Website / Hugo work\nnix develop .#docs\n\n# Full kitchen-sink environment\nnix develop .#full\n```\n\n### GitHub Codespaces\n\nThe repository includes a `.devcontainer/devcontainer.json` that keeps the current base image (`mcr.microsoft.com/devcontainers/base:ubuntu-24.04`), installs Nix by default, and enables flakes (`nix-command flakes`) out of the box. Docker access is enabled as well.\n\nYou can use:\n\n```bash\nnix develop\nnix develop .#ansible\nnix develop .#flux\n```\n\nIf you are in a different environment where flakes are not enabled, use:\n\n```bash\nnix-shell bin/nix/shell.nix\n```\n\n\n### Gitpod\n\nAlternatively, you can use Gitpod to get a pre-configured development environment in your browser. Click the button below to get started:\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/from-referrer/)\n\n## 🚀 Quick Start\n\nGot your [prerequisites](./website/content/en/docs/gs1.getting_started.md#prerequisites) and [secrets configured](./website/content/en/docs/gs1.getting_started.md#configuration-secrets-management)?\n\nDeploy your entire infrastructure with a single command:\n\n```bash\nmake up\n```\n\nThis command will:\n*   Provision infrastructure on DigitalOcean using Terraform.\n*   Install Docker on all hosts.\n*   Initialize a Docker Swarm cluster.\n*   Deploy Caddy and Portainer applications.\n\nTo tear down the infrastructure:\n\n```bash\nmake down\n```\n\nFor a detailed step-by-step guide, including prerequisites and secret management options, please refer to our **[Full Getting Started Guide](./website/content/en/docs/gs1.getting_started.md)**.\n\nTo understand the underlying Ansible concepts, check out **[Understanding Ansible Concepts](./website/content/en/docs/b1.ansible_concepts.md)**.\n\n## Articles and Tutorials\n\nThe articles/tutorials are divided into sections. \n* **Introduction** -\u003e What are the tools to manage infrastructure? Perfect to learn the basis.\n* **How-tos** -\u003e Good takeaway from this project - Answers many questions you could encounter in the future\n* **Deepening Understanding** -\u003e Learn more about each application used in this setup (Portainer, Graphana, Caddy, etc.)\n* **Local Experimentation \u0026 Advanced Topics**: Deeper dives into specific setups and components.\n\nI used [DigitalOcean](https://digitalocean.pxf.io/q4b2qO) for experiments because it is cheap, but any cloud provider should work, as we are mainly playing with Virtual Machines. You can even get [$200 DigitalOcean free credit](https://digitalocean.pxf.io/q4b2qO) when starting \n* Don't forget to delete everything after a tutorial if you don't want to add unnecessary costs\n\n### Tools Introduction\n\n* [ ] WIP: 📚 1: [What is **Terraform** and why you might need it.]()\n* [X] 📚 2: [What is **Terraform Cloud** and why you might need it.](https://faun.pub/what-is-terraform-cloud-and-why-you-might-need-it-c9847fb8f6e6?sk=ee85423512f39030bb287a3f2a6623d3)\n* [ ] WIP: 📚 3: [What is **Github Action** and why you might need it.]()\n* [ ] WIP: 📚 4: [What is **Ansible** and why you might need it.]()\n* [ ] WIP: 📚 5: [What is **Ansible AWX** and why you might need it.]()\n\n### Learn the Tools\n\n* [X] 🌍 [How to configure GitHub Environments with Terraform?](https://faun.pub/how-to-configure-github-environments-with-terraform-d2b76766547b?sk=b50616eed7da268d5a99c459fc9c57d5)\n* [x] 🏭 [How to provision VM on Digital Ocean with Terraform?](https://faun.pub/how-to-provision-vms-on-digitalocean-with-terraform-898515a0dbbc?sk=7af174d77b4a7bd81e581378beac9a0d)\n* [X] 🔏 [How to create SSH keys with Terraform?](https://faun.pub/how-to-create-ssh-keys-with-terraform-a615dfc631c1?sk=176a8f5c0c0517a01e8fabd5bb7c18fa)\n* [x] 🗺️ [How to create Ansible Inventory with Terraform?](https://faun.pub/how-to-create-ansible-inventory-with-terraform-a32fcbe11be6?sk=da18fba15ee996e4c3b92782229654ee)\n* [x] 👩 [How to run an Ansible playbook using GitHub Action?](https://faun.pub/how-to-run-an-ansible-playbook-using-github-action-42430dec944?sk=7796e8bd44f6b8c394b80507b8ff3e87)\n\n### Local Experimentation \u0026 Advanced Topics\n\nThese articles cover setting up local test environments and exploring specific components in more detail. They are excellent for understanding the individual parts before or alongside deploying the full cloud infrastructure.\n\n* [X] 🧰 1: [Design and Test Ansible playbook with Vagrant](https://faun.pub/a-disposable-local-test-environment-is-essential-for-devops-sysadmin-af97fa8f3db0?sk=f2f0e3a6b4fe4215cec13019887b6302)\n   * Example code [.articles/1_vagrant_101](.articles/1_vagrant_101)   \n* [X] 🧰 2 [Experimenting on Docker Swarm with Vagrant and Ansible](https://faun.pub/experimenting-on-docker-swarm-with-vagrant-and-ansible-bcc2c79ba7c4?sk=1eac227cf3c9ec5dc5abbf06f38e92c3)\n   * Example code [.articles/2_docker_swarm_101](.articles/2_docker_swarm_101)\n* [ ] WIP: 🧰 3: [Automate Infrastructure provisioning with Ansible and Github action]() (This might be more of an advanced topic now, focusing on CI/CD aspects beyond the basic `make up`)\n\n\n### Learn about the applications used in this setup\n\n* [ ] WIP: ☸️ 1: [What is Portainer and why you might need it.]() (Covered by [Portainer Management UI](./website/content/en/docs/a2.portainer.md))\n* [ ] WIP: ☸️ 2: [What is Prometheus and why you might need it.]()\n* [ ] WIP: ☸️ 3: [What is Caddy and why you might need it.]() (Covered by [Caddy Web Server](./website/content/en/docs/a1.caddy.md))\n\n### Deep Dives\n\nBelow, I've included some explainers on how I solved a specific problem when I encountered it. This should demistify some of the magic happening in this repo.\n\n#### Ansible\n\n* [x] 🏃‍♂️ 1: [Speedup Ansible Playbook Pull-Requests by only running affected roles](https://medium.com/itnext/speedup-ansible-playbook-merge-request-by-only-running-affected-roles-42d9ca3f6433?sk=382b8de777e41deb20f7fefe430b2f26)\n* [x] 🏃‍♂️ 2: [How to rotate Docker Secrets with Ansible](https://medium.com/itnext/rotating-docker-swarm-secrets-with-ansible-cbaddfdd8ee9?sk=886dae52f1570c251a6a664d5ee2c5fe)\n* [x] 🏃‍♂️ 3: [How to implement Pull-Request locking for Ansible](https://medium.com/itnext/safe-infrastructure-as-code-github-actions-workflow-with-a-pr-lock-27bef636f852?sk=a6615ca085348aa2543a68f9c7a41077)\n\n## Ansible Collection\n\nThis repository is also available as an Ansible Collection on Ansible Galaxy, allowing you to easily reuse the roles in your own Ansible projects.\n\n**Collection Name:** `xnok.infra_bootstrap_tools`\n\n### Installation\n\nTo install this collection from Ansible Galaxy, use the following command:\n\n```bash\nansible-galaxy collection install xnok.infra_bootstrap_tools\n```\n\n### Usage\n\nOnce installed, you can use the roles from this collection in your playbooks. For example, to use the `docker` role:\n\n```yaml\n- hosts: all\n  become: yes\n  roles:\n    - role: xnok.infra_bootstrap_tools.docker\n      # Optional: specify variables for the role\n      # docker_users:\n      #   - your_username\n```\n\nRefer to the `README.md` file within each role's directory (`ansible/roles/[role_name]/README.md`) for detailed information on specific roles, their variables, and dependencies.\n\nYou can find the collection on Ansible Galaxy: [xnok.infra_bootstrap_tools](https://galaxy.ansible.com/xnok/infra_bootstrap_tools)\n\n## Release Management\n\nThis monorepo uses [Changesets](https://github.com/changesets/changesets) for automated version management and releases. Different package types (Ansible collection, Python package, Docker stacks) are automatically published when versions are bumped.\n\nFor detailed information about the release process, see **[RELEASE.md](./RELEASE.md)**.\n\n### Quick Start\n\nTo create a changeset for your changes:\n```bash\nnpx changeset add\n```\n\nFor more details on package types, publishing workflows, and troubleshooting, see the [full release documentation](./RELEASE.md).\n\n## Architecture\n\n![](./diagrams/startup_infra_for_small_self_hosted_project.png)\n\n## Handy toolchain\n\nDo you want to go fast? Too lazy to set up your local environment?\n\nThen, use the tools from a Docker container. I included a simple Toochain in this repository and a useful alias for it.\n\nUse common infrastructure tools in docker with:\n* [docker_tools_alias.sh](bin/bash/docker_tools_alias.sh)\n\n```\nsource ./bin/docker_tools_alias.sh\n```\n\n```\nuse dasb for ansible in docker\nuse dap for ansible-playbook in docker\nuse daws for awscli in docker\nuse dpk for packer in docker\nuse dtf for terraform in docker\nuse dbash for bash in docker\n```\n\n## Tools Showcase\n\nThis project leverages several tools to streamline development and improve code quality. Here's a brief overview of some of them:\n\n*   **Pre-commit**: We use pre-commit hooks to automate linting, formatting, and other checks before code is committed. This helps maintain code consistency and catch errors early. Configuration can be found in `.pre-commit-config.yaml`.\n*   **1Password CLI**: For securely managing sensitive information like API keys and passwords, the 1Password CLI can be integrated into your workflow. The setup script provides an option to install it.\n*   **Boilerplate**: [Gruntwork Boilerplate](https://github.com/gruntwork-io/boilerplate) is used to generate répétitive code structures, ensuring consistency and saving time. You can find boilerplate templates in the `.boilerplates` directory.\n*   **Hugo**: The project documentation website (what you're likely reading if you're on the website!) is built using [Hugo](https://gohugo.io/), a fast and flexible static site generator. The website content is in the `website/` directory.\n\n## Scale Up\n\nWith docker swarm and portainer it because easy to manager multiple nodes.\n\n![](./diagrams/scaled_up_infra_for_small_self_hosted_project.png)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxnok%2Finfra-bootstrap-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxnok%2Finfra-bootstrap-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxnok%2Finfra-bootstrap-tools/lists"}