Deploy Portefaix on Civo

This guide shows you how to deploy a Portefaix platform on Civo Cloud using Civo's K3s-based managed Kubernetes service — a lightweight, fast-provisioning alternative to full Kubernetes clusters.

Goal: a running Civo Kubernetes cluster with Portefaix stacks continuously reconciled by ArgoCD.

Prerequisites

Civo account with a valid API token
civo CLI installed and authenticated
Terraform ≥ 1.5, kubectl, and Helm installed locally

1. Configure your environment

export CIVO_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export CIVO_REGION="LON1"   # LON1 | FRA1 | NYC1 | PHX1
export PORTEFAIX_ENV="dev"

. ./portefaix.sh civo

Verify CLI access:

civo kubernetes list

2. Provision the network with Terraform

The network module creates a dedicated Civo network and firewall for the Kubernetes cluster:

cd portefaix-infrastructure/terraform/civo/network
cp terraform.tfvars.example terraform.tfvars

region       = "LON1"
network_name = "portefaix-dev"

terraform init
terraform plan -out=tfplan
terraform apply tfplan

3. Provision the Kubernetes cluster with Terraform

cd portefaix-infrastructure/terraform/civo/kubernetes
cp terraform.tfvars.example terraform.tfvars

region          = "LON1"
cluster_name    = "portefaix-dev"
node_size       = "g4s.kube.medium"
node_count      = 3
network_name    = "portefaix-dev"

terraform plan -out=tfplan
terraform apply tfplan

4. Fetch cluster credentials

export CLUSTER_ID="$(terraform output -raw cluster_id)"

civo kubernetes config "$CLUSTER_ID" \
  --region $CIVO_REGION \
  --save --merge

kubectl config use-context portefaix-dev

kubectl get nodes
NAME                                                       STATUS   ROLES    AGE     VERSION
k3s-portefaix-dev-civo-691a-de1391-node-pool-8c2e-859cq   Ready    <none>   6m29s   v1.30.5+k3s1

5. Deploy Portefaix stacks via ArgoCD

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

helm install argocd argo/argo-cd \
  --namespace argocd --create-namespace \
  --values portefaix-kubernetes/gitops/argocd/values-civo.yaml \
  --wait

kubectl apply -f portefaix-kubernetes/gitops/argocd/bootstrap/app-of-apps-civo-$PORTEFAIX_ENV.yaml

argocd app wait portefaix-bootstrap --health --timeout 600

Stacks available on Civo

Stack	Description	Notes
Observability	Prometheus, Grafana, Loki	Local PV storage (smaller footprint for dev)
TLS certificates	cert-manager	HTTP-01 challenge via Civo LoadBalancer
Policy enforcement	Kyverno	—

Tip: Civo clusters use K3s which ships with Traefik as the default ingress controller. The Portefaix values file for Civo disables the K3s-bundled Traefik and installs ingress-nginx instead, for consistency with other cloud providers.

Troubleshooting

Cluster not showing in kubeconfig after merge

civo kubernetes config "$CLUSTER_ID" --region $CIVO_REGION

# Manually merge into existing kubeconfig
KUBECONFIG="$HOME/.kube/config:$HOME/.kube/portefaix-civo" \
  kubectl config view --flatten > /tmp/merged.yaml

mv /tmp/merged.yaml $HOME/.kube/config