Back to Details

caddy-subdomain-add

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Add Subdomain Skill

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.
最简请求： "Add grafana running on port 3001"
完整请求示例：
Add a new subdomain:
- Name: Grafana Dashboard
- Subdomain: grafana
- Backend: 192.168.68.135:3001
- HTTPS: yes
- Auth: yes
结果： 服务可通过https://grafana.temet.ai访问，并受Google OAuth保护。

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
  1. 何时使用此Skill
  2. 该Skill的功能
  3. 操作步骤
    • 3.1 收集服务信息
    • 3.2 验证输入
    • 3.3 确定配置
    • 3.4 添加到domains.toml
    • 3.5 应用更改
    • 3.6 手动隧道配置步骤
    • 3.7 验证设置
  4. 支持文件
  5. 预期结果
  6. 集成点
  7. 预期收益
  8. 要求
  9. 注意事项

When to Use This Skill

何时使用此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?"
明确触发指令：
  • "Add a subdomain for [service]"
  • "Create subdomain [name]"
  • "Add [service] to the network"
  • "Set up reverse proxy for [service]"
  • "Expose [service] externally"
隐含触发场景：
  • 配置需要外部访问的新Docker容器
  • 安装需要HTTPS的新软件
  • 配置用于远程访问的新IoT设备
调试触发指令：
  • "Why can't I access [service].temet.ai?"
  • "How do I add HTTPS to my service?"

What This Skill Does

该Skill的功能

  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
  1. 收集信息 - 通过交互式提问获取服务相关详情
  2. 验证输入 - 检查子域名格式、IP地址和端口
  3. 建议默认值 - 根据服务类型推荐设置
  4. 配置domains.toml - 添加包含正确选项的服务条目
  5. 应用更改 - 运行manage-domains.sh生成配置
  6. 提供隧道配置说明 - 引导用户完成Cloudflare手动步骤
  7. 验证设置 - 测试DNS、HTTPS和认证

Instructions

操作步骤

3.1 Gather Service Information

3.1 收集服务信息

Ask the user for the following details (provide examples):
Required:
FieldQuestionExample
nameWhat is the display name for this service?"Grafana Dashboard"
subdomainWhat subdomain do you want? (without .temet.ai)"grafana"
backendWhere is the service running? (IP:port or container:port)"192.168.68.135:3001" or "grafana:3000"
Service Type (for intelligent defaults):
TypeDescription
webStandard web application (default settings)
dockerDocker container on the same network
iotIoT device (needs header stripping)
apiAPI service (may need custom headers)
externalService on different machine on LAN
向用户询问以下详情（提供示例）：
必填项：
字段问题示例
name该服务的显示名称是什么？"Grafana Dashboard"
subdomain你想要的子域名是什么？（不含.temet.ai）"grafana"
backend服务运行在何处？（IP:端口 或 容器:端口）"192.168.68.135:3001" 或 "grafana:3000"
服务类型（用于智能默认值）：
类型描述
web标准Web应用（默认设置）
docker同一网络中的Docker容器
iotIoT设备（需要剥离请求头）
apiAPI服务（可能需要自定义请求头）
external局域网中另一台机器上的服务

3.2 Validate Input

3.2 验证输入

Use the validation script to check subdomain and backend:
bash
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
使用验证脚本检查子域名和后端地址：
bash
python3 .claude/skills/add-subdomain/scripts/validate-subdomain.py grafana 192.168.68.135:3001
规则：
  • 子域名：小写字母、数字和连字符，最多63个字符，首尾不能为连字符
  • 后端地址：IP:端口（例如 
    192.168.68.135:3001
    ）或容器:端口（例如 
    grafana:3000
    ）
  • 添加前检查是否存在重复

3.3 Determine Configuration

3.3 确定配置

Use service type to select defaults (see 
references/reference.md
for full matrix):
Typeenable_httpsenable_httprequire_authSpecial
webtruefalsetrueproxy_headers
dockertruefalsetruecontainer:port backend
iotfalsetruetruestrip_cf_headers
externaltruefalsetrueLAN IP backend
self-signedtruefalsetruetls_insecure
publicfalsetruefalseno auth
根据服务类型选择默认值（完整配置矩阵请参考
references/reference.md
）：
类型enable_httpsenable_httprequire_auth特殊设置
webtruefalsetrueproxy_headers
dockertruefalsetruecontainer:port后端
iotfalsetruetruestrip_cf_headers
externaltruefalsetrueLAN IP后端
self-signedtruefalsetruetls_insecure
publicfalsetruefalse无认证

3.4 Add to domains.toml

3.4 添加到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:
toml
[[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}
位置： 
/home/dawiddutoit/projects/network/domains.toml
步骤：
  1. 读取当前domains.toml文件
  2. 找到合适的章节（核心基础设施、IoT设备或实用服务）
  3. 在高级配置章节之前追加新服务条目
  4. 使用编辑工具添加条目
模板：
toml
[[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

3.5 应用更改

Run the management script:
bash
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
运行管理脚本：
bash
cd /home/dawiddutoit/projects/network && ./scripts/manage-domains.sh apply
预期输出：
=== 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

3.6 手动隧道配置步骤

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:
Service TypeTunnel URL
HTTPS enabled
https://caddy:443
HTTP only (IoT)Direct to service: 
http://192.168.68.XXX:80
Docker container
https://caddy:443
or 
http://caddy:80
提供清晰的Cloudflare Tunnel配置说明：
需要手动操作：添加Cloudflare Tunnel路由

1. 访问：https://one.dash.cloudflare.com
2. 导航至：Access -> Tunnels
3. 点击隧道："pi-home"（或你的隧道名称）
4. 点击“Configure” -> “Public Hostname” -> “Add a public hostname”
5. 输入：
   - Subdomain: {subdomain}
   - Domain: temet.ai
   - Type: {HTTP或HTTPS}
   - URL: {backend_for_tunnel}

   对于HTTPS服务：https://caddy:443
   对于仅HTTP服务：http://caddy:80 或直接指向服务

6. 点击“Save hostname"
隧道后端选择：
服务类型隧道URL
启用HTTPS
https://caddy:443
仅HTTP（IoT）直接指向服务：
http://192.168.68.XXX:80
Docker容器
https://caddy:443
或 
http://caddy:80

3.7 Verify Setup

3.7 验证设置

After tunnel configuration, run verification:
1. DNS Resolution (local):
bash
dig @192.168.68.135 {subdomain}.temet.ai +short
Expected: Returns the dns_ip configured
2. HTTPS Certificate:
bash
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:
bash
curl -I https://{subdomain}.temet.ai
Expected: HTTP/2 200 or 302 (redirect to login)
4. Service List:
bash
./scripts/manage-domains.sh list
Expected: New service appears in list
隧道配置完成后，运行验证步骤：
1. DNS解析（本地）：
bash
dig @192.168.68.135 {subdomain}.temet.ai +short
预期结果：返回配置的dns_ip
2. HTTPS证书：
bash
echo | openssl s_client -servername {subdomain}.temet.ai \
  -connect {subdomain}.temet.ai:443 2>/dev/null | \
  openssl x509 -noout -dates -issuer
预期结果：来自Let's Encrypt的有效证书
3. HTTP响应：
bash
curl -I https://{subdomain}.temet.ai
预期结果：HTTP/2 200 或 302（重定向至登录页）
4. 服务列表：
bash
./scripts/manage-domains.sh list
预期结果：新服务出现在列表中

Supporting Files

支持文件

FilePurpose
references/reference.md
Complete configuration options reference
examples/examples.md
Common service configuration examples
scripts/validate-subdomain.py
Pre-validation of subdomain and backend
Validation Script Usage:
bash
python3 .claude/skills/add-subdomain/scripts/validate-subdomain.py grafana 192.168.68.135:3001
文件用途
references/reference.md
完整配置选项参考
examples/examples.md
常见服务配置示例
scripts/validate-subdomain.py
子域名和后端地址预验证
验证脚本使用方法：
bash
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
成功：
  • 服务条目已添加到domains.toml
  • 已重新生成包含新服务块的Caddyfile
  • 已创建Pi-hole DNS条目
  • 已创建Cloudflare Access应用（如果require_auth=true）
  • Caddy已重新加载并获取新证书
  • 服务可通过https://{subdomain}.temet.ai访问
部分成功：
  • 配置已应用但未配置隧道（已向用户发出提醒）
  • 证书正在颁发中（可能需要1-2分钟）
失败迹象：
  • domains.toml语法错误 -> 验证并修复 �- Caddy重载失败 -> 检查Caddyfile语法
  • DNS无法解析 -> 检查Pi-hole日志
  • 证书错误 -> 检查Cloudflare API令牌

Integration Points

集成点

This skill integrates with:
ComponentPurpose
domains.toml
Central configuration source
manage-domains.sh
Applies configuration changes
generate-caddyfile.py
Generates Caddyfile from domains.toml
generate-pihole-dns.py
Updates Pi-hole DNS entries
sync-cloudflare-access.py
Creates/updates Access applications
Cloudflare TunnelManual public hostname configuration
Related Skills:
  • setup-new-domain-services
    - For adding new top-level domains
  • troubleshoot-ssl-certificates
    - For certificate issues
  • diagnose-cloudflare-access
    - For authentication problems
此Skill与以下组件集成：
组件用途
domains.toml
中央配置源
manage-domains.sh
应用配置更改
generate-caddyfile.py
从domains.toml生成Caddyfile
generate-pihole-dns.py
更新Pi-hole DNS条目
sync-cloudflare-access.py
创建/更新Access应用
Cloudflare Tunnel手动公共主机名配置
相关Skill：
  • setup-new-domain-services
    - 用于添加新顶级域名
  • troubleshoot-ssl-certificates
    - 用于证书问题排查
  • diagnose-cloudflare-access
    - 用于认证问题排查

Expected Benefits

预期收益

MetricBeforeAfter
Time to add service15-30 min (manual)2-5 min (guided)
Configuration errorsCommon (manual editing)Rare (validated)
Documentation neededMultiple filesSingle skill reference
ConsistencyVariableStandardized
指标之前之后
添加服务所需时间15-30分钟（手动）2-5分钟（引导式）
配置错误常见（手动编辑）极少（已验证）
所需文档多个文件单个Skill参考
一致性参差不齐标准化

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)
环境：
  • 运行中的Docker，包含caddy、pihole容器
  • 已连接的Cloudflare tunnel
  • 包含API令牌的有效
    .env
    文件
所需工具：
  • 读写编辑权限（针对domains.toml）
  • Bash（用于执行应用脚本和验证命令）
  • Grep（用于重复检查）

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
  • 不要添加重复子域名（先检查）
  • 子域名不要使用大写字母
  • 不要忘记手动隧道配置步骤
  • 应用更改后不要跳过验证
  • Linux系统上不要使用
    host.docker.internal
    （使用实际IP）
  • 除非特别需要，否则不要同时启用HTTPS和HTTP
  • 除非服务必须公开，否则不要设置require_auth=false
  • 对于使用自签名证书的服务，不要跳过tls_insecure设置

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
  • 树莓派IP通常为
    192.168.68.135
    （适用于运行在树莓派上的服务）
  • IoT设备需要设置
    strip_cf_headers = true
    才能正常工作
  • 使用自签名证书的服务需要设置
    tls_insecure = true
  • 根路径重定向（如
    /admin/
    ）使用
    root_redirect
    选项
  • 隧道步骤为手动操作，因为Cloudflare Tunnel的API较为复杂
  • 始终运行
    ./scripts/manage-domains.sh list
    查看当前服务列表