Skip to content
VietGara Docs

DEPLOYMENT GUIDE

VietGara — Version 1.0 — September 28, 2026 · Scope: staging (Phase 1)

This page is the entry point for deploying VietGara. The commands live next to the files they run, in the vietgara-infra repository, so there is one source of truth:

EnvironmentHowGuide
LocalDocker Compose, images built from sourcevietgara-backend/README.md, Run locally
StagingOne VM, Docker Compose, images from the GitHub Container Registry (ghcr.io)vietgara-infra/staging/README.md
ProductionGKE or Cloud Run, Cloud SQL, created from Terraform (Release 9.2)Not yet written; target design in Deployment Architecture

Staging release in short

  1. Publish images: merge to master or push a v* tag in vietgara-backend, vietgara-owner-web and vietgara-admin-web. GitHub Actions pushes each image to GHCR; the tag is in the run summary. (make image-push is the manual fallback.)
  2. Deploy on the VM, in ~/vietgara-infra/staging: make backup, then make deploy BACKEND_TAG=<tag> WEB_OWNER_TAG=<tag> WEB_ADMIN_TAG=<tag>.
  3. Check make ps (backend healthy), open the staging URL and run the P1 E2E scenarios (05-Testing).
  4. Roll back if needed: make deploy with the previous tags; restore the backup when the schema changed.

The one-time VM preparation, the settings in .env, platform admins, backups and troubleshooting are all covered in vietgara-infra/staging/README.md.

Web UI kit

vietgara-web-ui is a library, not a service: nothing is deployed from it. A UI change ships by tagging the kit (vX.Y.Z) and bumping that tag in vietgara-owner-web and vietgara-admin-web, which rebuild their images as usual. The web Dockerfiles install git because the dependency is fetched from GitHub over HTTPS during npm ci.

Admin Web

vietgara-admin-web builds its own image (ghcr.io/viettechno/vietgara-admin-web) the same way as the owner web. It calls the API on its own origin (/api), so it has its own host. On staging, vietgara-infra/staging runs it as the vietgara-admin-web service: Caddy (or Traefik) serves WEB_ADMIN_ADDRESS (vietgara-admin-staging.viettechno.com, a DNS A record) with the SPA from its container and /api through Kong. Set WEB_ADMIN_TAG in .env, or pass it to make deploy. Locally, vietgara-backend’s Compose stack serves it at http://admin.localhost:8000 (make docker-up-admin-web).

Hostnames

Staging’s hosts are vietgara-staging, vietgara-admin-staging, vietgara-api-staging (the API-only host the mobile apps use) and vietgara-mailpit-staging, all .viettechno.com; production drops -staging. The full list and the reasoning are in Deployment Architecture, Section 2.2. Restrict access to the host (IP allow-list or VPN) where possible.

Public sites (planned, Release 10.2)

viettechno-website and vietgara-help are static sites, not part of vietgara-infra’s Compose stack. Each repository’s CI builds the site and deploys it to the static host (ADR-013); a pull request gets a preview URL, master publishes to production. The hosts are viettechno.com, www.viettechno.com and vietgara-help.viettechno.com, CNAME records in the company zone; keep the MX, SPF and DKIM records of viettechno.com as they are. The contact form’s function needs two secrets on the host, the API host’s base URL and the anti-spam secret; neither is kept in the repository.