Why I Built a Go Deploy CLI to Keep Server Control
I built a Go deploy CLI to keep direct, scriptable control over my server deployments without relying on a heavyweight platform or a vendor’s lock-in. It takes a build artifact, pushes it over SSH, runs a remote script, and reports the result — all from one command. This article explains the background, the design choices, and the practical lessons from that process.
Background: The Deployment Problem
Deploying a web service sounds simple: copy files, restart the process. But in practice it involves building, transferring, backing up, migrating, restarting, and verifying. Many teams reach for a CI/CD platform or a PaaS to automate this, but those tools add their own constraints: proprietary config formats, limited shell access, per-seat pricing, and a layer of abstraction that can hide what is actually running on the server.
I wanted a tool that was transparent — every step visible in a terminal log — and portable — a single static binary that runs on any machine without a runtime. Go is a natural fit because it compiles to a standalone executable, has a robust SSH library, and is easy to distribute.
Why Go, Not Bash or Python
Bash scripts are the default for deployment, but they get fragile as they grow: quoting bugs, missing error handling, and environment differences. Python is more readable but requires a Python interpreter and dependency management on the target machine. Go gives you:
- Static binaries — no runtime to install on the server or the operator’s laptop.
- Strong typing — catches config mistakes at compile time.
- Concurrency — easy to run remote commands in parallel, e.g., health checks on multiple instances.
- Standard library —
crypto/sshandos/execcover most needs without third-party dependencies.
For a solo developer or small team that wants to understand every layer, Go hits the sweet spot between control and productivity.
How the CLI Works
The tool follows a simple pipeline. You invoke it with a target environment (e.g., deploy --env prod), and it:
- Builds the project locally (or pulls a pre-built artifact).
- Compresses the artifact (tar.gz) to reduce transfer time.
- Uploads it via SCP/SFTP to a staging directory on the server.
- Runs a remote script that stops the service, backs up the current version, swaps the new files, and restarts.
- Verifies by polling a health endpoint or checking the process status.
- Rolls back automatically if verification fails.
All configuration lives in a single YAML file per environment (host, user, paths, service name). The CLI reads that file and executes the steps, printing each action with a timestamp. This makes it easy to see exactly what happened during a deploy, which is crucial for debugging.
Key Design Choices
Several decisions shaped the tool’s usability and safety:
- Idempotency — running the same deploy twice should have the same result. The remote script checks for existing backups and refuses to overwrite unless forced.
- Atomic swaps — the new version is placed in a separate directory, then a symlink is flipped. This avoids partial states if the process crashes mid-deploy.
- Explicit rollback — the CLI keeps the last two versions. If a health check fails, it can restore the previous symlink and restart the service.
- No secrets in the repo — SSH keys are referenced by path, and passwords are read from environment variables or a local secrets file that is git-ignored.
These choices came from real pain: a bad deploy that left the server in a broken state with no easy way to revert. The CLI now makes rollback a one-command operation.
Common Pitfalls and How to Avoid Them
Building a deploy tool teaches you where things go wrong. The most common issues I encountered:
- Path mismatches — the remote script assumed a different working directory than the SSH session’s default. Always use absolute paths in scripts.
- File permissions — the uploaded files inherited the local user’s umask, making them unreadable by the service user. The remote script now sets explicit permissions.
- Service managers — systemd vs. init.d vs. a plain nohup process. The CLI abstracts this with a
restart_commandconfig option. - Network timeouts — large uploads would stall. The tool now sets a configurable timeout and retries the transfer.
Each of these was a debugging session that ended with a clearer error message or a more robust default. The lesson: assume nothing about the server’s environment.
Comparing to Existing Tools
Why not use Capistrano, Fabric, or Ansible? Those are excellent, but they bring their own ecosystems. Capistrano is Ruby-centric, Fabric is Python, and Ansible has a learning curve for its YAML syntax and inventory system. My CLI is purpose-built for a single project’s needs, so it has fewer moving parts.
The trade-off is that I maintain it myself. For a side project or a small internal tool, that is worth it. For a team that deploys many services with complex orchestration, a general-purpose tool is likely better. The decision comes down to how much you value control versus how much you value convenience.
Costs and Maintenance
The main cost is time: writing the initial code, debugging edge cases, and updating it when the server setup changes. There is no monetary cost beyond the server itself. The CLI is a few hundred lines of Go, so maintenance is light. But it is a permanent responsibility — if the server’s SSH config changes, the tool must adapt.
Another cost is that you lose the community support that popular tools have. When something breaks, you debug it yourself. For me, that is acceptable because I know the codebase inside out, and the debugging often leads to a deeper understanding of my own infrastructure.
Safety and Rollback Strategies
Safety is paramount in any deployment tool. The CLI implements several safeguards:
- Pre-deploy checks — verifies that the remote directory exists, the service is running, and there is enough disk space.
- Backup before swap — the current version is archived with a timestamp, so you can always go back.
- Health verification — after restart, the tool waits for a configurable number of seconds and then checks a URL or a process list. If the check fails, it triggers a rollback.
- Lock file — prevents two concurrent deploys from stepping on each other.
These measures have saved me more than once. A bad config that caused the service to crash on startup was caught by the health check, and the rollback restored the previous version in seconds.
Frequently Asked Questions
Is it worth writing your own deploy tool?
It depends on your situation. If you have a single server and a simple deployment, a bash script is enough. If you have multiple environments and want a consistent, testable process, a small CLI can be a good investment. But if you need complex orchestration, use an existing tool.
How do you handle secrets like SSH keys?
The CLI uses SSH agent forwarding or a key file path specified in the config. Passwords are never stored in the repo; they are read from environment variables or a local secrets file that is git-ignored. The remote script also uses a dedicated deploy user with limited permissions.
Can this work with Docker containers?
Yes, but you would adapt the remote script to build and run containers instead of swapping files. The CLI’s core (upload, execute, verify) remains the same. The main difference is that the artifact is a Docker image or a docker-compose file.
What if the server is behind a jump host?
Go’s SSH library supports proxy jumps. You can configure a chain of hosts in the YAML, and the CLI will open a tunnel. This adds complexity, but it is doable. For a single jump host, it is straightforward.
How do you test the deploy tool itself?
I run it against a local Vagrant VM that mimics the production environment. This catches most issues before they hit the real server. The tool also has a --dry-run flag that prints the commands without executing them, which is useful for sanity checks.
Does this work on Windows or macOS?
Yes, because Go compiles to a binary for each OS. The CLI runs on any machine that has SSH access to the server. The remote script must be POSIX-compatible, so it works on Linux and macOS servers, but not on Windows servers.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.