vm-bootstrap

README

vm-bootstrap

⠤⠤⠤⠤⠤⠤⢤⣄⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠙⠒⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠤⠤⠶⠶⠶⠦⠤⠤⠤⠤⠤⢤⣤⣀⣀⣀⣀⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⢀⠄⢂⣠⣭⣭⣕⠄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠤⠀⠀⠀⠤⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠉⠉⠉⠉⠉⠉⠉
⠀⠀⢀⠜⣳⣾⡿⠛⣿⣿⣿⣦⡠⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠠⣤⣤⣤⣤⣤⣤⣤⣤⣤⣍⣀⣦⠦⠄⣀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠠⣄⣽⣿⠋⠀⡰⢿⣿⣿⣿⣿⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣼⣿⡿⠛⠛⡿⠿⣿⣿⣿⣿⣿⣿⣷⣶⣿⣁⣂⣤⡄⠀⠀⠀⠀⠀⠀
⢳⣶⣼⣿⠃⠀⢀⠧⠤⢜⣿⣿⣿⣿⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣾⠟⠁⠀⠀⠀⡇⠀⣀⡈⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧⡀⠁⠐⠀⣀⠀⠀
⠀⠙⠻⣿⠀⠀⠀⠀⠀⠀⢹⣿⣿⡝⢿⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⡿⠋⠀⠀⠀⠀⠠⠃⠁⠀⠀⠙⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣿⡿⠋⠀⠀
⠀⠀⠀⠙⡄⠀⠀⠀⠀⠀⢸⣿⣿⡃⢼⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣿⣿⣿⡏⠉⠉⠻⣿⡿⠋⠀⠀⠀⠀
⠀⠀⠀⠀⢰⠀⠀⠰⡒⠊⠻⠿⠋⠐⡼⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣿⣿⣿⣿⠀⠀⠀⠀⣿⠇⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠸⣇⡀⠀⠑⢄⠀⠀⠀⡠⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢖⠠⠤⠤⠔⠙⠻⠿⠋⠱⡑⢄⠀⢠⠟⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠈⠉⠒⠒⠻⠶⠛⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠡⢀⡵⠃⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⠦⣀⠀⠀⠀⠀⠀⢀⣤⡟⠉⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠉⠉⠉⠙⠛⠓⠒⠲⠿⢍⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀

bootstrap helper TUI for your shiny new Ubuntu/Debian VPS instances

Install

go install github.com/programat/vm-bootstrap/cmd/vm-bootstrap@latest

Why

vm-bootstrap exists for a very common case: you get a clean Ubuntu or Debian VPS for a hackathon, pet project, demo, or some quick internal task, and you want it ready fast.

Instead of stitching together shell snippets and one-off notes, you open one TUI and configure the base host in one place: common packages, swap, Docker, Compose, optional system update, and a small services compose.yml.

The longer-term plan is to bring app deploys, users, and SSH key setup into the same flow, while keeping the project local-first and small enough to stay useful on plain Ubuntu and Debian hosts.

Quick Start

vm-bootstrap init

Useful CLI helpers when you want them:

vm-bootstrap doctor
vm-bootstrap apply -f ~/.config/vm-bootstrap/manifests/default.yaml --dry-run
vm-bootstrap apply -f ~/.config/vm-bootstrap/manifests/default.yaml
vm-bootstrap apply -f ~/.config/vm-bootstrap/manifests/default.yaml --no-resume
vm-bootstrap status -f ~/.config/vm-bootstrap/manifests/default.yaml

Stages

Status	Stage	What works now	What is next
In progress	Stage 1 core	swap, common packages, Docker Engine, Compose plugin, Buildx plugin, optional system update	polish defaults and keep base bootstrap repeatable
In progress	Stage 2 services	Nginx, optional Nginx UI, Portainer, and a rendered service compose.yml under the managed dir	expand the service layer without adding remote orchestration
Planned	Stage 3 apps	visible in the pipeline, but intentionally disabled in this pass	repo and app deploy flow after core and services settle
Planned	Stage 4 users	visible in the pipeline, but intentionally disabled in this pass	users, SSH keys, access rules, and first-day host setup

TUI Flow

1. Run vm-bootstrap init.
2. Review the landing screen with current host facts, then press Enter to open the init pipeline.
3. Move between the Pipeline, Form, and Summary panes to shape the host setup.
4. Use / to search stages or tags, Tab to switch panes, j/k to move, Space to toggle, Enter to edit or select, and h/l to collapse or expand sections.
5. Save the manifest with Ctrl+S.
6. Use Ctrl+A when you want to save and apply locally right away from the TUI.
7. Use vm-bootstrap status -f <manifest> later to inspect the last grouped run.

vm-bootstrap doctor and vm-bootstrap apply --dry-run -f <manifest> stay useful when you want a plain CLI readiness check or a plan preview.

Considerations of Future Work

Not in the main flow right now. These can return later if they still fit the local-first scope:

• remote upload/sync/apply helpers
• app repo cloning and deploy packs
• SSH hardening and advanced security automation
• AI tool packs and mixed control-plane extras

License

Apache-2.0.

Copyright 2026 programat. See LICENSE and NOTICE.

Reference

Example manifest

apiVersion: vm-bootstrap/v2alpha1
kind: HostBootstrap
metadata:
  name: box-01
spec:
  layout:
    managed_dir: /home/egor/.local/share/vm-bootstrap

  core:
    enabled: true
    system_update:
      enabled: false
    packages:
      enabled: true
      common:
        - ca-certificates
        - curl
        - git
        - gnupg
        - htop
        - jq
        - lsb-release
        - make
        - unzip
    docker:
      enabled: true
      compose_plugin: true
      buildx_plugin: true
    swap:
      enabled: true
      mode: auto
      size_gb: 4
      swappiness: 10

  services:
    enabled: true
    nginx:
      enabled: true
      ui_enabled: false
      publish_http: 80
    portainer:
      enabled: true
      publish_https: 9443
      edge_port: 8000
      public_bind: 0.0.0.0

Notes

• apply is intentionally limited to Linux hosts on Ubuntu/Debian-family distros.
• apply resumes previously completed steps only when the saved state matches the current plan fingerprint; use --no-resume to force a full rerun.
• The current release accepts only apiVersion: vm-bootstrap/v2alpha1.
• Old manifests are rejected with a clear message; regenerate them through init.
• If Stage 2 is enabled while Docker is absent, either enable Docker in Stage 1 or install Docker on the host first.
• Nginx can run either as a plain HTTP-only baseline or as the official nginx-ui container when spec.services.nginx.ui_enabled=true.
• When Nginx UI is enabled, finish the first-run setup at http://<host>:<nginx_http_port>/install.
• Nginx in the current MVP still exposes only HTTP. TLS/443 configuration returns in a later pass.
• Portainer stays directly exposed on its own HTTPS port in this MVP.