Shakudo Microservice

Shakudo Microservice Management

This skill teaches you how to manage Shakudo microservices correctly, including deployment, restart, scaling, and debugging workflows.

Prerequisites

• Access to Shakudo platform MCP tools (shakudo-platform_*)
• Environment variable USER_EMAIL must be set (required for all operations)
• Git repository synced with Shakudo platform

Core Concepts

Environment Configuration

• Default environment: basic-ai-tools-small (use unless user specifies otherwise)
• Git server: demos (default, verify with listGitServers)
• Branch: main (default)
• Port: 8787 (default for most services)

Key Environment Variables

USER_EMAIL     - Owner email (REQUIRED for all operations)
MY_JOB_ID      - Current job ID (for URL construction)

Workflows

1. Create a New Microservice

Step-by-step:

1. Discover valid environments (if unsure):

   shakudo-platform_listEnvironments({ search: "basic" })
   

2. Verify git server is available:

   shakudo-platform_listGitServers()
   

3. Create the microservice:

   shakudo-platform_createMicroservice({
     name: "my-service-name",       # MUST: lowercase, hyphens, 1-63 chars
     userEmail: process.env.USER_EMAIL,
     environment: "basic-ai-tools-small",
     gitServer: "demos",
     branch: "main",
     port: 8787,
     script: "run.sh"
   })
   

4. Poll for status until status='running':

   shakudo-platform_searchMicroservice({ searchTerm: "my-service-name" })
   

   Typical startup: 30-120 seconds

5. Verify service is healthy by checking logs:

   shakudo-platform_getPodEvents({ jobId: "<service-id>" })
   

2. Restart a Microservice (After Code Changes)

IMPORTANT: Do NOT cancel/delete the service when debugging. Instead:

1. Fix the bug in code

2. Commit and push to git:

   git add . && git commit -m "[subfolder] fix description" && git push
   

3. Wait for git sync (check sync status):

   shakudo-platform_checkGitServerSync()
   

   Wait until the repository shows as synced (usually 30-60 seconds)

4. Find the service ID:

   shakudo-platform_searchMicroservice({ searchTerm: "my-service-name" })
   

5. Restart the service:

   shakudo-platform_restartService({ id: "<service-id>" })
   

6. Watch logs for success:

   shakudo-platform_getPodEvents({ jobId: "<service-id>", tailLines: 100 })
   

3. Scale a Microservice

Scale to zero (stop without deleting):

shakudo-platform_scaleService({ id: "<service-id>", newReplicas: 0 })

Scale up for more capacity:

shakudo-platform_scaleService({ id: "<service-id>", newReplicas: 3 })

4. Debug a Failing Microservice

1. Get pod events and logs:

   shakudo-platform_getPodEvents({ 
     jobId: "<service-id>",
     tailLines: 200
   })
   

2. Check common issues:

   • Port mismatch (service expects different port than configured)
   • Missing environment variables
   • Script path incorrect (run.sh not found)
   • Git not synced (old code deployed)

3. Search for service by name (to get full details):

   shakudo-platform_listPipelineJobs({
     jobName: "my-service",
     isService: true,
     limit: 10
   })
   

5. Delete a Microservice

WARNING: This is permanent and cannot be undone.

shakudo-platform_deleteMicroservice({ 
  id: "<service-id>",
  confirm: true  # REQUIRED safety flag
})

URL Patterns

External URLs (Public Access)

Pattern: https://{service-name}.dev.hyperplane.dev

Priority order for URL construction:

1. mappedUrl (if available)
2. https://{userServiceSubdomain}.dev.hyperplane.dev
3. https://{dashboardPrefix}.dev.hyperplane.dev
4. https://{service-name}.dev.hyperplane.dev

In-cluster URLs (Internal Access)

Pattern: http://hyperplane-service-{first-6-chars-of-id}.hyperplane-pipelines.svc.cluster.local:8787

Use in-cluster URLs for:

• Playwright testing
• Service-to-service communication
• Health checks

Common Mistakes to Avoid

1. Don't guess the environment name - Always verify with listEnvironments
2. Don't restart before git sync - Check checkGitServerSync first
3. Don't use npm or pnpm - Use bun and bunx instead
4. Don't delete to debug - Use restart workflow instead
5. Don't hardcode USER_EMAIL - Always read from environment variable

Examples

Deploy a React App

// 1. Create microservice
shakudo-platform_createMicroservice({
  name: "my-react-app",
  userEmail: process.env.USER_EMAIL,
  environment: "basic-ai-tools-small",
  port: 3000,
  script: "run.sh"  // Should contain: bunx vite --port 3000 --host
})

// 2. Wait for running status
// 3. Access at: https://my-react-app.dev.hyperplane.dev

Deploy a Python API

// 1. Create microservice  
shakudo-platform_createMicroservice({
  name: "my-python-api",
  userEmail: process.env.USER_EMAIL,
  environment: "basic-ai-tools-small",
  port: 8000,
  script: "run.sh"  // Should contain: uv run uvicorn main:app --port 8000 --host 0.0.0.0
})