Deployment Guide

README.md is the primary deployment document for this project.

Source of Truth

Use the deployment section in ../README.md first.

Primary topics now live there:

  • production release flow
  • .vps.config setup
  • SSH key/password login notes
  • reverse proxy localhost bindings
  • deploy/Caddyfile.example

Deployment Files

  • release.sh - build locally, push to GHCR, deploy to VPS over SSH
  • build.sh - local production image build/push helper
  • docker-compose.prod.yml - production stack behind external reverse proxy
  • .vps.config.example - local deploy config template
  • .env.production.example - VPS runtime env template
  • deploy/Caddyfile.example - example Caddy config for app.iot.farmvion.com

Production Model

  • Build on local machine with Docker buildx for linux/amd64
  • Push images to GHCR
  • Deploy to Ubuntu x64 VPS over SSH with release.sh
  • Do not build the app on the VPS
  • Use an external reverse proxy in front of the app

Default localhost bindings:

  • backend: 127.0.0.1:3000
  • frontend: 127.0.0.1:5173

Quick Release

cp .env.production.example .env.production  # Fill in values
cp .vps.config.example .vps.config          # Fill in values
./release.sh

That’s it. release.sh handles everything: build, push, deploy, migrate, and verify.

Remote Requirements

  • Docker + Docker Compose plugin installed on the VPS
  • VPS can pull GHCR images
  • For password SSH deploys: local sshpass installed and VPS SSH allows password login

Release Sequence

  1. Build linux/amd64 images locally
  2. Push images to GHCR
  3. Upload docker-compose.prod.yml and .env.production to the VPS
  4. Validate compose config and required env keys on remote
  5. Pull backend and frontend images on remote
  6. Start infra services (postgres, redis, emqx, minio, portainer)
  7. Wait for postgres to be healthy (not just running)
  8. Run backend migrations
  9. Start backend and frontend
  10. Verify containers are running and healthy

Notes

  • Frontend VITE_* values are build-time values. Set them before running ./release.sh.
  • Database SSL is off by default for the current VPS compose flow. Set DATABASE_SSL=true only when your database requires TLS.
  • REMOTE_DOCKER_LOGIN=1 enables GHCR login on remote if the VPS cannot pull images directly.
  • Postgres health check waits for healthy status before running migrations, ensuring the database is fully ready.
  • Container health verification confirms backend and frontend are healthy after deployment.
  • Keep README.md updated first. This file is only a trimmed deployment reference.