diff --git a/.cspell/custom-dictionary-workspace.txt b/.cspell/custom-dictionary-workspace.txt index b308d53..dc1786f 100644 --- a/.cspell/custom-dictionary-workspace.txt +++ b/.cspell/custom-dictionary-workspace.txt @@ -7,6 +7,7 @@ coredns crds envsubst externaldns +glddns gomplate Jellyfin KUBECONFIG @@ -24,4 +25,5 @@ PGDATA SAMEORIGIN traefik USEPATH +vxlan websecure diff --git a/README.md b/README.md index ea80577..994031d 100644 --- a/README.md +++ b/README.md @@ -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! diff --git a/dev/TODO.md b/dev/TODO.md index 5a66d81..887b243 100644 --- a/dev/TODO.md +++ b/dev/TODO.md @@ -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) diff --git a/docs/APPS.md b/docs/APPS.md deleted file mode 100644 index e0cc1b8..0000000 --- a/docs/APPS.md +++ /dev/null @@ -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]` \ No newline at end of file diff --git a/docs/SETUP.md b/docs/SETUP.md index ab5b24b..9a1f03e 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -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. \ No newline at end of file +Welcome to your personal cloud journey! You now have the foundation for hosting your own services and taking control of your digital life. diff --git a/docs/lan-routers/GL-iNet.md b/docs/lan-routers/GL-iNet.md new file mode 100644 index 0000000..822d143 --- /dev/null +++ b/docs/lan-routers/GL-iNet.md @@ -0,0 +1,3 @@ +# GL-iNet LAN Router Setup + +TBD diff --git a/docs/troubleshooting/VISIBILITY.md b/docs/troubleshooting/visibility.md similarity index 100% rename from docs/troubleshooting/VISIBILITY.md rename to docs/troubleshooting/visibility.md