StackClass Helm Charts

This repository hosts official Helm charts for StackClass. These charts are used to deploy StackClass to Kubernetes.

Pre-requisites

• Kubernetes 1.19+.
• Helm 3.9.0+.
• PV provisioner support in the underlying infrastructure.
• ReadWriteMany volumes for deployment scaling.
• Cert-Manager (for TLS automation, install separately if needed).
• Harbor (for container image storage and management).
• Gitea (for Git repository management).

Cert-Manager

cert-manager is a Kubernetes add-on that automates the management and issuance of TLS certificates from various issuing sources. It ensures certificates are valid and up-to-date, and attempts to renew them at an appropriate time before expiry.

Optional: Only install cert-manager if you need TLS automation. If you're using your own certificates or don't need HTTPS, you can skip this step. For TLS configuration options, see the TLS Support section below.

For detailed installation instructions, refer to the cert-manager Documentation.

Tekton

Tekton is a powerful and flexible open-source framework for creating CI/CD systems. We use Tekton to build and test our course test cases, and it's a required dependency that must be installed beforehand.

We recommend installing Tekton using the Tekton Operator. For installation instructions, refer to: Tekton Operator Helm Chart.

Harbor

Harbor is an open-source container image registry that provides secure storage and management of container images. To install Harbor, follow the official Harbor Helm Chart instructions.

Gitea

Gitea is a lightweight and self-hosted Git service required for managing repositories in StackClass. It provides essential Git functionality for the platform.

For detailed configuration options, refer to the Gitea Helm Chart Documentation.

Add Helm Repository

helm repo add stackclass https://charts.stackclass.dev

If you had already added this repo earlier, run helm repo update to retrieve the latest versions of the packages. You can then run helm search repo stackclass to see the charts.

Install StackClass

Important Notes: By default, this installs PostgreSQL (see PostgreSQL config for credentials). To customize (e.g., disable PostgreSQL or adjust storage), use -f values.yaml or --set after reviewing the Configuration section.

To install StackClass for the first time with the release name stackclass:

helm install stackclass stackclass/stackclass --create-namespace -n=stackclass

This command deploys the StackClass API Server, frontend, and services on your Kubernetes cluster with default configurations.

Upgrade StackClass

To upgrade an existing StackClass deployment (e.g., after modifying values.yaml):

helm upgrade stackclass stackclass/stackclass -n=stackclass

Optional Flags:

• --atomic: Automatically rollback if the upgrade fails.
• --wait: Wait for all resources to be ready before marking the upgrade as complete.
• -f values.yaml: Override default values with a custom configuration file.

Example with atomic upgrade:

helm upgrade stackclass stackclass/stackclass -n=stackclass --atomic --wait

Uninstall StackClass

To uninstall the chart and remove all associated Kubernetes resources:

helm uninstall stackclass -n=stackclass

Configuration

PostgreSQL

PostgreSQL is enabled by default (postgresql.enabled=true). It will be automatically deployed with generated credentials.

Using External PostgreSQL:

1. Disable the built-in PostgreSQL:

helm install stackclass stackclass/stackclass --set postgresql.enabled=false

2. Manually update these secrets:

• backend-secrets.yaml: Replace DATABASE_URL
• frontend-secrets.yaml: Replace BETTER_DATABASE_URL

Application Configuration

This chart manages application settings through Kubernetes Secrets. By default, it creates:

• {release-name}-backend-secrets
• {release-name}-frontend-secrets

-Customizable Secrets:

-Some secrets must be explicitly provided by the user:

• BETTER_AUTH_SECRET: Replace <REPLACE_WITH_BETTER_AUTH_SECRET> with your Better Auth Secret.
• GITHUB_CLIENT_ID: Replace <REPLACE_WITH_GITHUB_CLIENT_ID> with your GitHub OAuth client ID.
• GITHUB_CLIENT_SECRET: Replace <REPLACE_WITH_GITHUB_CLIENT_SECRET> with your GitHub OAuth client secret.

1. Before installation: Modify values.yaml or use --set to override secret values. For example:

# Other options ...
--set frontend.secrets.betterAuthSecret="your-better-auth-secret" \
--set frontend.secrets.githubClientId="your-client-id" \
--set frontend.secrets.githubClientSecret="your-client-secret"

2. After installation: Edit secrets directly (changes persist through upgrades):

kubectl edit secret stackclass-backend-secrets -n stackclass
kubectl edit secret stackclass-frontend-secrets -n stackclass

Key Configuration Files:

• Backend: Refer to charts/stackclass/templates/secrets/backend-secrets.yaml
• Frontend: Refer to charts/stackclass/templates/secrets/frontend-secrets.yaml
• Environment templates: Check each component's .env.example for available variables.

Storage

This chart configures persistent storage for PostgreSQL and backend services. All volumes use ReadWriteOnce access mode by default.

When left unspecified or set to an empty string (storageClass: ""), the chart will automatically use your Kubernetes cluster's default StorageClass for dynamic volume provisioning. If you need to use a specific storage backend (e.g., AWS gp3, Azure managed-premium, or GCP standard), you can explicitly specify the StorageClass name.

💡 Run kubectl get storageclass to see available classes in your cluster.

PostgreSQL uses 10Gi of storage with your cluster's default StorageClass.

postgresql:
  primary:
    persistence:
      size: 10Gi
      storageClass: ""

Backend defaults to 10Gi with cluster-default storage.

backend:
  persistence:
    size: 10Gi
    storageClass: ""

Ingress

Ingress Class

By default, the Ingress resources will use the cluster's default Ingress Controller (e.g., Traefik for k3s, ALB for EKS). Below is a table summarizing the configurations for different platforms:

Platform	Ingress Class	Documentation
k3s (Traefik)	traefik	Traefik Docs
AWS EKS (ALB)	alb	AWS ALB Docs
GKE (GCE)	gce	GKE Ingress Docs
Standard	nginx	Nginx Ingress Docs

Notes:

• If className is left empty, the cluster will use its default Ingress Controller.
• annotations are only required for overriding controller-specific behaviors.

Hostname

The default host values are configured for testing purposes:

• Frontend: stackclass.local
• Backend:
  • api: api.stackclass.local
  • git: git.stackclass.local

For production environments, you should override these values using --set or a custom values.yaml file. For example:

# Other options ...
--set frontend.ingress.host=your-frontend-domain.com \
--set backend.ingress.hosts.api=your-backend-domain.com \
--set backend.ingress.hosts.git=your-git-domain.com

TLS Support

To enable TLS for the Ingress resources, follow these steps:

Enable TLS in values.yaml or via --set:

# Other options ...
--set frontend.ingress.tls.enabled=true \
--set backend.ingress.tls.enabled=true

Using Your Own Certificates:

If you already have TLS certificates (e.g., from your organization's CA or a commercial provider), you can configure them directly:

# Other options ...
--set frontend.ingress.tls.secretName="your-frontend-tls-secret" \
--set backend.ingress.tls.secretName="your-backend-tls-secret"

Create TLS Secrets (if not already present):

kubectl create secret tls your-frontend-tls-secret \
    --cert=path/to/cert.crt \
    --key=path/to/cert.key \
    -n stackclass

kubectl create secret tls your-backend-tls-secret \
    --cert=path/to/cert.crt \
    --key=path/to/cert.key \
    -n stackclass

Verify the Ingress resources include TLS:

kubectl get ingress -n stackclass

Notes:

• Ensure the certificate's Common Name (CN) or Subject Alternative Names (SANs) match the configured host values.

Using Cert-Manager for Automatic TLS

To automate TLS certificate management using cert-manager, first ensure cert-manager is installed, then enable the Issuer configuration in values.yaml or via --set:

# Other options ...
--set issuer.enabled=true \
--set [email protected] \
--set issuer.environment=staging  # or "prod" for production

Notes:

• Replace [email protected] with a valid email address for certificate notifications.
• Set environment to prod for production certificates (rate limits apply).
• Certificates will be automatically issued and renewed by cert-manager.

Documentation

• All the helm chart source code will be committed to main branch, all the charts will be placed under /charts and each chart will be separate with their own folder

• The index.yaml will be committed to gh-pages branch, which represent an accessible page. The helm repository required an index.yaml file to show its charts structure

• Github action is set to provide helm release automation when changes are committed to the main branch.

• Due to rapid churn in the Kubernetes ecosystem, charts in this repository assume a version of Kubernetes released in the last 12 months. This typically means one of the last four releases.

  Note: While these charts may work with versions of older versions of Kubernetes, only releases made in the last year are eligible for support.

License

Copyright (c) The StackClass Authors. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.