​
Overview

  • This guide details how to deploy a GoFast application on a Kubernetes cluster with monitoring capabilities.
  • The setup require a server with root access to deploy the Kubernetes cluster.
  • Optionaly, you can add worker nodes to the cluster.
  • Docker images are stored in the GitHub Container Registry.
  • CloudNativePG is used to deploy a PostgreSQL database.

Additional note, all resources are build for the ARM64 architecture. If you are using a different architecture, please update the Dockerfiles and the deployment scripts accordingly.

Important: Run all commands from the kube directory.

​
Prerequisites

Ensure the following tools are installed:

You’ll need server with root access:

  • Production/Staging server (e.g. 12.34.56.78)

Set up domains/subdomains:

  • User Service (e.g. user.gofast.live)
  • Admin Service (e.g. admin.gofast.live)
  • Client Service (e.g. client.gofast.live)
  • Monitoring (e.g. grafana.gofast.live)

These domains should resolve to the corresponding server IP addresses:

user.gofast.live -> 12.34.56.78
admin.gofast.live -> 12.34.56.78
client.gofast.live -> 12.34.56.78
grafana.gofast.live -> 12.34.56.78

Include AAAA records if using IPv6.

​
Configure Environment Variables

You’ve got two options to set the environment variables:

  1. Fill in the .env file with your secrets.
  2. Pass the secrets as environment variables when running the scripts (preferred).
POSTGRES_USER=your_user \
POSTGRES_PASS=your_pass \
sh setup_kube.sh

​
Install Kubernetes Cluster

Run the following command to set up the Kubernetes cluster:

sh setup_kube.sh

Monitor the cluster using the k9s tool:

k9s

​
Authorize GitHub Container Registry

Generate a personal access token with read:packages and write:packages scopes from GitHub Settings. Save it as GITHUB_ACCESS_TOKEN env and run:

sh setup_docker.sh

​
Build Docker Images

If you don’t have a builder, create one:

docker buildx create --use

Build the Docker images for each service:

cd ../your-service
docker buildx build --platform $BUILD_PLATFORM -t ghcr.io/$GITHUB_REPO/$IMAGE_NAME:latest --push .

Replace:

  • $BUILD_PLATFORM with the target platform (e.g., linux/amd64, linux/arm64)
  • $GITHUB_REPO with your GitHub Repo (e.g., gofast-live/gofast-app)
  • $IMAGE_NAME with the image name (e.g., service-user, service-admin-rc)

​
Set up Docker Images (Optional - For CI/CD)

Go https://github.com/OWNER/packages and connect the images to the repository. Then for each image, go to Package Settings -> Manage Actions Access -> Add the repository -> Change to Write.

​
Deploy PostgreSQL

This will add postgres to your cluster with a migration job and a backup job. Deploy a PostgreSQL database using CloudNativePG:

sh deploy_postgres.sh

​
Deploy the Application

sh deploy_app.sh

Check deployment status with:

kubectl get pods
# or
k9s

​
Deploy Monitoring Stack

Set up the monitoring stack:

sh deploy_monitoring.sh

This scripts outputs the Grafana admin password.

​
Deploy a New Version

To deploy an updated version, build and push new images, then restart the deployments:

kubectl rollout restart deployment service-user
kubectl rollout restart deployment service-admin
kubectl rollout restart deployment service-client

​
Auto Deploy using GitHub Actions

  1. Switch to the desired context:
kubectl config use-context YOUR_CONTEXT
  1. Copy the kubeconfig file:
cat ~/.kube/config

  1. On the GitHub repository, go to Settings > Secrets and add KUBE_CONFIG with the kubeconfig.

  2. Create database url from postgresql://${POSTGRES_USER}:${POSTGRES_PASS}@${MIGRATION_SERVER_IP}:30432/${POSTGRES_DB}?sslmode=disable and add it to the GitHub Secrets as DATABASE_URL.

  3. Modify the deploy.yml to match your environments and services.

​
Framework Specific Instructions

For the Next.js and Vue.js clients, we need to update the build environment variables.

To deploy a Next.js client, point NEXT_PUBLIC_USER_URL inside Dockerfile to your user service URL.

To deploy a Vue.js client, point VITE_USER_URL inside Dockerfile to your user service URL.

Was this page helpful?

Suggest edits