Go Developer Toolkit
Doc 1 of 2 • Series Complete
A curated set of Go libraries and CLI tools for building production-grade applications — covering WebSocket hubs, deployment automation, and database optimization.
go-deploy-cli
“One-command zero-downtime deployment for Go + Docker projects”
A CLI tool that wraps Docker, SSH, and GitHub Actions into a single deploy command with automatic rollback on failure, Slack notifications, and environment-specific config files.
Installation
Detailed installation instructions for all platforms
Requirements
Required for go install method only
https://golang.org/dl/Required on the machine running deployments
https://docs.docker.com/get-docker/SSH key-based access to your target server
Install via Homebrew
Simplest installation on macOS
brew install lordofthemind/tap/go-deploy-cliPlatform Notes
- Homebrew handles PATH automatically
Quick Start
Deploy your first project in 3 steps
Install go-deploy-cli
Install via go install or Homebrew
# Option 1: go install (requires Go 1.21+)
go install github.com/lordofthemind/go-deploy-cli@latest
# Option 2: Homebrew (macOS / Linux)
brew install lordofthemind/tap/go-deploy-cli
# Verify installation
go-deploy version💡 Tips
- •Ensure $GOPATH/bin is in your $PATH for go install
- •Homebrew automatically adds the binary to /usr/local/bin
Initialize your project
Run go-deploy init in your project root to create a .deployrc.yaml config file
cd my-go-project
go-deploy init
# This creates .deployrc.yaml — edit it to match your server:
# host: your-vps-ip
# user: deploy
# image: ghcr.io/yourname/myapp
# envFile: .env.productionDeploy
Run go-deploy deploy to build, push, and restart your container
go-deploy deploy
# Output:
# [go-deploy] Building Docker image...
# [go-deploy] Pushing to ghcr.io/yourname/myapp:abc1234...
# [go-deploy] Deploying to 192.168.1.1...
# [go-deploy] Health check passed ✓
# [go-deploy] Deployed in 2m 14sYou're all set! Check out the detailed usage guide below for more advanced features.
Usage Guide
Practical examples for common deployment scenarios
Basic Deployment
Deploy using default .deployrc.yaml config
# Deploy using config in current directory
go-deploy deploy
# Deploy with explicit config file
go-deploy deploy --config ./configs/production.yamlOutput
Builds Docker image, pushes to registry, SSH-deploys to server, runs health checkRollback
Roll back to the previous successful deployment
# Roll back to previous deployment
go-deploy rollback
# Roll back to a specific image tag
go-deploy rollback --tag abc1234CLI Reference
Complete reference for all go-deploy-cli commands and flags
deploy
Builds a Docker image, pushes it to the configured registry, and deploys it to the target server via SSH with a health check verification step.
Signature
go-deploy deploy [flags]Parameters
--configstringDefault: .deployrc.yamlPath to .deployrc.yaml config file
--tagstringDocker image tag to deploy (default: short git SHA)
--confirmboolDefault: falseRequire interactive confirmation before deploying
Returns
exit 0 on success, exit 1 on failureExamples
go-deploy deploygo-deploy deploy --config .deployrc.staging.yamlgo-deploy deploy --tag v1.2.3 --confirmrollback
Restarts the previous Docker image on the target server. Reads the last successful deployment tag from the server-side deployment log.
Signature
go-deploy rollback [flags]Parameters
--tagstringRoll back to a specific image tag (default: previous)
Returns
exit 0 on success, exit 1 on failureExamples
go-deploy rollbackgo-deploy rollback --tag abc1234status
Shows the current deployment status on the target server — running container, image tag, uptime, and last 10 log lines.
Signature
go-deploy statusReturns
Formatted status output to stdoutExamples
go-deploy statusExamples
Real-world code examples and use cases
Deploy a Go API server
beginnerComplete .deployrc.yaml for a Go REST API
# .deployrc.yaml
host: 192.168.1.100
user: deploy
sshKeyPath: ~/.ssh/deploy_key
image: ghcr.io/myorg/myapi
registry: ghcr.io
container:
name: myapi
port: "8080:8080"
restartPolicy: unless-stopped
envFile: .env.production
healthCheck:
path: /api/health
timeout: 30sDeploy with pre/post hooks
intermediateRun database migrations before and cleanup after deploy
hooks:
preDeploy:
- command: "go-deploy exec -- ./scripts/migrate.sh"
timeout: 60s
postDeploy:
- command: "go-deploy exec -- docker image prune -f"Frequently Asked Questions
4 questions answered
Still have questions?
Check out the source code or open an issue on GitHub
Related Content
Explore related articles, projects, and tools.