🚀 launchd

A simple, no-nonsense deployment tool for Go applications on Linux servers with systemd

---

📖 Overview

launchd is a lightweight CI/CD helper that deploys Go binaries to Linux servers from your laptop. No Docker, no complex pipelines—just simple, effective deployments using SSH and systemd.

✨ What it does

• 🔨 Build your Go app locally
• 📦 Copy the binary to your server over SSH
• ⚙️ Create/refresh a systemd service
• 🗄️ Run database migrations (optional)
• ✅ Verify health before finishing

Perfect for side projects, MVPs, and small-scale deployments where simplicity matters.

---

📋 Prerequisites

Before you start, make sure you have:

💻 On Your Local Machine

• ✓ Go installed (1.21+)
• ✓ OpenSSH client (ssh, scp)
• ✓ A Go project with a main package

🖥️ On Your Server

• ✓ Linux with systemd (Ubuntu, Debian, CentOS, Fedora, etc.)
• ✓ SSH access with sudo privileges
• ✓ Network port open (e.g., 8080)

🏥 In Your Application

• ✓ Health endpoint (e.g., GET /health → 200 OK)
• ✓ Configurable port (via flag or environment variable)

---

🔧 Installation

1. Clone the repository

git clone https://github.com/yourusername/launchd.git
cd launchd

2. Build the CLI

go build -o launchd ./cmd/launchd

3. (Optional) Add to PATH

sudo mv launchd /usr/local/bin/

Verify installation:

launchd --version

---

🎯 Quick Start

Prepare Your Application

Ensure your app builds locally:

go build -o ./bin/myapp ./path/to/your/cmd

Make sure it:

• Accepts a port configuration (flag or env var)
• Exposes a /health endpoint that returns 200 OK

Deploy in One Command

launchd deploy \
  --host your-server.com \
  --user deploy \
  --app ./bin/myapp \
  --port 8080 \
  --timeout 60s

🎉 That's it! Your app is now running as a systemd service.

---

🔍 How It Works

┌─────────────┐
│ 1. BUILD    │  Compile Go binary locally
└──────┬──────┘
       │
┌──────▼──────┐
│ 2. TRANSFER │  SCP binary to server
└──────┬──────┘
       │
┌──────▼──────┐
│ 3. SERVICE  │  Create/update systemd unit
└──────┬──────┘
       │
┌──────▼──────┐
│ 4. MIGRATE  │  Run DB migrations (optional)
└──────┬──────┘
       │
┌──────▼──────┐
│ 5. VERIFY   │  Health check polling
└─────────────┘

Under the Hood

1. Build: Uses your local Go toolchain to compile the binary
2. Transfer: Copies via scp to /usr/local/bin/<app>
3. Service: Generates systemd unit file and runs:
   • systemctl daemon-reload
   • systemctl enable <app>
   • systemctl restart <app>
4. Migrate: Executes migration tool if configured
5. Health Check: Polls http://<host>:<port>/health until success

---

🛠️ Command Reference

Basic Deployment

launchd deploy --host <server> --user <username> --app <binary> --port <port>

With Migrations

launchd deploy \
  --host server.com \
  --user deploy \
  --app ./bin/myapp \
  --port 8080 \
  --migrate \
  --migration-cmd "migrate -path /path/to/migrations -database postgres://..."

Custom Health Endpoint

launchd deploy \
  --host server.com \
  --user deploy \
  --app ./bin/myapp \
  --port 8080 \
  --health-path /api/health

---

🐛 Troubleshooting

SSH Connection Fails

# Test SSH access first
ssh deploy@your-server.com

Solutions:

• Verify SSH keys are set up: ssh-copy-id deploy@your-server.com
• Check firewall rules allow SSH (port 22)

Sudo Permission Denied

Problem: User cannot run systemctl without password

Solution: Add sudo permissions for systemctl:

# On the server, edit sudoers
sudo visudo

# Add this line (replace 'deploy' with your username)
deploy ALL=(ALL) NOPASSWD: /bin/systemctl, /usr/bin/install

Port Already in Use

# Check what's using the port
sudo lsof -i :8080

# Stop the conflicting service
sudo systemctl stop conflicting-service

Health Check Fails

Possible causes:

• App takes too long to start (increase --timeout)
• Wrong port or health endpoint path
• App crashes on startup

Check logs:

ssh deploy@server.com 'sudo journalctl -u myapp.service -f'

View Service Status

# Check if service is running
ssh deploy@server.com 'sudo systemctl status myapp.service'

# View recent logs
ssh deploy@server.com 'sudo journalctl -u myapp.service --since "10 minutes ago"'

---

🔄 Managing Your Service

View Status

ssh user@server 'sudo systemctl status myapp.service'

View Logs

# Follow logs in real-time
ssh user@server 'sudo journalctl -u myapp.service -f'

# Last 100 lines
ssh user@server 'sudo journalctl -u myapp.service -n 100'

Restart Service

ssh user@server 'sudo systemctl restart myapp.service'

Stop Service

ssh user@server 'sudo systemctl stop myapp.service'

Remove Service Completely

ssh user@server << 'EOF'
sudo systemctl stop myapp.service
sudo systemctl disable myapp.service
sudo rm -f /usr/local/bin/myapp
sudo rm -f /etc/systemd/system/myapp.service
sudo systemctl daemon-reload
EOF

---

🔁 Re-deploying

Good news: launchd is idempotent! You can run the same deploy command multiple times safely.

# Make changes to your code
# Then deploy again
launchd deploy --host server.com --user deploy --app ./bin/myapp --port 8080

What happens:

• ✅ Binary is overwritten with new version
• ✅ Service is restarted with zero-downtime goal
• ✅ Health check confirms new version is running

---

❓ FAQ

Do I need Docker?

No! launchd deploys native binaries directly. No containers required.

Do I need Go installed on the server?

No. Building happens locally on your machine. The server only runs the pre-compiled binary.

Do I need root access?

You need a user with sudo privileges to:

• Copy files to /usr/local/bin
• Manage systemd services

You don't need to log in as root directly.

Can I deploy to multiple servers?

Yes! Run the deploy command once per server, or write a simple bash loop:

for server in server1.com server2.com server3.com; do
  launchd deploy --host $server --user deploy --app ./bin/myapp --port 8080
done

What about environment variables?

Add them to your systemd service file or use a tool like envdir. Future versions of launchd may support this natively.

Is this production-ready?

launchd works great for:

• ✅ Side projects
• ✅ MVPs and prototypes
• ✅ Internal tools
• ✅ Small-scale production apps

For large-scale production with complex requirements, consider Kubernetes, Nomad, or managed platforms.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

Built with ❤️ for developers who prefer simplicity over complexity.

Why launchd? Because sometimes you just want to ship code, not configure orchestrators.

---

Documentation • Installation • Quick Start • Troubleshooting

Made with Go • Deployed with launchd