Quick Start Guide
About 494 wordsAbout 2 min
2025-06-30
Follow this guide to get StaticPages up and running in your Kubernetes cluster and deploy your first static site using GitHub Actions.
1. Deploy StaticPages with Helm
First, deploy the StaticPages backend to your existing Kubernetes cluster:
helm repo add spechtlabs https://charts.specht-labs.de
helm install staticpages spechtlabs/staticpages \
-n static-pages \
--create-namespace \
-f my-values.yamlThen, create a secret containing your S3 credentials, typically managed via ksops and kustomize:
apiVersion: v1
kind: Secret
metadata:
name: s3-credentials
namespace: static-pages
type: Opaque
stringData:
app-id: <your-app-id>
s3-secret: <your-base64-encoded-s3-secret>For full setup instructions, refer to the Helm Chart documentation and the GitHub Action documentation.
2. Configure Your Static Page
Update your my-values.yaml file with your desired static page configuration. Below is an example using Backblaze B2 as the S3-compatible storage backend:
configs:
pages:
- domain: specht-labs.de
bucket:
region: eu-central-003
url: https://s3.eu-central-003.backblazeb2.com
name: static-pages
applicationId: ENV(APPLICATION_ID)
secret: ENV(S3_SECRET)
proxy:
url: https://f003.backblazeb2.com
path: file/static-pages
notFound: 404.html
searchPath:
- /index.html
- /index.htm
git:
provider: github
repository: SpechtLabs/spechtlabs.github.io
mainBranch: main
preview:
enabled: true
branch: true
sha: false
environment: falseTips
Environment variables like ENV(APPLICATION_ID) and ENV(S3_SECRET) should be defined via Kubernetes secrets and loaded through Helm's extraEnvFrom configuration.
Sharing settings across pages with pageDefaults
If you host several sites from the same bucket and CDN, declare the shared settings once under a top-level pageDefaults block. Every entry in pages is deep-merged over it, so each page only needs the fields that differ:
configs:
pageDefaults:
bucket:
region: eu-central-003
url: https://s3.eu-central-003.backblazeb2.com
name: static-pages
applicationId: ENV(APPLICATION_ID)
secret: ENV(S3_SECRET)
proxy:
url: https://cdn.specht-labs.de
path: file/static-pages
notFound: 404.html
searchPath: [.html, .htm, /index.html, /index.htm]
git:
provider: github
mainBranch: main
preview:
enabled: true
branch: true
pages:
- domain: prose.specht-labs.de
git: { repository: SpechtLabs/prose }
- domain: dev.specht-labs.de
git: { repository: SpechtLabs/tka }
preview: { enabled: false } # overrides the default; `branch` stays inheritedMerge rules:
- Nested blocks merge per field — a page that sets only
git.repositorykeeps the defaultgit.providerandgit.mainBranch. - A field set on a page always wins, including a zero value:
preview.enabled: falseoverrides atruedefault. - Lists replace rather than append; a page's
searchPathfully supersedes the default one. domainis always per page. OmitpageDefaultsentirely and the config behaves exactly as before.
3. Set Up GitHub Action for Deployment
Use the following step in your GitHub Actions workflow to deploy your static site:
- name: Upload to Static Pages
uses: SpechtLabs/StaticPages-Upload@main
with:
endpoint: https://pages.specht-labs.de
site-dir: dist/Note
Ensure site-dir points to the directory containing your built static site (e.g., public/ for Hugo or dist/ for VuePress).
For a full working example, see the SpechtLabs Website Deployment Workflow.
