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.mdskills/deploy/SKILL.md
GitHubUser 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
Pre-flight checks:
Run
mvn compileandmvn test— do not deploy if tests failEnsure platform context:
- Read
akka://contextresource to check current org/project - If organization is empty:
a. Call
akka_organizations_listto get available orgs b. Present the list to the user and ask which to use c. Remember the chosen org for subsequent tool calls - If project is empty:
a. Call
akka_projects_list(passorganizationparameter if known) b. If projects exist: present list and ask user to pick c. If none: ask if they want to create one viaakka_projects_created. Remember the chosen project for subsequent tool calls - Read
akka://regionsto confirm target region - IMPORTANT: Pass the chosen project as the
projectparameter on every platform tool call. Do NOT callakka config set— that modifies the user's persistent CLI configuration.
- Read
Check the service name: Read
pom.xmland 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 theserviceparameter inakka_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 infooutput forcontainerdas 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:- Open Docker Desktop → Settings → General
- Uncheck 'Use containerd for pulling and storing images'
- 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.manifestor anAdminEndpoint.javafile 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 removeto 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
Stop local services: Before building the container image, call
akka_local_stop_serviceto stop any locally running instance of the service. Running services hold file locks on build artifacts that preventmvn clean installfrom packaging the image. Then callakka_local_stopto shut down the local runtime environment. If nothing is running, these calls are safe no-ops — proceed to the next step.Build container image: Use
akka_build_imageMCP tool to runmvn clean install -DskipTests. This creates a local Docker image. Note the image name and tag from the output.Deploy to platform: Choose the appropriate method:
Option A — Direct deploy (quick iteration):
- Use
akka_services_deployMCP tool with the image:tag andpush=true - The
--pushflag 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_envto inject secrets (e.g.{"MY_VAR": "secret-name/key"}) - Suitable for development and testing
Option B — Descriptor-based deploy (production):
- Use
akka_push_imageto build and push the image first - Use
akka_project_exportto capture current state - Modify or create a project descriptor YAML with the new service
- Use
akka_project_validateto check the descriptor - Use
akka_project_applywithdry_run=truefirst - Use
akka_project_applyto apply
- Use
Verify deployment:
- Use
akka_services_getto check service status - Use
akka_services_logsto verify the service started correctly - Check for errors in the logs
- Use
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_componentsto verify all expected components (entities, views, workflows, agents) are registered and activeakka_backoffice_get_entity_stateorakka_backoffice_list_eventsto spot-check entity state if test traffic has been sentakka_backoffice_get_workflowto verify workflow executionakka_backoffice_query_viewto confirm view projections are workingakka_backoffice_list_timersto check timer registrations- Do NOT pass
local=true— these calls target the deployed service
Configure routing (if needed):
- Use
akka_routes_listto 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_listto 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_createwith a path mapping (e.g. path/→ service name)
- Use
- If the user doesn't need external access yet, skip routing
- Use
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. Runningmvn clean install -DskipTests(viaakka_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 compileandmvn testsucceeded — no deploy was attempted with failing tests. - Platform context is confirmed:
akka://contextwas read; an organization and project were selected (fromakka_organizations_list/akka_projects_listif empty) and passed as theprojectparameter on every subsequent platform call —akka config setwas 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 theserviceparameter toakka_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_serviceandakka_local_stopwere called to release file locks before building the image. -
akka_build_imageproduced a local Docker image and the image name/tag are known. - Either Option A (
akka_services_deploywithpush=true) or Option B (akka_push_image→akka_project_export→akka_project_validate→akka_project_applywithdry_run=truethen real apply) completed successfully — production deploys used the descriptor-based flow. -
akka_services_getandakka_services_logsconfirm 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.xmlfor 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.