--- name: mittwald-zerodeploy description: Deploy an arbitrary application from your local machine or a Git repository to mittwald mStudio. Use when the user mentions "deploy to Mittwald", "move to mStudio", "Container Hosting auf Mittwald", "stack_deploy", or asks for help deploying a workload (K8s, Docker Compose, VPS, another hoster, another mStudio project) onto Mittwald. Source is open, target is always mStudio. --- # mittwald-zerodeploy Zero-config deployment to mittwald mStudio container hosting using Railpack build inference. --- ## Description This skill guides users through deploying containerized applications to mittwald mStudio **without requiring Docker knowledge**. The workflow uses Railpack to automatically detect project types and generate build plans, then deploys via the mittwald CLI or GitHub Actions. **Perfect for**: Developers who want to deploy quickly without writing Dockerfiles. **Not for**: DevOps teams needing explicit container definitions (use `deploy-container-action` instead). --- ## When to use this skill Trigger this skill when the user wants to: - Deploy an app to mittwald without writing a Dockerfile - Set up automated deployment with GitHub Actions to mittwald - Troubleshoot Railpack-based deployment failures - Transition from local CLI testing to CI/CD automation - Fix issues with faulty AI-generated Dockerfiles - Understand why their deployment isn't working --- ## Workflow ### Phase 1: Local Testing (CLI) **Goal**: Validate the deployment locally before setting up automation. 1. **Load** `playbooks/01-provision-target.md` - Verify mStudio project exists and user has API token - Confirm project ID is configured or can be passed explicitly - Check CLI is installed and authenticated 2. **Load** `playbooks/02-cli-deploy-local.md` - Run `mw experimental deploy` from project root - Handle environment variables via `--env` or `--env-file` - Parse deployment output for URL and container ID - Verify the app is reachable 3. **Load** `playbooks/05-verify.md` - Check container status in mStudio web UI - Test HTTP endpoints and validate responses - Confirm environment variables are applied correctly ### Phase 2: Automation (GitHub Actions) **Goal**: Set up continuous deployment after local testing succeeds. 1. **Load** `playbooks/03-setup-github-action.md` - Create `.github/workflows/zerodeploy.yml` - Configure GitHub secrets (`MITTWALD_API_TOKEN`, `MITTWALD_PROJECT_ID`) - Handle runtime secrets via workflow `.env` generation - Test with manual workflow dispatch 2. **Test automated deployment** - Trigger workflow manually - Monitor workflow logs for errors 3. **Load** `playbooks/05-verify.md` again - Confirm automated deployment produces same result as CLI ### Troubleshooting (As Needed) **When deployment fails or behaves unexpectedly:** - **Load** `playbooks/04-troubleshoot-deployment.md` - Guide user to mStudio web UI logs - Identify common error patterns - Check for faulty Dockerfiles to delete - Reconfigure ports if needed **When encountering the 3 critical gotchas:** - **Load** `references/pitfalls.md` - Faulty pre-existing Dockerfiles - Hidden port configurations - Exotic projects that won't work with Railpack **When stuck after 2-3 attempts:** - **Load** `references/when-to-escalate.md` - Recognize escalation triggers - Document errors for handoff - Avoid endless iteration --- ## Critical References (Load on Demand) ### Build & Detection Issues - `references/railpack-overview.md` - when Railpack can't detect project type or build fails ### Configuration Issues - `references/secrets-management.md` - when handling API keys, database passwords, or `.env` files - `references/port-configuration.md` - when app won't respond on expected port or ingress issues occur ### Failure Patterns - `references/pitfalls.md` - the 3 most common gotchas with solutions - `references/when-to-escalate.md` - when to stop iterating and hand off to DevOps --- ## Core Constraints ### Workflow Progression - ✅ **Always test locally first** with `mw experimental deploy` - ✅ **Only automate when stable** - don't set up GitHub Actions until CLI works - ❌ **Never mix** CLI and GitHub Actions in the same project phase ### Dockerfile Handling - ❌ **Never let AI generate Dockerfiles** for this workflow - ✅ **Delete existing Dockerfiles** if deployment fails (Railpack is bypassed when Dockerfile exists) - ✅ **Let Railpack infer the build** - it's smarter than most AI-generated Dockerfiles ### Escalation Limits - ⚠️ **After 2-3 deployment attempts fail**, escalate to DevOps - ❌ **Don't deep-dive into container internals** without Docker expertise - ✅ **Document errors and hand off** rather than iterate endlessly --- ## Key Facts ### Deployment Mechanics - `mw experimental deploy` auto-detects Dockerfile **OR** uses Railpack - `mittwald/zerodeploy-action` wraps the CLI for GitHub Actions (same behavior) - Ingress is **automatically configured** with default `webapp` prefix (customize via `--uri-prefix`) - Environment variables: `--env KEY=VALUE` or `--env-file path/to/.env` - Wait for completion: `--wait` flag (default 600s timeout) ### Railpack Behavior - Auto-detects: Node.js, Python, PHP, Ruby, Go, static sites, and more - Requires: Buildpacks, build tools (npm, pip, composer, etc.) - Failure modes: Exotic dependencies, complex monorepos, custom build chains - Documentation: https://railpack.com/getting-started ### mStudio Integration - **Troubleshooting happens in mStudio web UI**, not via CLI - Logs, port inspection, container status are all GUI-based - Port reconfiguration is done post-deployment in ingress settings - Environment variables can be edited after deployment in mStudio --- ## Information Sources ### Official Documentation - **GitHub Actions Guide**: https://developer.mittwald.de/docs/v2/guides/deployment/container-actions/ - **CLI Reference**: https://developer.mittwald.de/docs/v2/cli/reference/experimental/ - **Railpack Getting Started**: https://railpack.com/getting-started ### Skill Components - **Playbooks**: Step-by-step execution guides for each phase - **References**: Background knowledge, gotchas, and escalation criteria