Add Subdomain Skill

Interactive guide for adding new subdomains to the network infrastructure.

Quick Start

Minimal Request: "Add grafana running on port 3001"

Full Request Example:

Add a new subdomain:
- Name: Grafana Dashboard
- Subdomain: grafana
- Backend: 192.168.68.135:3001
- HTTPS: yes
- Auth: yes

Result: Service accessible at https://grafana.temet.ai with Google OAuth protection.

Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. Instructions
   • 3.1 Gather Service Information
   • 3.2 Validate Input
   • 3.3 Determine Configuration
   • 3.4 Add to domains.toml
   • 3.5 Apply Changes
   • 3.6 Manual Tunnel Step
   • 3.7 Verify Setup
4. Supporting Files
5. Expected Outcomes
6. Integration Points
7. Expected Benefits
8. Requirements
9. Red Flags to Avoid

When to Use This Skill

Explicit Triggers:

• "Add a subdomain for [service]"
• "Create subdomain [name]"
• "Add [service] to the network"
• "Set up reverse proxy for [service]"
• "Expose [service] externally"

Implicit Triggers:

• Setting up a new Docker container that needs external access
• Installing new software that requires HTTPS
• Configuring a new IoT device for remote access

Debugging Triggers:

• "Why can't I access [service].temet.ai?"
• "How do I add HTTPS to my service?"

What This Skill Does

1. Gathers Information - Asks interactive questions about the service
2. Validates Input - Checks subdomain format, IP addresses, ports
3. Suggests Defaults - Recommends settings based on service type
4. Configures domains.toml - Adds service entry with correct options
5. Applies Changes - Runs manage-domains.sh to generate configs
6. Provides Tunnel Instructions - Guides user through manual Cloudflare step
7. Verifies Setup - Tests DNS, HTTPS, and authentication

Instructions

3.1 Gather Service Information

Ask the user for the following details (provide examples):

Required:

Service Type (for intelligent defaults):

3.2 Validate Input

Use the validation script to check subdomain and backend:

python3 .claude/skills/add-subdomain/scripts/validate-subdomain.py grafana 192.168.68.135:3001

Rules:

• Subdomain: lowercase alphanumeric + hyphens, max 63 chars, no leading/trailing hyphens
• Backend: IP:port (e.g., 192.168.68.135:3001) or container:port (e.g., grafana:3000)
• Check for duplicates before adding

3.3 Determine Configuration

Use service type to select defaults (see references/reference.md for full matrix):

3.4 Add to domains.toml

Location: /home/dawiddutoit/projects/network/domains.toml

Steps:

1. Read current domains.toml
2. Find appropriate section (Core Infrastructure, IoT Devices, or Utility Services)
3. Append new service entry before the Advanced Configuration section
4. Use Edit tool to add the entry

Template:

[[services]]
name = "{name}"
subdomain = "{subdomain}"
backend = "{backend}"
enable_https = {enable_https}
enable_http = {enable_http}
dns_ip = "{dns_ip}"
require_auth = {require_auth}
{optional_fields}

3.5 Apply Changes

Run the management script:

cd /home/dawiddutoit/projects/network && ./scripts/manage-domains.sh apply

Expected output:

=== Applying Domain Configuration ===

Validating configuration...
[checkmark] Configuration is valid

Generating Caddyfile...
[checkmark] Caddyfile generated successfully

Updating Pi-hole DNS entries...
[checkmark] Pi-hole DNS entries updated

Syncing Cloudflare Access applications...
[checkmark] Cloudflare Access synced successfully

Reloading Caddy configuration...
[checkmark] Caddy reloaded successfully

Restarting Pi-hole to apply DNS changes...
[checkmark] Pi-hole restarted successfully

3.6 Manual Tunnel Step

Provide clear instructions for the Cloudflare Tunnel configuration:

MANUAL STEP REQUIRED: Add Cloudflare Tunnel Route

1. Go to: https://one.dash.cloudflare.com
2. Navigate to: Access -> Tunnels
3. Click on tunnel: "pi-home" (or your tunnel name)
4. Click "Configure" -> "Public Hostname" -> "Add a public hostname"
5. Enter:
   - Subdomain: {subdomain}
   - Domain: temet.ai
   - Type: {HTTP or HTTPS}
   - URL: {backend_for_tunnel}

   For HTTPS services: https://caddy:443
   For HTTP-only services: http://caddy:80 or direct to service

6. Click "Save hostname"

Tunnel Backend Selection:

3.7 Verify Setup

After tunnel configuration, run verification:

1. DNS Resolution (local):

dig @192.168.68.135 {subdomain}.temet.ai +short

Expected: Returns the dns_ip configured

2. HTTPS Certificate:

echo | openssl s_client -servername {subdomain}.temet.ai \
  -connect {subdomain}.temet.ai:443 2>/dev/null | \
  openssl x509 -noout -dates -issuer

Expected: Valid certificate from Let's Encrypt

3. HTTP Response:

curl -I https://{subdomain}.temet.ai

Expected: HTTP/2 200 or 302 (redirect to login)

4. Service List:

./scripts/manage-domains.sh list

Expected: New service appears in list

Supporting Files

Validation Script Usage:

python3 .claude/skills/add-subdomain/scripts/validate-subdomain.py grafana 192.168.68.135:3001

Expected Outcomes

Success:

• Service entry added to domains.toml
• Caddyfile regenerated with new service block
• Pi-hole DNS entry created
• Cloudflare Access application created (if require_auth=true)
• Caddy reloaded with new certificate
• Service accessible at https://{subdomain}.temet.ai

Partial Success:

• Configuration applied but tunnel not configured (user reminder provided)
• Certificate pending (may take 1-2 minutes)

Failure Indicators:

• domains.toml syntax error -> validate and fix
• Caddy reload failed -> check Caddyfile syntax
• DNS not resolving -> check Pi-hole logs
• Certificate error -> check Cloudflare API token

Integration Points

This skill integrates with:

Related Skills:

• setup-new-domain-services - For adding new top-level domains
• troubleshoot-ssl-certificates - For certificate issues
• diagnose-cloudflare-access - For authentication problems

Expected Benefits

Requirements

Environment:

• Docker running with caddy, pihole containers
• Cloudflare tunnel connected
• Valid .env with API tokens

Tools needed:

• Read, Write, Edit (for domains.toml)
• Bash (for apply script and verification)
• Grep (for duplicate checking)

Red Flags to Avoid

• Do not add duplicate subdomains (check first)
• Do not use uppercase in subdomain names
• Do not forget the manual tunnel step
• Do not skip verification after apply
• Do not use host.docker.internal on Linux (use actual IP)
• Do not enable both HTTPS and HTTP unless specifically needed
• Do not set require_auth=false unless service must be public
• Do not skip tls_insecure for services with self-signed certs

Notes

• The Pi IP is typically 192.168.68.135 for services running on the Pi
• IoT devices need strip_cf_headers = true to work properly
• Services with self-signed certs need tls_insecure = true
• Root redirects (like /admin/) use root_redirect option
• The tunnel step is manual because Cloudflare API for tunnels is complex
• Always run ./scripts/manage-domains.sh list to see current services