Deploy with an AI agent

Don’t want to SSH in and run commands manually? Hand the deployment to an AI coding agent. The repo ships with ready-to-use prompt files in prompts/ — edit the placeholders, paste to your agent, done.

What you need before starting

A VPS with root or sudo access (Ubuntu 22.04/24.04/26.04).
SSH access — the agent connects via ssh user@your-server-ip.
Your repo on GitHub — the agent clones it onto the server.
Your domain (optional) — if you want HTTPS, point the DNS record to your server IP before starting.

First deploy

The repo includes prompt files for both deployment paths:

File	Path	What to edit
`prompts/deploy-systemd.txt`	systemd (bare VPS)	4 placeholders: SSH, repo, domain, install path
`prompts/deploy-docker.txt`	Docker	4 placeholders: SSH, repo, domain, install path

Steps

Open the prompt file for your chosen path (e.g. prompts/deploy-systemd.txt).
Replace the four placeholders at the top:
- USER@SERVER_IP → your SSH login (e.g. root@203.0.113.5)
- YOUR_USER/YOUR_REPO → your GitHub repo
- your-domain.com → your domain (or none)
- /opt/laju-go → install path on the server (or keep as-is)
Paste the entire file content to your AI agent.

The agent SSHes in, installs Go + Node.js (or Docker), clones the repo, builds the Go binary (npm run build:all — vite build then go build), creates .env, starts the service, and verifies /health on port 8080. It also saves a deploy.env file in your local project root (added to .gitignore) so routine updates don’t need retyping.

After first deploy: HTTPS

Your app is live on port 8080 (plain HTTP). For HTTPS, pick one:

File	Path	What you need
`prompts/setup-cloudflare.txt`	Cloudflare (recommended)	Cloudflare API token + domain on Cloudflare
`prompts/setup-caddy.txt`	Caddy (no Cloudflare)	Just a domain pointing to your server

Cloudflare — the agent creates the DNS record, sets SSL to Flexible, creates an Origin Rule (so CSRF and OAuth work), and configures the firewall to only allow Cloudflare IPs. You need a Cloudflare API token with Zone → DNS → Edit and Zone → Read permissions.

Caddy — the agent installs Caddy, creates a Caddyfile with automatic TLS via Let’s Encrypt, and starts it. No Cloudflare account needed.

Edit the placeholders in the prompt file, paste to your agent. For the full manual walkthrough (including Nginx + Certbot), see the reverse proxy guide.

Routine updates

When you push new code to GitHub, paste the matching update prompt. No editing needed — the agent reads deploy.env (created during first deploy) to reconnect.

File	Path
`prompts/update-systemd.txt`	systemd
`prompts/update-docker.txt`	Docker

Just paste the file content to your agent. It SSHes in, pulls the latest code, rebuilds, restarts, and verifies /health.

Troubleshooting

If the agent reports an error, paste it back and ask the agent to fix it. Common issues:

“laju-go: not found” in systemd logs

The systemd service can't find the laju-go binary. Check that
npm run build:all succeeded and the binary exists in the install
path. Update the ExecStart path in the systemd unit file if needed.

“EADDRINUSE: Port 8080”

Port 8080 is in use. Find what's using it (ss -tlnp | grep 8080)
and either kill it or change APP_PORT in .env to 8081.

Docker container keeps restarting

The Docker container is restarting. Check `docker compose logs`
and fix whatever error is causing the crash.

Health check returns non-200

The /health endpoint is returning a non-200 status. Check the
service logs (journalctl --user -u laju-go or docker compose logs)
and fix the issue.

CGO build failure

The Go build fails with a CGO error. go-sqlite3 requires a C
compiler. Install build-essential (apt install build-essential)
on the server, or use the Docker path which includes CGO in the
build stage.

The agent will diagnose and fix — you don’t need to know the commands yourself.