Feature: Application Management
Relevant source files
The following files were used as context for generating this wiki page:
- internal/server-plugins/app/plugin.go
- internal/server-plugins/app/application/application_usecase.go
- internal/server-plugins/app/domain/application.entity.go
- internal/server-plugins/app/infrastructure/application_repository.go
- internal/server-plugins/app/domain/application-validation.service.go
- internal/server-plugins/app/infrastructure/dokku_adapter.go
- internal/server-plugins/app/domain/application_name.vo.go
- internal/server-plugins/app/prompts.go
The Application Management feature is a core server plugin responsible for the lifecycle of Dokku applications. It provides a comprehensive suite of capabilities for creating, deploying, scaling, and configuring applications through the Model Context Protocol (MCP). This allows external clients, such as LLM-based agents, to manage a Dokku instance programmatically.
The feature is implemented as the apps server plugin and follows a Domain-Driven Design (DDD) architecture. It exposes its functionality as a collection of MCP Tools, Resources, and Prompts, abstracting the underlying Dokku CLI commands into a structured, validated, and consistent API.
Sources: internal/server-plugins/app/plugin.go:29-33, README.md:31-33
Architecture
The Application Management plugin is structured in distinct layers, promoting separation of concerns and maintainability. The flow of control generally moves from the MCP interface down to the Dokku command execution.
Sources: internal/server-plugins/app/plugin.go, internal/server-plugins/app/application/application_usecase.go, internal/server-plugins/app/domain/application.entity.go, internal/server-plugins/app/infrastructure/application_repository.go
The following diagram illustrates the high-level architecture of the plugin.
Core Components
| Component | Description | File |
|---|---|---|
AppsServerPlugin | Implements the ServerPlugin interface. Defines and handles all MCP tools, resources, and prompts for application management. | internal/server-plugins/app/plugin.go |
ApplicationUseCase | Orchestrates all business logic. It validates commands and coordinates the domain entities and repositories to fulfill a request. | internal/server-plugins/app/application/application_usecase.go |
Application (Entity) | The core domain model representing a Dokku application, its state, configuration, and lifecycle events. | internal/server-plugins/app/domain/application.entity.go |
ValidationService | A domain service that centralizes validation logic for application names, deployments, and scaling operations. | internal/server-plugins/app/domain/application-validation.service.go |
ApplicationRepository | An interface defining the contract for persisting and retrieving Application entities. | internal/server-plugins/app/domain/application.repository.go |
DokkuApplicationRepository | The infrastructure implementation of the repository. It interacts with Dokku via an adapter to manage application state. | internal/server-plugins/app/infrastructure/application_repository.go |
DokkuApplicationAdapter | A low-level adapter that encapsulates the logic for executing specific Dokku application-related commands (e.g., apps:list, ps:scale). | internal/server-plugins/app/infrastructure/dokku_adapter.go |
Domain Model
The core of the feature is the Application entity, which models a Dokku application and its associated properties. It uses several Value Objects to ensure validity and consistency.
Sources: internal/server-plugins/app/domain/application.entity.go, internal/server-plugins/app/domain/application_name.vo.go
Application Entity Diagram
This diagram shows the structure of the Application entity and its relationship with other domain objects.
Application States
The Application entity can exist in several states, which are determined by querying Dokku's ps:report and apps:report commands.
| State | Description |
|---|---|
StateExists | The application has been created in Dokku but has not yet been deployed. |
StateRunning | The application is deployed and has one or more running processes. |
StateStopped | The application is deployed but all its processes are scaled to zero. |
StateError | The application is in a locked or failed state, often during a failed deployment. |
Sources: internal/server-plugins/app/infrastructure/application_repository.go:414-456, internal/server-plugins/app/domain/application.entity.go:19-22
Application Name Validation
Application names are handled by the ApplicationName value object, which enforces Dokku's naming constraints.
| Rule | Description |
|---|---|
| Not Empty | The name cannot be empty. |
| Max Length | Cannot exceed 63 characters. |
| Pattern | Must match ^[a-z0-9](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/%5Ba-z0-9-%5D%7B0%2C61%7D%5Ba-z0-9%5D)?$. |
| No Hyphen Prefix/Suffix | Cannot start or end with a hyphen. |
| Not Reserved | Cannot be a reserved name like dokku, apps, ps, etc. |
Sources: internal/server-plugins/app/domain/application_name.vo.go:57-93
MCP Interface
The plugin exposes its functionality to MCP clients through a set of resources, tools, and prompts.
Sources: internal/server-plugins/app/plugin.go:61-112
Resources
| URI | Name | Description | MIME Type |
|---|---|---|---|
dokku://apps/list | Application List | Provides a complete list of all Dokku applications with their current status. | application/json |
Sources: internal/server-plugins/app/plugin.go:63-69
Tools
The following tools are available for managing applications.
| Tool Name | Description | Parameters |
|---|---|---|
create_app | Create a new Dokku application. | name (string, required), buildpack (string), no_vhost (boolean) |
deploy_app | Deploy an application from a Git repository. | app_name (string, required), repo_url (string, required), git_ref (string), force (boolean) |
scale_app | Scale application processes. | app_name (string, required), process_type (string), instances (number, required) |
configure_app | Set environment variables for an application. | app_name (string, required), config (object, required) |
get_app_status | Get comprehensive status for an application. | app_name (string, required) |
Sources: internal/server-plugins/app/plugin.go:74-107
Prompts
| Prompt Name | Description |
|---|---|
app_doctor | Provides a template for comprehensive application health diagnosis and troubleshooting. |
Sources: internal/server-plugins/app/plugin.go:110-115, internal/server-plugins/app/prompts.go:13-43
Use Case Flows
The ApplicationUseCase orchestrates operations by coordinating domain logic, validation, and infrastructure persistence.
Create Application Flow
This sequence diagram shows the interactions when a client calls the create_app tool.
State Determination Logic
A key responsibility of the DokkuApplicationRepository is to determine the ApplicationState from the text output of Dokku commands. This logic is crucial for accurately representing the real-world state of an application within the domain model.
The determineStateFromInfo function inspects a map of key-value pairs parsed from ps:report and apps:report.
Summary
The Application Management feature provides a robust and well-architected system for managing Dokku applications via the MCP standard. By leveraging a DDD approach, it separates concerns into distinct layers, from the high-level MCP interface down to the low-level execution of Dokku commands. Its use of domain entities, value objects, and a dedicated validation service ensures that operations are both consistent and safe, providing a reliable foundation for automated and agent-driven Dokku management.