Deployment
What runs where. Two stacks of ShopNexus on one k3d cluster, kept in step with the repo by Argo CD, and the docs on GitHub Pages.
The server, the website, the docs and the console run on one k3d cluster in two stacks, dev and prod. Each stack has its own namespace and its own Postgres, Restate, RustFS and AI hub (ai-gateway and ai-models, from the ai repo). Everything the cluster needs is in infra/ in the umbrella repo. The Android app is built and installed from Gradle and is not part of the cluster.
| Stack | Domain | Namespace | Follows |
|---|---|---|---|
| dev | dev.shopnexus.id.vn | shopnexus-dev | :main, by digest |
| prod | shopnexus.id.vn | shopnexus-prod | a release of the umbrella, vX.Y.Z |
Each stack serves the website on its domain and four hosts below it: api. for the server, media. for the object store, docs. for the docs and console. for the console.
The system is built and checked on a local k3d cluster. Bringing it up on the author’s server and running the failover drills are the next steps, so the public hosts above are not live yet.
From a push to a pod
flowchart TB push[git push to main] --> ci[GitHub Actions build.yml] ci --> ghcr["GHCR ghcr.io/shopnexus/*<br/>:main and sha-#lt;commit#gt;"] ghcr --> iu[Argo CD Image Updater] iu --> argo[Argo CD] rel["umbrella release.yml<br/>X.Y.Z, tag vX.Y.Z"] --> argo argo --> devns[shopnexus-dev] argo --> prodns[shopnexus-prod] devns --> traefik[Traefik] prodns --> traefik
Each component repo (server, website, docs, console) has a .github/workflows/build.yml. A push to main builds the image and pushes it to GHCR with the tags main and sha-<commit>. For a prod release, the umbrella’s Release workflow adds the tag X.Y.Z to the sha-<commit> images of the commits its submodules point at. The packages are public, because the cluster pulls them without credentials.
Argo CD Image Updater watches GHCR for dev. It follows the digest of :main, writes the new tag as a Helm parameter on stack-dev, and Argo CD syncs the chart in infra/stack into shopnexus-dev. Prod has no Image Updater: the Release workflow writes the version into infra/ and tags the umbrella vX.Y.Z, and stack-prod renders infra/stack at that tag. CI never connects to the cluster. Traefik, bundled with k3s, routes each request by its Host header to the stack’s Services.
The cluster
The docs on GitHub Pages
The docs have a second deployment outside the cluster. Every push to the docs repository’s main runs .github/workflows/pages.yml, which builds the Astro site with Bun and publishes it on GitHub Pages at https://shopnexus.github.io/docs/. That build sets DOCS_BASE to the Pages path prefix and leaves out the internal Developers tab. The image in each stack is built with DOCS_BASE=/ and serves the site at the root of docs.<domain>.
Production checks in the server
The server refuses to start with APP_ENV=prod when:
RESTATE_IDENTITY_KEYis empty;FCM_CREDENTIALSis empty, so pushes would only be logged;PNV_TEST_NUMBERS=true, so PNV’s test numbers would sign in.
It also refuses to start in any environment while migrations are pending, which is why the migrate Job runs before the server in each stack. The chart sets APP_ENV from appEnv in the values file, PNV_TEST_NUMBERS=false in values-prod.yaml, and LOG_FORMAT=json in both stacks; the other server variables are on the Configuration page.