deploy

Build a container image, push it, and deploy the service to the Akka platform. This is the transition from local development to development on the AAO platform.

SKILL.md

GitHub

User Input

You MUST consider the user input before proceeding (if not empty).

Purpose

This command transitions the service from local development to the Akka platform. It builds a container image, pushes it to a registry, deploys it, and configures routing. Only run this when the service works locally (via /akka:build) and you're ready to ship.

Outline

  1. Pre-flight checks:

    • Run mvn compile and mvn test — do not deploy if tests fail

    • Ensure platform context:

      1. Read akka://context resource to check current org/project
      2. If organization is empty: a. Call akka_organizations_list to get available orgs b. Present the list to the user and ask which to use c. Remember the chosen org for subsequent tool calls
      3. If project is empty: a. Call akka_projects_list (pass organization parameter if known) b. If projects exist: present list and ask user to pick c. If none: ask if they want to create one via akka_projects_create d. Remember the chosen project for subsequent tool calls
      4. Read akka://regions to confirm target region
      5. IMPORTANT: Pass the chosen project as the project parameter on every platform tool call. Do NOT call akka config set — that modifies the user's persistent CLI configuration.
    • Check the service name: Read pom.xml and check the <artifactId>. If it is a scaffold default (e.g. empty-service, my-service, example-service), ask the user what service name they want to deploy as. Use the user's chosen name as the service parameter in akka_services_deploy — do NOT rename the artifactId in pom.xml.

    • Check Docker image store: Docker Desktop may have the containerd image store enabled, which is incompatible with the Akka container registry push flow. Check docker info output for containerd as the storage driver or image store. If detected, warn the user: "Docker Desktop appears to be using the containerd image store, which is incompatible with the Akka container registry push flow. Please:

      1. Open Docker Desktop → Settings → General
      2. Uncheck 'Use containerd for pulling and storing images'
      3. Apply & Restart Docker Desktop

      Then let me know and I'll continue the deploy." Do NOT proceed with the build until the user confirms this is resolved.

    • Check for reliability testing artifacts: Look for .akka/reliability.manifest or an AdminEndpoint.java file in the project's api package. If found, warn the user: "Reliability testing admin endpoint detected. This endpoint provides full cluster control and proxied access to business endpoints — it must not be deployed to production. Run /akka:reliability remove to clean up before deploying." Ask the user whether to proceed anyway (for development/staging deployments) or stop and run the remove command first.

    • Confirm with the user that they want to deploy to the platform

  2. Stop local services: Before building the container image, call akka_local_stop_service to stop any locally running instance of the service. Running services hold file locks on build artifacts that prevent mvn clean install from packaging the image. Then call akka_local_stop to shut down the local runtime environment. If nothing is running, these calls are safe no-ops — proceed to the next step.

  3. Build container image: Use akka_build_image MCP tool to run mvn clean install -DskipTests. This creates a local Docker image. Note the image name and tag from the output.

  4. Deploy to platform: Choose the appropriate method:

    Option A — Direct deploy (quick iteration):

    • Use akka_services_deploy MCP tool with the image:tag and push=true
    • The --push flag pushes the image to the Akka container registry and deploys it in one step
    • Docker registry credentials are configured automatically if the user is logged in via akka auth login — no separate credential setup needed
    • Use secret_env to inject secrets (e.g. {"MY_VAR": "secret-name/key"})
    • Suitable for development and testing

    Option B — Descriptor-based deploy (production):

    • Use akka_push_image to build and push the image first
    • Use akka_project_export to capture current state
    • Modify or create a project descriptor YAML with the new service
    • Use akka_project_validate to check the descriptor
    • Use akka_project_apply with dry_run=true first
    • Use akka_project_apply to apply
  5. Verify deployment:

    • Use akka_services_get to check service status
    • Use akka_services_logs to verify the service started correctly
    • Check for errors in the logs
  6. Inspect deployed service (optional): Use backoffice tools to inspect the deployed service's runtime state. These are read-only and safe for production.

    • akka_backoffice_list_components to verify all expected components (entities, views, workflows, agents) are registered and active
    • akka_backoffice_get_entity_state or akka_backoffice_list_events to spot-check entity state if test traffic has been sent
    • akka_backoffice_get_workflow to verify workflow execution
    • akka_backoffice_query_view to confirm view projections are working
    • akka_backoffice_list_timers to check timer registrations
    • Do NOT pass local=true — these calls target the deployed service
  7. Configure routing (if needed):

    • Use akka_routes_list to check existing routes
    • If routes already exist for this service, no action needed
    • If no routes exist and the user wants external access:
      • Use akka_hostnames_list to check if the project has a hostname
      • If no hostnames exist, use akka_hostnames_add (without a hostname parameter) to get an auto-generated hostname — this is the easiest option for development
      • Once a hostname exists, use akka_routes_create with a path mapping (e.g. path / → service name)
    • If the user doesn't need external access yet, skip routing
  8. Report: Summarize deployment:

    • Image URI pushed
    • Service name and version
    • Region deployed to
    • Route URL (if configured)
    • Service status
    • Component health (if backoffice inspection was performed)

Key Rules

  • ALWAYS run tests before deploying — do not deploy broken code
  • ALWAYS confirm with the user before deploying to the platform
  • Always validate descriptors before applying
  • Always use dry_run before real apply
  • Check logs after deployment to verify health
  • Prefer descriptor-based deployment for production
  • NEVER modify pom.xml for image building or deployment — do not add Jib, docker-maven-plugin, buildx configuration, or any other image-related plugins. The Akka SDK parent POM already configures docker-maven-plugin with the correct platform (linux/amd64) and base image. Running mvn clean install -DskipTests (via akka_build_image) is all that's needed to produce a deployable image. If the build fails with architecture errors, check that Docker/Colima is running and supports buildx — do NOT attempt to fix it by editing pom.xml.

Done When

  • mvn compile and mvn test succeeded — no deploy was attempted with failing tests.
  • Platform context is confirmed: akka://context was read; an organization and project were selected (from akka_organizations_list / akka_projects_list if empty) and passed as the project parameter on every subsequent platform call — akka config set was NOT invoked.
  • The target region was confirmed via akka://regions.
  • The pom.xml <artifactId> was checked; if it was a scaffold default, the user supplied the deploy service name and it was passed as the service parameter to akka_services_deploy — <artifactId> was NOT renamed.
  • Docker Desktop was checked for the containerd image store; if detected, the deploy paused until the user disabled it and confirmed.
  • The user explicitly confirmed the deploy.
  • akka_local_stop_service and akka_local_stop were called to release file locks before building the image.
  • akka_build_image produced a local Docker image and the image name/tag are known.
  • Either Option A (akka_services_deploy with push=true) or Option B (akka_push_image → akka_project_export → akka_project_validate → akka_project_apply with dry_run=true then real apply) completed successfully — production deploys used the descriptor-based flow.
  • akka_services_get and akka_services_logs confirm the deployed service is healthy with no startup errors.
  • Routing was configured only if requested; when configured, a hostname exists (akka_hostnames_list / akka_hostnames_add) and a route maps to the service (akka_routes_create).
  • NO changes were made to pom.xml for image building or deployment — no Jib, docker-maven-plugin, or buildx plugins were added.
  • The report includes image URI, service name and version, region, route URL (if configured), and current service status.