# Taskserv Quick Guide\n\n## 🚀 Quick Start\n\n### Create a New Taskserv (Interactive)\n\n```\nnu provisioning/tools/create-taskserv-helper.nu interactive\n```\n\n### Create a New Taskserv (Direct)\n\n```\nnu provisioning/tools/create-taskserv-helper.nu create my-api \\n  --category development \\n  --port 8080 \\n  --description "My REST API service"\n```\n\n## 📋 5-Minute Setup\n\n### 1. Choose Your Method\n\n- **Interactive**: `nu provisioning/tools/create-taskserv-helper.nu interactive`\n- **Command Line**: Use the direct command above\n- **Manual**: Follow the structure guide below\n\n### 2. Basic Structure\n\n```\nmy-service/\n├── nickel/\n│   ├── manifest.toml   # Package definition\n│   ├── my-service.ncl  # Main schema\n│   └── version.ncl     # Version info\n├── default/\n│   ├── defs.toml       # Default config\n│   └── install-*.sh    # Install script\n└── README.md           # Documentation\n```\n\n### 3. Essential Files\n\n**manifest.toml** (package definition):\n\n```\n[package]\nname = "my-service"\nversion = "1.0.0"\ndescription = "My service"\n\n[dependencies]\nk8s = { oci = "oci://ghcr.io/kcl-lang/k8s", tag = "1.30" }\n```\n\n**my-service.ncl** (main schema):\n\n```\nlet MyService = {\n    name | String,\n    version | String,\n    port | Number,\n    replicas | Number,\n} in\n\n{\n    my_service_config = {\n        name = "my-service",\n        version = "latest",\n        port = 8080,\n        replicas = 1,\n    }\n}\n```\n\n### 4. Test Your Taskserv\n\n```\n# Discover your taskserv\nnu -c "use provisioning/core/nulib/taskservs/discover.nu *; get-taskserv-info my-service"\n\n# Test layer resolution\nnu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution my-service wuji upcloud"\n\n# Deploy with check\nprovisioning/core/cli/provisioning taskserv create my-service --infra wuji --check\n```\n\n## 🎯 Common Patterns\n\n### Web Service\n\n```\nlet WebService = {\n    name | String,\n    version | String | default = "latest",\n    port | Number | default = 8080,\n    replicas | Number | default = 1,\n    ingress | {\n        enabled | Bool | default = true,\n        hostname | String,\n        tls | Bool | default = false,\n    },\n    resources | {\n        cpu | String | default = "100m",\n        memory | String | default = "128Mi",\n    },\n} in\nWebService\n```\n\n### Database Service\n\n```\nlet DatabaseService = {\n    name | String,\n    version | String | default = "latest",\n    port | Number | default = 5432,\n    persistence | {\n        enabled | Bool | default = true,\n        size | String | default = "10Gi",\n        storage_class | String | default = "ssd",\n    },\n    auth | {\n        database | String | default = "app",\n        username | String | default = "user",\n        password_secret | String,\n    },\n} in\nDatabaseService\n```\n\n### Background Worker\n\n```\nlet BackgroundWorker = {\n    name | String,\n    version | String | default = "latest",\n    replicas | Number | default = 1,\n    job | {\n        schedule | String | optional,  # Cron format for scheduled jobs\n        parallelism | Number | default = 1,\n        completions | Number | default = 1,\n    },\n    resources | {\n        cpu | String | default = "500m",\n        memory | String | default = "512Mi",\n    },\n} in\nBackgroundWorker\n```\n\n## 🛠️ CLI Shortcuts\n\n### Discovery\n\n```\n# List all taskservs\nnu -c "use provisioning/core/nulib/taskservs/discover.nu *; discover-taskservs | select name group"\n\n# Search taskservs\nnu -c "use provisioning/core/nulib/taskservs/discover.nu *; search-taskservs redis"\n\n# Show stats\nnu -c "use provisioning/workspace/tools/layer-utils.nu *; show_layer_stats"\n```\n\n### Development\n\n```\n# Check Nickel syntax\nnickel typecheck provisioning/extensions/taskservs/{category}/{name}/schemas/{name}.ncl\n\n# Generate configuration\nprovisioning/core/cli/provisioning taskserv generate {name} --infra {infra}\n\n# Version management\nprovisioning/core/cli/provisioning taskserv versions {name}\nprovisioning/core/cli/provisioning taskserv check-updates\n```\n\n### Testing\n\n```\n# Dry run deployment\nprovisioning/core/cli/provisioning taskserv create {name} --infra {infra} --check\n\n# Layer resolution debug\nnu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution {name} {infra} {provider}"\n```\n\n## 📚 Categories Reference\n\n| Category | Examples | Use Case |\n| ---------- | ---------- | ---------- |\n| **container-runtime** | containerd, crio, podman | Container runtime engines |\n| **databases** | postgres, redis | Database services |\n| **development** | coder, gitea, desktop | Development tools |\n| **infrastructure** | kms, webhook, os | System infrastructure |\n| **kubernetes** | kubernetes | Kubernetes orchestration |\n| **networking** | cilium, coredns, etcd | Network services |\n| **storage** | rook-ceph, external-nfs | Storage solutions |\n\n## 🔧 Troubleshooting\n\n### Taskserv Not Found\n\n```\n# Check if discovered\nnu -c "use provisioning/core/nulib/taskservs/discover.nu *; discover-taskservs | where name == my-service"\n\n# Verify kcl.mod exists\nls provisioning/extensions/taskservs/{category}/my-service/kcl/kcl.mod\n```\n\n### Layer Resolution Issues\n\n```\n# Debug resolution\nnu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution my-service wuji upcloud"\n\n# Check template exists\nls provisioning/workspace/templates/taskservs/{category}/my-service.ncl\n```\n\n### Nickel Syntax Errors\n\n```\n# Check syntax\nnickel typecheck provisioning/extensions/taskservs/{category}/my-service/schemas/my-service.ncl\n\n# Format code\nnickel format provisioning/extensions/taskservs/{category}/my-service/schemas/\n```\n\n## 💡 Pro Tips\n\n1. **Use existing taskservs as templates** - Copy and modify similar services\n2. **Test with --check first** - Always use dry run before actual deployment\n3. **Follow naming conventions** - Use kebab-case for consistency\n4. **Document thoroughly** - Good docs save time later\n5. **Version your schemas** - Include version.ncl for compatibility tracking\n\n## 🔗 Next Steps\n\n1. Read the full [Taskserv Developer Guide](TASKSERV_DEVELOPER_GUIDE.md)\n2. Explore existing taskservs in `provisioning/extensions/taskservs/`\n3. Check out templates in `provisioning/workspace/templates/taskservs/`\n4. Join the development community for support