Home

Welcome to the gd-tools documentation.

This wiki is the primary source of documentation for gd-tools — a pragmatic Go toolchain for building, provisioning, and operating self-hosted infrastructure.

If you are new to gd-tools, this is where to begin.

---

Why the name “gd-tools”?

The name gd-tools is short for Go Deployment Tools — as you probably guessed.

The abbreviation is intentional. gd-tools is meant to be concise, direct, and practical, much like the toolchain itself. It does not try to brand a grand framework or a platform, but a focused set of tools built in Go for deploying and operating systems in a controlled way.

As a practical side effect, the command name gdt is currently unused on a standard Ubuntu system. This makes it short, unambiguous, and easy to type — without colliding with existing system tools.

If the name feels slightly understated, that is by design.

---

Platform scope

At the moment, gd-tools targets production systems are based on the Debian / Ubuntu ecosystem.

On the production host, gd-tools assumes:

• apt / apt-get for package management
• Debian-style filesystem layout and conventions
• systemd as the service manager

Other Linux distributions (such as Red Hat, Fedora, SUSE, or Alpine) are not currently supported on the production side.

---

Development workstation

The development workstation is less constrained.

gdt can be used on:

• Linux
• macOS
• Windows (via WSL2)

All modeling, configuration, and decision-making happens on the development workstation. Platform-specific assumptions apply primarily to the production agent.

---

Start here

With the groundwork out of the way, this is where to start:

• Installation & Bootstrap
  Install gd-tools on your development workstation and understand the basic bootstrap model.

• Your first production server
  How to start provisioning a real server.

• Typical Workflow
  The typical lifecycle from setup to deployment.

• Regular Maintenance
  The regular care and feeding of your infrastructure.

These four chapters form the essential reading to get started with gd-tools. The remaining documentation provides additional background and is primarily relevant for a deeper understanding of the concepts and design decisions behind the toolchain.

---

Further reading

For deeper insight into the rationale and design philosophy behind gd-tools, the following pages provide additional context:

• Design Goals The guiding principles behind gd-tools and the trade-offs it makes.

• Non-Goals What gd-tools explicitly does not try to solve.

• Core Concepts Key ideas such as Dev vs Prod, generated artifacts, and idempotency.

These pages are not required to get started, but they explain why gd-tools works the way it does.

---

Reference environment

gd-tools is opinionated and optimized around a well-defined reference setup:

• Reference Environment: Hetzner
  Assumptions and integrations based on Hetzner Cloud Servers, with Hetzner Volumes as scalable on-line storage, Cloud DNS API, and Storage Box backups.

Other environments can be supported, but Hetzner serves as the primary baseline.

---

If something feels unclear or incomplete, that usually means the documentation needs improvement — not that you missed something.