Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide provides comprehensive instructions for deploying the Dokku MCP server and for deploying applications onto a Dokku instance using the server's capabilities. It covers setup for local development using Docker, building from source, using pre-built binaries, and the architecture of the asynchronous application deployment system.
The server is designed to be run as a process that connects to a Dokku host via SSH. Configuration can be managed via a config.yaml file or environment variables. The primary function of the server is to expose Dokku's features, such as application deployment, to MCP-compatible clients.
Sources: README.md:4-9, README.md:120-123
1. Server Deployment Methods
There are three primary methods for deploying and running the dokku-mcp server.
Local Development Deployment (Docker)
For development and testing, a local Dokku instance can be provisioned using Docker and Make. This is the recommended approach for contributors.
The setup process is automated via a script that configures a Docker container, sets up SSH keys, and generates a local config.yaml.
Sources: README.md:134-138, scripts/setup-dokku-local.sh
The following diagram illustrates the local setup flow:
This diagram shows the automated steps performed by the setup-dokku-local.sh script.
Sources: scripts/setup-dokku-local.sh:5-110
Key Makefile Commands:
| Command | Description | Source |
|---|---|---|
make setup-dokku | Runs the setup script to configure the local Dokku container, SSH keys, and config file. Must be run once. | README.md:143-144 |
make dokku-start | Starts the local Dokku container. | README.md:146-147 |
make dokku-stop | Stops the local Dokku container. | README.md:150-151 |
make start | Builds the binary (if needed) and starts the server, connecting to the local Dokku instance. | README.md:18-19, README.md:188-189 |
The setup-dokku-local.sh script generates a config.yaml file with settings tailored for the local Docker environment, including SSH configuration to connect to the Dokku container on 127.0.0.1:3022.
Sources: scripts/setup-dokku-local.sh:78-110
Deployment from Source
To build and run the server from source, you need Go version 1.25 or later.
- Clone the repository:
git clone https://github.com/dokku-mcp/dokku-mcp.git cd dokku-mcp - Build the binary:
make build - Run the server:
Alternatively, the./build/dokku-mcpmake startcommand combines the build and run steps.
Sources: README.md:110-117, scripts/start-server.sh:49-56
Using Pre-built Binaries
Pre-built binaries are available for Linux and macOS. This method does not require Go to be installed.
- Download the binary for your platform from the releases page.
# Example for Linux (amd64) curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/download/v0.2.0/dokku-mcp-linux-amd64 - Make it executable and move it to your PATH.
chmod +x dokku-mcp sudo mv dokku-mcp /usr/local/bin/ - Verify the installation.
dokku-mcp --version
Sources: README.md:99-108
2. Application Deployment via MCP
The server provides a deploy_app tool to deploy applications to the connected Dokku instance. This system uses an asynchronous architecture to handle long-running builds without blocking the client.
Sources: README.md:40, PHASE1_IMPLEMENTATION.md:11-14
Architecture Overview
When a deployment is initiated, the server immediately returns a deploymentID and begins tracking the status in the background. This is achieved by polling the Dokku instance for application status, process reports, and logs. This replaces a previous "fire-and-forget" approach where SSH timeouts were incorrectly treated as successful deployments.
Sources: PHASE1_IMPLEMENTATION.md:16-24
The key components involved in this process are:
| Component | Description | Source File |
|---|---|---|
AppsServerPlugin | Defines the deploy_app MCP tool and handles the initial request. | internal/server-plugins/app/plugin.go |
ApplicationUseCase | Orchestrates the deployment logic, validating the request and calling the deployment service. | internal/server-plugins/app/application/application_usecase.go |
DeploymentService | An interface for deploying applications. The implementation is provided by the deployment plugin. | internal/server-plugins/app/application/application_usecase.go:21-25 |
deploymentInfrastructure | Implements the low-level logic for interacting with Dokku via SSH, including git:sync and ps:rebuild commands. | internal/server-plugins/deployment/infrastructure/deployment_infrastructure.go |
DeploymentTracker | A thread-safe, in-memory store for tracking the state of active deployments. | PHASE1_IMPLEMENTATION.md:27-38 |
DeploymentPoller | A background worker that periodically polls Dokku to check the status of an ongoing deployment. | PHASE1_IMPLEMENTATION.md:43-53 |
DeploymentStatusChecker | Queries Dokku's apps:report and ps:report to determine the actual status of a deployment. | PHASE1_IMPLEMENTATION.md:58-69 |
Deployment Flow
The following sequence diagram illustrates the asynchronous deployment process:
This diagram shows the sequence of events from a client's deploy_app call to the background polling that tracks the deployment status.
Sources: PHASE1_IMPLEMENTATION.md:144-165, internal/server-plugins/deployment/infrastructure/deployment_infrastructure.go:121-131
deploy_app Tool
The deploy_app tool is the entry point for all Git-based deployments.
| Parameter | Required | Description | Source |
|---|---|---|---|
app_name | Yes | Name of the application to deploy. | internal/server-plugins/app/plugin.go:153-156 |
repo_url | Yes | URL of the Git repository to deploy from. | internal/server-plugins/app/plugin.go:157-160 |
git_ref | No | Git reference (branch, tag, or commit) to deploy. Defaults to main. | internal/server-plugins/app/plugin.go:161-163 |
force | No | Force deployment even if no changes are detected. | internal/server-plugins/app/plugin.go:164-166 |
Deployment Status Lifecycle
A deployment progresses through several states, which are tracked by the DeploymentTracker.
| Status | Description |
|---|---|
pending | The initial state of a deployment after it has been created but before the build has started. |
running | The deployment is actively being built and deployed by Dokku. |
succeeded | The deployment completed successfully, and the application processes are running. |
failed | The deployment failed due to a build error, timeout, or other issue. |
rolled_back | The deployment was rolled back. |
Sources: internal/server-plugins/deployment/domain/deployment.entity.go:18-25
The state transitions are managed by the DeploymentPoller and DeploymentTracker.
This diagram shows the lifecycle of a Deployment entity.
Sources: internal/server-plugins/deployment/domain/deployment.entity.go:100-116, PHASE1_IMPLEMENTATION.md:154-160
Configuration
The deployment polling mechanism has several key configuration values that are hardcoded in the dependency injection module.
| Parameter | Value | Description | Source |
|---|---|---|---|
| Poll Interval | 10 seconds | The frequency at which the DeploymentPoller checks the status of an active deployment. | internal/server-plugins/deployment/module.go:37-41 |
| Max Poll Duration | 30 minutes | The maximum amount of time the poller will track a deployment before marking it as failed. | internal/server-plugins/deployment/module.go:42-43 |
| Cleanup TTL | 5 minutes | The time a completed (succeeded/failed) deployment remains in the in-memory tracker before being cleaned up. | PHASE1_IMPLEMENTATION.md:32-33 |
Sources: PHASE1_IMPLEMENTATION.md:231-240