mittwald-zerodeploy

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