ryan/turbovault-app
1
0
Fork 0
mirror of https://github.com/ryankazokas/turbovault-app.git synced 2026-04-16 22:12:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Deploy to production: GitHub Actions + ghcr.io + Kubernetes

Browse Source 
- Switch from Gitea to GitHub Container Registry (ghcr.io)
- Add GitHub Actions workflow with Tailscale connectivity
- Update k8s manifests for cloud nodes and Traefik ingress
- Configure for turbo.kazcloud.dev domain
- Test deployment with home page text change
This commit is contained in:
Ryan Kazokas
2026-03-29 08:46:27 -04:00
parent 2bb1dfa1e4
commit 69993a3bf5
14 changed files with 793 additions and 596 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
docs/GITEA_SECRETS.md
View File

@@ -1,202 +0,0 @@
# Gitea Secrets Configuration
This document explains what secrets you need to configure in Gitea for automatic builds and deployments.
## Required Secrets
### 1. GITEA_TOKEN
**Purpose:** Allows Gitea Actions to push Docker images to Gitea Container Registry
**How to create:**
1. Go to Gitea → **Settings** → **Applications**
2. Under **"Generate New Token"**, enter name: `gitea-actions`
3. Select scopes:
- ✅ `write:package` (push container images)
- ✅ `read:package` (pull container images)
4. Click **"Generate Token"**
5. Copy the token (starts with `glpat-...` or similar)
**How to add to repository:**
1. Go to your Gitea repository: `gitea.kazcloud.dev/ryankazokas/turbovault-app`
2. Click **Settings** → **Secrets**
3. Click **"Add Secret"**
4. Name: `GITEA_TOKEN`
5. Value: Paste the token you copied
6. Click **"Add Secret"**
---
### 2. KUBECONFIG
**Purpose:** Allows Gitea Actions to deploy to your Kubernetes cluster
**How to create:**
```bash
# Export your kubeconfig as base64
cat ~/.kube/config | base64 -w 0 > kubeconfig-base64.txt
# Copy the contents of kubeconfig-base64.txt
cat kubeconfig-base64.txt
```
**How to add to repository:**
1. Go to your Gitea repository: `gitea.kazcloud.dev/ryankazokas/turbovault-app`
2. Click **Settings** → **Secrets**
3. Click **"Add Secret"**
4. Name: `KUBECONFIG`
5. Value: Paste the base64-encoded kubeconfig
6. Click **"Add Secret"**
**⚠️ Security Note:** This gives Gitea Actions full access to your Kubernetes cluster. Only add this to trusted repositories!
---
## Optional: Scoped Kubeconfig (More Secure)
Instead of using your full kubeconfig, create a limited service account:
```bash
# Create service account for deployments
kubectl create serviceaccount turbovault-deployer -n turbovault
# Create role with deployment permissions
cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: turbovault-deployer
namespace: turbovault
rules:
- apiGroups: ["apps"]
resources: ["deployments"]
verbs: ["get", "list", "patch", "update"]
- apiGroups: [""]
resources: ["pods"]
verbs: ["get", "list"]
- apiGroups: ["apps"]
resources: ["deployments/status"]
verbs: ["get"]
EOF
# Bind role to service account
kubectl create rolebinding turbovault-deployer \
--role=turbovault-deployer \
--serviceaccount=turbovault:turbovault-deployer \
-n turbovault
# Get service account token
kubectl create token turbovault-deployer -n turbovault --duration=87600h > token.txt
# Create minimal kubeconfig
cat <<EOF > deployer-kubeconfig.yaml
apiVersion: v1
kind: Config
clusters:
- cluster:
server: https://100.101.31.99:6443
# Add certificate-authority-data from your main kubeconfig if needed
insecure-skip-tls-verify: true
name: k3s
contexts:
- context:
cluster: k3s
namespace: turbovault
user: turbovault-deployer
name: k3s
current-context: k3s
users:
- name: turbovault-deployer
user:
token: $(cat token.txt)
EOF
# Encode for Gitea
cat deployer-kubeconfig.yaml | base64 -w 0 > deployer-kubeconfig-base64.txt
# Use this in KUBECONFIG secret instead
cat deployer-kubeconfig-base64.txt
```
This limits Gitea Actions to only deploying TurboVault, not full cluster access.
---
## Verifying Secrets
After adding secrets, you can verify they're set:
1. Go to repository → **Settings** → **Secrets**
2. You should see:
- `GITEA_TOKEN` ✅
- `KUBECONFIG` ✅
**Note:** You can't view secret values after creation (security feature).
---
## Testing the Workflow
After secrets are configured:
```bash
# Create a test tag
git tag v0.0.1-test
git push origin v0.0.1-test
```
Watch the workflow at:
`gitea.kazcloud.dev/ryankazokas/turbovault-app/actions`
The workflow should:
1. ✅ Build Docker image
2. ✅ Push to Gitea registry
3. ✅ Deploy to Kubernetes
4. ✅ Wait for rollout to complete
---
## Troubleshooting
### "Error: authentication required"
- Check `GITEA_TOKEN` is set and has `write:package` scope
### "Error: Unable to connect to the server"
- Check `KUBECONFIG` secret is set correctly
- Verify base64 encoding (no line breaks with `-w 0`)
- Test kubeconfig works locally: `kubectl --kubeconfig=<file> get pods -n turbovault`
### "Error: deployment not found"
- Make sure initial deployment is done first: `./scripts/deploy-k8s.sh`
- Workflow only updates existing deployments, doesn't create them
---
## Security Best Practices
✅ **DO:**
- Use service account with minimal permissions (Role, not ClusterRole)
- Rotate tokens regularly
- Only add secrets to repositories you control
❌ **DON'T:**
- Share secrets in code or documentation
- Use admin kubeconfig if possible
- Commit secrets to git
---
## Summary
**Two secrets required:**
1. **GITEA_TOKEN** - For pushing container images
2. **KUBECONFIG** - For deploying to Kubernetes
Both added at: `gitea.kazcloud.dev/ryankazokas/turbovault-app/settings/secrets`
After setup, just push tags to trigger automatic builds and deployments! 🚀

323
docs/GITEA_WORKFLOW.md
View File

@@ -1,323 +0,0 @@
# Gitea CI/CD Workflow
## Overview
TurboVault uses Gitea Actions for fully automated builds and deployments:
1. **Push code to GitHub** (primary repository)
2. **Gitea mirrors** from GitHub automatically
3. **Gitea Actions** builds Docker image and deploys to Kubernetes
All automatic! 🚀
---
## Setup (One-Time)
### 1. Mirror GitHub Repository to Gitea
In Gitea:
1. Go to `gitea.kazcloud.dev` → **New Repository**
2. Choose **"New Migration"** → **"GitHub"**
3. URL: `https://github.com/ryankazokas/turbovault-app`
4. Enable **"This repository will be a mirror"**
5. Set sync interval: **10 minutes** (or setup webhook for instant sync)
6. Click **"Migrate Repository"**
**Webhook for instant sync (optional):**
- In GitHub repo → Settings → Webhooks → Add webhook
- Payload URL: `https://gitea.kazcloud.dev/ryankazokas/turbovault-app/mirror-sync`
- Content type: `application/json`
- Events: Just the push event
### 2. Configure Gitea Secrets
See [GITEA_SECRETS.md](GITEA_SECRETS.md) for detailed instructions.
**Required secrets:**
- `GITEA_TOKEN` - For pushing images to registry
- `KUBECONFIG` - For deploying to Kubernetes
Add at: `gitea.kazcloud.dev/ryankazokas/turbovault-app/settings/secrets`
### 3. Initial Deployment to Kubernetes
Before automation works, do initial deployment:
```bash
# Build and push first image
docker build -t gitea.kazcloud.dev/ryankazokas/turbovault-app:v1.0.0 .
docker login gitea.kazcloud.dev
docker push gitea.kazcloud.dev/ryankazokas/turbovault-app:v1.0.0
# Configure secrets and database
cp k8s/secrets.yaml.example k8s/secrets.yaml
nano k8s/secrets.yaml # Add SECRET_KEY_BASE, DATABASE_PASSWORD, etc.
nano k8s/configmap.yaml # Add DATABASE_HOST, etc.
# Deploy to Kubernetes
./scripts/deploy-k8s.sh
```
When script asks for registry credentials:
- Registry: `gitea.kazcloud.dev`
- Username: `ryankazokas`
- Password: `<your-gitea-token>`
---
## Daily Workflow
After setup, deployments are fully automatic:
```bash
# 1. Make changes in GitHub
git add .
git commit -m "Feature: add new functionality"
git push origin main
# 2. When ready to deploy, create version tag
git tag v1.0.1
git push origin v1.0.1
# 3. That's it! ✅
# Gitea auto-syncs → builds → deploys to Kubernetes
```
**Watch build and deployment:**
`https://gitea.kazcloud.dev/ryankazokas/turbovault-app/actions`
---
## How It Works
```
GitHub (code)
↓ (mirror sync)
Gitea (code mirror)
↓ (on tag push)
Gitea Actions:
1. Build Docker image
2. Push to gitea.kazcloud.dev registry
3. Deploy to Kubernetes (kubectl)
4. Wait for rollout
5. Show status
↓
Kubernetes pulls image and updates deployment ✅
```
---
## Workflow Features
### ✅ Automatic Rollout Status
Workflow waits for rollout to complete before marking as success.
### ✅ Automatic Rollback on Failure
If deployment fails, workflow automatically rolls back to previous version.
### ✅ Multiple Tags
Each version gets two tags:
- `v1.0.0` (specific version)
- `latest` (always points to most recent)
### ✅ Manual Trigger
Can manually trigger builds via Gitea Actions UI if needed.
---
## Manual Deployment (If Needed)
If you want to deploy manually without waiting for Gitea sync:
```bash
# Build and push
docker build -t gitea.kazcloud.dev/ryankazokas/turbovault-app:v1.0.1 .
docker push gitea.kazcloud.dev/ryankazokas/turbovault-app:v1.0.1
# Deploy
./scripts/update-deployment.sh v1.0.1
```
---
## Version Management
### Semantic Versioning
Use semantic versioning for tags:
- `v1.0.0` - Major.Minor.Patch
- `v1.0.1` - Patch update (bug fixes)
- `v1.1.0` - Minor update (new features)
- `v2.0.0` - Major update (breaking changes)
### Viewing Deployed Version
```bash
# Check current image
kubectl get deployment turbovault -n turbovault -o jsonpath='{.spec.template.spec.containers[0].image}'
# Check all pods
kubectl get pods -n turbovault -l app=turbovault
```
---
## Troubleshooting
### Workflow Fails at "Build and push"
**Issue:** Can't push to registry
**Fix:**
- Check `GITEA_TOKEN` secret is set
- Verify token has `write:package` scope
- Test: `docker login gitea.kazcloud.dev` with token
### Workflow Fails at "Deploy to Kubernetes"
**Issue:** Can't connect to Kubernetes
**Fix:**
- Check `KUBECONFIG` secret is set correctly
- Verify base64 encoding: `echo "$SECRET" | base64 -d | kubectl --kubeconfig=/dev/stdin get nodes`
- Check cluster is reachable from Gitea Actions runner
### Deployment Succeeds but Pods Not Starting
**Issue:** Image pull errors or configuration issues
**Check:**
```bash
kubectl get pods -n turbovault
kubectl describe pod <pod-name> -n turbovault
kubectl logs <pod-name> -n turbovault
```
**Common causes:**
- Image pull secret not configured (run `./scripts/deploy-k8s.sh` again)
- Database connection issues (check `k8s/configmap.yaml` and `k8s/secrets.yaml`)
- Missing environment variables
---
## Monitoring Deployments
### Watch Live Deployment
```bash
# Watch pods update
kubectl get pods -n turbovault -w
# Watch rollout status
kubectl rollout status deployment/turbovault -n turbovault
# View logs
kubectl logs -f -l app=turbovault -n turbovault
```
### Deployment History
```bash
# View rollout history
kubectl rollout history deployment/turbovault -n turbovault
# View specific revision
kubectl rollout history deployment/turbovault --revision=2 -n turbovault
```
---
## Rollback
### Automatic Rollback
Workflow automatically rolls back if deployment fails.
### Manual Rollback
```bash
# Rollback to previous version
kubectl rollout undo deployment/turbovault -n turbovault
# Rollback to specific revision
kubectl rollout undo deployment/turbovault --to-revision=3 -n turbovault
```
---
## Security Considerations
### Secrets Management
- All secrets in Gitea are encrypted
- Secrets never appear in logs
- Use service account kubeconfig (not admin)
### Network Security
- Gitea Actions runners on internal network
- Can reach Kubernetes API (not exposed publicly)
- Images pulled from internal registry
### Access Control
- Only repository collaborators can trigger workflows
- Gitea token scoped to package registry only
- Kubeconfig scoped to turbovault namespace only (recommended)
---
## Advanced: Staging vs Production
To add staging environment:
1. Create `v*.*.*-rc*` tags for release candidates
2. Deploy to staging namespace
3. Update workflow to detect RC tags:
```yaml
- name: Determine environment
id: env
run: |
if [[ "${{ github.ref }}" =~ -rc ]]; then
echo "namespace=turbovault-staging" >> $GITHUB_OUTPUT
else
echo "namespace=turbovault" >> $GITHUB_OUTPUT
fi
```
---
## Quick Reference
```bash
# Deploy new version
git tag v1.0.1
git push origin v1.0.1
# Watch deployment
kubectl get pods -n turbovault -w
# View logs
kubectl logs -f -l app=turbovault -n turbovault
# Rollback if needed
kubectl rollout undo deployment/turbovault -n turbovault
# Check current version
kubectl get deployment turbovault -n turbovault -o jsonpath='{.spec.template.spec.containers[0].image}'
```
---
## Summary
**Setup once:**
1. Mirror GitHub → Gitea
2. Add Gitea secrets (GITEA_TOKEN, KUBECONFIG)
3. Initial deployment with `./scripts/deploy-k8s.sh`
**Daily workflow:**
1. Push code to GitHub
2. Create version tag
3. Everything else is automatic! ✅
Questions? Check [GITEA_SECRETS.md](GITEA_SECRETS.md) for secret configuration details.

251
docs/GITHUB_SECRETS.md Normal file
View File

@@ -0,0 +1,251 @@
# GitHub Secrets Configuration
This document explains what secrets you need to configure in GitHub for automatic builds and deployments.
## Required Secrets
Go to: **`https://github.com/ryan/turbovault-app/settings/secrets/actions`**
### 1. GITHUB_TOKEN (Built-in)
**Purpose:** Authenticate to GitHub Container Registry (ghcr.io)
**Value:** This is automatically provided by GitHub Actions - no setup needed!
**How to add:**
1. Go to GitHub repo → Settings → Secrets and variables → Actions
2. Click **"New repository secret"**
3. Name: `GITEA_USERNAME`
4. Secret: `ryan`
5. Click **"Add secret"**
---
### 2. TAILSCALE_CLIENT_ID
**Purpose:** Allows GitHub Actions to connect to your Tailscale network (to reach Kubernetes)
**How to create:**
1. Go to: https://login.tailscale.com/admin/settings/oauth
2. Click **"Generate OAuth client"**
3. Description: `GitHub Actions - TurboVault`
4. Select tags: **`tag:ci`** (or create if it doesn't exist)
5. Copy the **Client ID**
**How to add to GitHub:**
1. Go to GitHub repo → Settings → Secrets and variables → Actions
2. Click **"New repository secret"**
3. Name: `TAILSCALE_CLIENT_ID`
4. Secret: Paste the Client ID
5. Click **"Add secret"**
---
### 3. TAILSCALE_CLIENT_SECRET
**Purpose:** OAuth secret for Tailscale connection
**How to get:**
(You got this when creating the OAuth client in step 3 above)
**How to add to GitHub:**
1. Go to GitHub repo → Settings → Secrets and variables → Actions
2. Click **"New repository secret"**
3. Name: `TAILSCALE_CLIENT_SECRET`
4. Secret: Paste the Client Secret
5. Click **"Add secret"**
---
### 4. KUBECONFIG
**Purpose:** Allows kubectl to deploy to your Kubernetes cluster
**How to create:**
```bash
# Encode your kubeconfig as base64
cat ~/.kube/config | base64 -w 0 > kubeconfig-base64.txt
# Copy the contents
cat kubeconfig-base64.txt
```
**How to add to GitHub:**
1. Go to GitHub repo → Settings → Secrets and variables → Actions
2. Click **"New repository secret"**
3. Name: `KUBECONFIG`
4. Secret: Paste the base64-encoded kubeconfig
5. Click **"Add secret"**
---
## Optional: Scoped Kubeconfig (More Secure)
Instead of using your full kubeconfig, create a limited service account:
```bash
# Create service account
kubectl create serviceaccount turbovault-deployer -n turbovault
# Create role with deployment permissions only
cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: turbovault-deployer
namespace: turbovault
rules:
- apiGroups: ["apps"]
resources: ["deployments"]
verbs: ["get", "list", "patch", "update"]
- apiGroups: [""]
resources: ["pods"]
verbs: ["get", "list"]
- apiGroups: ["apps"]
resources: ["deployments/status"]
verbs: ["get"]
EOF
# Bind role to service account
kubectl create rolebinding turbovault-deployer \
--role=turbovault-deployer \
--serviceaccount=turbovault:turbovault-deployer \
-n turbovault
# Get service account token (valid for 10 years)
kubectl create token turbovault-deployer -n turbovault --duration=87600h > token.txt
# Create minimal kubeconfig
cat <<EOF > deployer-kubeconfig.yaml
apiVersion: v1
kind: Config
clusters:
- cluster:
server: https://100.101.31.99:6443
insecure-skip-tls-verify: true
name: k3s
contexts:
- context:
cluster: k3s
namespace: turbovault
user: turbovault-deployer
name: k3s
current-context: k3s
users:
- name: turbovault-deployer
user:
token: $(cat token.txt)
EOF
# Encode for GitHub
cat deployer-kubeconfig.yaml | base64 -w 0 > deployer-kubeconfig-base64.txt
# Use this in KUBECONFIG secret
cat deployer-kubeconfig-base64.txt
```
This limits GitHub Actions to only deploying TurboVault, not full cluster access.
---
## Summary of Required Secrets
| Secret Name | Purpose | How to Get |
|-------------|---------|------------|
| `GITHUB_TOKEN` | Push to ghcr.io | Built-in (no setup needed!) |
| `TAILSCALE_CLIENT_ID` | Connect to Tailscale | Tailscale → OAuth clients |
| `TAILSCALE_CLIENT_SECRET` | Connect to Tailscale | Tailscale → OAuth clients |
| `KUBECONFIG` | Deploy to Kubernetes | `cat ~/.kube/config \| base64 -w 0` |
---
## Verifying Secrets
After adding all secrets, you should see 3 secrets in GitHub:
1. Go to: `https://github.com/ryankazokas/turbovault-app/settings/secrets/actions`
2. Verify all 3 are listed:
- ✅ TAILSCALE_CLIENT_ID
- ✅ TAILSCALE_CLIENT_SECRET
- ✅ KUBECONFIG
Note: `GITHUB_TOKEN` is automatic - you don't need to add it!
---
## Testing the Workflow
After secrets are configured:
```bash
# Create a test tag
git tag v0.0.1-test
git push origin v0.0.1-test
```
Watch the workflow at:
`https://github.com/ryan/turbovault-app/actions`
The workflow should:
1. ✅ Build Docker image
2. ✅ Push to Gitea registry (gitea.kazcloud.dev)
3. ✅ Connect to Tailscale
4. ✅ Deploy to Kubernetes
5. ✅ Wait for rollout to complete
---
## Troubleshooting
### "Error: authentication required" (Gitea)
- Check `GITEA_TOKEN` is set correctly
- Verify token has `write:package` scope
- Test: `docker login gitea.kazcloud.dev` with token
### "Error: Failed to connect to Tailscale"
- Check `TAILSCALE_CLIENT_ID` and `TAILSCALE_CLIENT_SECRET` are correct
- Verify OAuth client is active in Tailscale admin
- Check tags are configured correctly (tag:ci)
### "Error: Unable to connect to the server" (Kubernetes)
- Check `KUBECONFIG` secret is set correctly
- Verify base64 encoding (no line breaks with `-w 0`)
- Verify Tailscale connected (check logs)
- Test kubeconfig works: `kubectl --kubeconfig=<file> get pods -n turbovault`
### "Error: deployment not found"
- Make sure initial deployment is done first: `./scripts/deploy-k8s.sh`
- Workflow only updates existing deployments, doesn't create them
---
## Security Best Practices
✅ **DO:**
- Use service account with minimal permissions (recommended)
- Rotate tokens regularly
- Use OAuth for Tailscale (not auth keys)
- Only enable workflows on protected branches
❌ **DON'T:**
- Share secrets in code or documentation
- Use admin kubeconfig if possible
- Commit secrets to git
- Use long-lived Tailscale auth keys
---
## Next Steps
After configuring secrets:
1. Read [DEPLOYMENT.md](DEPLOYMENT.md) for initial deployment
2. Test workflow with a tag push
3. Monitor Actions tab for build status
Questions? Check the GitHub Actions logs for detailed error messages.