CSTF/wild-cloud
1
1
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

Update documentation for improved setup guidance

Browse Source
This commit is contained in:
Paul Payne
2025-05-18 15:42:22 -07:00
parent 9446c7ce6f
commit e16c0eac04
7 changed files with 11 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.cspell/custom-dictionary-workspace.txt
View File

@@ -7,6 +7,7 @@ coredns
crds
envsubst
externaldns
glddns
gomplate
Jellyfin
KUBECONFIG
@@ -24,4 +25,5 @@ PGDATA
SAMEORIGIN
traefik
USEPATH
vxlan
websecure

2
README.md
View File

@@ -52,7 +52,7 @@ The possibilities are endless! Here are just a few ideas:
For detailed instructions, check out our documentation:
- [**Setup Guide**](./docs/SETUP.md) - Step-by-step instructions for setting up your infrastructure
- [**Applications Guide**](./docs/APPS.md) - How to deploy and manage applications on your cloud
- [**Applications Guide**](./apps/README.md) - How to deploy and manage applications on your cloud
- [**Maintenance Guide**](./docs/MAINTENANCE.md) - Troubleshooting, backups, updates, and security
After setup, visit your dashboard at `https://dashboard.internal.yourdomain.com` to start exploring your new personal cloud infrastructure!

1
dev/TODO.md
View File

@@ -5,6 +5,7 @@
## Infrastructure Setup Cleanup
- Put Cloudflare-specific setup in a `dns_providers` directory.
- Standardize metallb allocation in coredns-service.yaml and traefik-service.yaml.
- Remove helm dependency in preference of kustomize.
- Figure out Traefik IngressRoute CRD. Is it better than just Ingress? (dashboard uses IngressRoute currently, example-admin uses Ingress)

165
docs/APPS.md
View File

@@ -1,165 +0,0 @@
# Deploying Applications
Once you have your personal cloud infrastructure up and running, you'll want to start deploying applications. This guide explains how to deploy and manage applications on your infrastructure.
## Application Charts
The `/charts` directory contains curated Helm charts for common applications that are ready to deploy on your personal cloud.
### Available Charts
| Chart | Description | Internal/Public |
|-------|-------------|----------------|
| mariadb | MariaDB database for applications | Internal |
| postgres | PostgreSQL database for applications | Internal |
### Installing Charts
Use the `bin/helm-install` script to easily deploy charts with the right configuration:
```bash
# Install PostgreSQL
./bin/helm-install postgres
# Install MariaDB
./bin/helm-install mariadb
```
The script automatically:
- Uses values from your environment variables
- Creates the necessary namespace
- Configures storage and networking
- Sets up appropriate secrets
### Customizing Chart Values
Each chart can be customized by:
1. Editing environment variables in your `.env` file
2. Creating a custom values file:
```bash
# Create a custom values file
cp charts/postgres/values.yaml my-postgres-values.yaml
nano my-postgres-values.yaml
# Install with custom values
./bin/helm-install postgres --values my-postgres-values.yaml
```
### Creating Your Own Charts
You can add your own applications to the charts directory:
1. Create a new directory: `mkdir -p charts/my-application`
2. Add the necessary templates and values
3. Document any required environment variables
## Deploying Custom Services
For simpler applications or services without existing charts, use the `deploy-service` script to quickly deploy from templates.
### Service Types
The system supports four types of services:
1. **Public** - Accessible from the internet
2. **Internal** - Only accessible within your local network
3. **Database** - Internal database services
4. **Microservice** - Services that are only accessible by other services
### Deployment Examples
```bash
# Deploy a public blog using Ghost
./bin/deploy-service --type public --name blog --image ghost:4.12 --port 2368
# Deploy an internal admin dashboard
./bin/deploy-service --type internal --name admin --image my-admin:v1 --port 8080
# Deploy a database service
./bin/deploy-service --type database --name postgres --image postgres:15 --port 5432
# Deploy a microservice
./bin/deploy-service --type microservice --name auth --image auth-service:v1 --port 9000
```
### Service Structure
When you deploy a service, a directory is created at `services/[service-name]/` containing:
- `service.yaml` - The Kubernetes manifest for your service
You can modify this file directly and reapply it with `kubectl apply -f services/[service-name]/service.yaml` to update your service.
## Accessing Services
Services are automatically configured with proper URLs and TLS certificates.
### URL Patterns
- **Public services**: `https://[service-name].[domain]`
- **Internal services**: `https://[service-name].internal.[domain]`
- **Microservices**: `https://[service-name].svc.[domain]`
- **Databases**: `[service-name].[namespace].svc.cluster.local:[port]`
### Dashboard Access
Access the Kubernetes Dashboard at `https://dashboard.internal.[domain]`:
```bash
# Get the dashboard token
./bin/dashboard-token
```
### Service Management
Monitor your running services with:
```bash
# List all services
kubectl get services -A
# View detailed information about a service
kubectl describe service [service-name] -n [namespace]
# Check pods for a service
kubectl get pods -n [namespace] -l app=[service-name]
# View logs for a service
kubectl logs -n [namespace] -l app=[service-name]
```
## Advanced Configuration
### Scaling Services
Scale your services by editing the deployment:
```bash
kubectl scale deployment [service-name] --replicas=3 -n [namespace]
```
### Adding Environment Variables
Add environment variables to your service by editing the service YAML file and adding entries to the `env` section:
```yaml
env:
- name: DATABASE_URL
value: "postgres://user:password@postgres:5432/db"
```
### Persistent Storage
For services that need persistent storage, add a PersistentVolumeClaim to your service YAML.
## Troubleshooting
If a service isn't working correctly:
1. Check pod status: `kubectl get pods -n [namespace]`
2. View logs: `kubectl logs [pod-name] -n [namespace]`
3. Describe the pod: `kubectl describe pod [pod-name] -n [namespace]`
4. Verify the service: `kubectl get svc [service-name] -n [namespace]`
5. Check the ingress: `kubectl get ingress [service-name] -n [namespace]`

3
docs/SETUP.md
View File

@@ -29,6 +29,7 @@ source load-env.sh
```
Important variables to set in your `.env` file:
- `DOMAIN`: Your domain name (e.g., `cloud.example.com`)
- `EMAIL`: Your email for Let's Encrypt certificates
- `CLOUDFLARE_API_TOKEN`: If using Cloudflare for DNS
@@ -58,6 +59,7 @@ One command sets up your entire cloud infrastructure:
This installs and configures:
- **MetalLB**: Provides IP addresses for services
- **LongHorn**: Provides distributed block storage on the cluster
- **Traefik**: Handles ingress (routing) with automatic HTTPS
- **cert-manager**: Manages TLS certificates automatically
- **CoreDNS**: Provides internal DNS resolution
@@ -93,6 +95,7 @@ Run the validation script to ensure everything is working correctly:
```
This script checks:
- All infrastructure components
- DNS resolution
- Service connectivity

3
docs/lan-routers/GL-iNet.md Normal file
View File

@@ -0,0 +1,3 @@
# GL-iNet LAN Router Setup
TBD

0
docs/troubleshooting/VISIBILITY.md → docs/troubleshooting/visibility.md
View File