Skip to content

Applications Guide

This guide explains how to deploy and manage applications in your Self-Host SaaS K3s cluster.

Overview

The deployment and management of applications in this cluster follows a GitOps approach using Argo CD for Continuous Deployment (CD) and GitHub Actions for Continuous Integration (CI).

Example Application

For reference, you can check out the example application at: https://github.com/humansoftware/example_self_hosted_saas_app

Configuring your applications

To deploy applications to your cluster, you need to configure them in the cluster's configuration:

  1. Edit the file group_vars/all/secrets.yml to specify which applications to deploy
  2. Add your application repositories to the self_saas_projects list
  3. Each repository should be specified in the format: owner/repo-name

For an example configuration, see secrets.example.yml

GitHub Authentication

The cluster needs access to your GitHub repositories for two purposes: 1. Argo CD needs to clone repositories to deploy applications 2. GitHub Actions need to interact with GitHub's API

To enable this access: 1. Create a GitHub Personal Access Token (PAT) with appropriate permissions: - repo scope for private repositories - workflow scope for GitHub Actions 2. Add this token to the github_pat field in group_vars/all/secrets.yml

The token will be securely stored and used by both Argo CD and GitHub Actions runners.

Application Structure

Continuous Integration (CI)

  • GitHub Actions is used for CI
  • Actions are defined in your application repository as you would normally do in GitHub
  • Key differences from standard GitHub Actions:
  • Actions run in your self-hosted cluster instead of GitHub runners
  • Pull request statuses and logs are updated the same way as with native GitHub runners

Docker Image Publishing

To publish Docker images to Harbor:

  1. Set up a GitHub secret for your application containing the Harbor admin password
  2. This password should match what you configured in the secrets configuration
  3. Use the following credentials for Docker login:
  4. Username: admin
  5. Password: The Harbor admin password secret you configured
  6. host: harbor.local

Continuous Deployment (CD)

Kubernetes Configuration

  • Applications must include Kubernetes Custom Resource Definitions (CRDs) in the deployment folder
  • These configurations define your application's components:
  • Jobs
  • Services
  • Pods
  • Other Kubernetes resources
  • The configurations can reference Docker images published by your CI pipelines

Kustomize Integration

  • Argo CD uses Kustomize for managing Kubernetes configurations
  • Each application should include a kustomization.yaml file that:
  • References the Kubernetes manifests
  • Defines common labels and annotations
  • Manages environment-specific configurations
  • For more information about Kustomize, see the official documentation
  • To learn how Argo CD integrates with Kustomize, refer to the Argo CD Kustomize documentation

Argo CD UI

Execute the following command to create a port-forward for the Argo CD UI:

kubectl -n argocd port-forward svc/argocd-server 8082:80

Visit http://localhost:8082 and log in with admin and the password you specified in secrets.

Best Practices

  1. Keep your Kubernetes configurations in the deployment folder organized and well-documented
  2. Ensure your GitHub Actions workflows are properly configured for self-hosted runners
  3. Securely manage your Harbor credentials using GitHub secrets
  4. Follow the example application structure for consistency