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]`

5
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
@@ -110,4 +113,4 @@ Now that your personal cloud is running, consider:
- Deploying applications like Nextcloud, Home Assistant, or Gitea
- Exploring the Kubernetes Dashboard to monitor your services
Welcome to your personal cloud journey! You now have the foundation for hosting your own services and taking control of your digital life.
Welcome to your personal cloud journey! You now have the foundation for hosting your own services and taking control of your digital life.

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