Local Development Environment

Relevant source files

The following files were used as context for generating this wiki page: - [CONTRIBUTING.md](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/CONTRIBUTING.md) - [README.md](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/README.md) - [scripts/setup-dokku-local.sh](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/scripts/setup-dokku-local.sh) - [PHASE1_IMPLEMENTATION.md](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/PHASE1_IMPLEMENTATION.md) - [scripts/cleanup-test-apps.sh](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/scripts/cleanup-test-apps.sh) - [scripts/setup-dev.sh](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/scripts/setup-dev.sh) - [internal/dokku-api/ssh_integration_test.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/dokku-api/ssh_integration_test.go) - [internal/server-plugins/app/domain/application-validation.service_test.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/server-plugins/app/domain/application-validation.service_test.go) - [internal/server-plugins/app/plugin.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/server-plugins/app/plugin.go) - [internal/server-plugins/onboarding/plugin.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/server-plugins/onboarding/plugin.go) - [internal/server-plugins/core/plugin.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/server-plugins/core/plugin.go) - [scripts/start-server.sh](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/scripts/start-server.sh) - [internal/dokku-api/client.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/dokku-api/client.go) - [internal/server-plugins/domain/infrastructure/dokku_adapter.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/server-plugins/domain/infrastructure/dokku_adapter.go) - [internal/dokku-api/client_blacklist_test.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/dokku-api/client_blacklist_test.go) - [internal/server-plugins/domain/plugin.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/server-plugins/domain/plugin.go) - [internal/server-plugins/core/infrastructure/dokku_adapter.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/server-plugins/core/infrastructure/dokku_adapter.go) - [internal/server-plugin/application/registry_test.go](https://github.com/dokku-MCP/dokku-mcp/blob/HEAD/internal/server-plugin/application/registry_test.go)

The Dokku MCP project provides a comprehensive local development environment that utilizes Docker and Make to streamline setup, testing, and contribution. This environment allows developers to run a local Dokku instance in a container, enabling integration testing without requiring a remote server. The setup is automated through a series of shell scripts and a Makefile, ensuring consistency and ease of use for all contributors.

The core of the local setup is a Dockerized Dokku instance, which the dokku-mcp server connects to via SSH. The setup scripts handle the configuration of SSH keys, network ports, and a local config.yaml file, creating a self-contained ecosystem for development and testing. This approach facilitates a robust development workflow, from writing code and running automated checks with Git hooks to executing a full suite of unit and integration tests.

Sources: README.md:100-103, CONTRIBUTING.md:22-27, scripts/setup-dokku-local.sh

Prerequisites

To set up the local development environment, the following tools must be installed on your system:

• Go: Version 1.25 or later.
• Docker and Docker Compose: For running the local Dokku instance.
• Make: For using the automated build and setup commands.

Sources: README.md:141-144, README.md:101-102

Initial Setup Workflow

The initial setup process involves cloning the repository and running a series of make commands to install tools and configure the environment. This process is designed to be executed once to prepare a developer's machine for contribution.

The following diagram illustrates the one-time setup flow for a new developer.

This diagram shows the sequence of commands to prepare the development environment.
Sources: CONTRIBUTING.md:24-27, README.md:150-159

1. Install Development Tools

The make install-tools command installs necessary Go tools for development, including goimports for code formatting and golangci-lint for static analysis.

make install-tools

Sources: README.md:154-158, scripts/setup-dev.sh:15-27

2. Configure Git Hooks

The make setup-dev command configures Git hooks by setting the core.hooksPath to the .githooks/ directory. This ensures that pre-commit checks are run automatically to maintain code quality.

make setup-dev

The pre-commit hook performs several actions:

• Auto-formats Go code using goimports/gofmt.
• Runs static analysis with go vet.
• Enforces strong typing rules (e.g., blocks interface{}).
• Runs quick tests on modified packages.

Sources: CONTRIBUTING.md:50-59, scripts/setup-dev.sh:7-13

Local Dokku Instance

For development and integration testing, a local Dokku instance can be run using Docker. The project provides make commands and a setup script to manage this container.

Architecture Overview

The local development environment consists of the developer's machine running the dokku-mcp server process, which communicates over SSH with a Dokku instance running inside a Docker container named dokku-mcp-dev.

This diagram shows the interaction between the local server process and the Dockerized Dokku instance.
Sources: scripts/setup-dokku-local.sh:88-91, README.md:100-103

Setting Up the Local Dokku Container

The make setup-dokku command executes the scripts/setup-dokku-local.sh script, which automates the entire process of configuring the local Dokku instance. This command only needs to be run once.

The setup script performs the following steps:

1. Starts the Dokku container using docker compose up -d.
2. Waits for the Dokku service to become available.
3. Generates a dedicated SSH key pair (.ssh/dokku_mcp_test) for testing if one doesn't exist.
4. Adds the public key to the Dokku container's ssh-keys.
5. Updates the user's local ~/.ssh/config with an entry for dokku.local to simplify SSH access.
6. Creates a config.yaml file in the project root, pre-configured to connect to the local Dokku container.

The following diagram visualizes the flow of the setup-dokku-local.sh script.

This flowchart outlines the automated steps for preparing the local Dokku container.
Sources: scripts/setup-dokku-local.sh, README.md:107-111

The generated config.yaml contains all the necessary settings to connect the dokku-mcp server to the local Dokku instance.

# Dokku MCP Server Configuration for Local Development
ssh:
  host: "127.0.0.1"
  port: 3022
  user: "dokku"
  key_path: ".ssh/dokku_mcp_test"

security:
  blacklist:
    - "destroy"
    - "uninstall"
    - "remove"

Sources: scripts/setup-dokku-local.sh:94-123

Managing the Local Dokku Container

The following make commands are used to control the local Dokku container's lifecycle:

Command	Description
make setup-dokku	Runs the initial setup script for the local Dokku container.
make dokku-start	Starts the local Dokku container if it's stopped.
make dokku-stop	Stops the local Dokku container.

Sources: README.md:109-117

Makefile Commands

The Makefile provides a set of commands to automate common development tasks.

Command	Description	Source
make help	Shows all available commands.	README.md:165
make build	Builds the dokku-mcp server binary into the build/ directory.	README.md:166
make start	Builds the binary (if needed) and starts the server.	README.md:161
make check	Runs all code quality checks (linting, formatting, static analysis).	CONTRIBUTING.md:45
make test	Runs all unit and integration tests and generates an HTML coverage report.	README.md:171
make test-integration-local	Runs integration tests specifically against the local Dokku container.	README.md:177
make clean	Cleans up build artifacts.	README.md:167
make inspect	Launches the MCP Inspector CLI connected to the server for quick inspection.	README.md:25

Testing

The project includes both unit and integration tests. The local development environment is crucial for running integration tests that interact with a real Dokku instance.

• Unit and Integration Tests: make test runs the complete test suite.
• Local Integration Tests: make test-integration-local runs tests specifically against the running local Dokku container. This is useful for verifying features that depend on Dokku's behavior.

The presence of files like internal/dokku-api/ssh_integration_test.go with the //go:build integration tag indicates a dedicated suite of tests that require a running Dokku instance to execute.

Sources: README.md:170-179, internal/dokku-api/ssh_integration_test.go:1-3

Cleanup

To remove artifacts created during local development and testing, the scripts/cleanup-test-apps.sh script is provided. This script:

1. Deletes any test applications (named with dokku-mcp-test) from the Dokku instance.
2. Removes the dokku-mcp-test SSH key from the Dokku instance.
3. Removes the dokku.local host entry from the local ~/.ssh/config file.
4. Deletes the local test SSH key pair (~/.ssh/dokku_mcp_test).

The following diagram shows the cleanup process.

This flowchart details the steps taken by the cleanup script to reset the environment.
Sources: scripts/cleanup-test-apps.sh

Summary

The local development environment for dokku-mcp is a well-architected system that leverages Docker, Make, and shell scripts to provide a consistent and isolated workspace. It enables developers to build, test, and validate their changes against a real Dokku instance running locally, significantly improving the development workflow and ensuring high-quality contributions. The automation of setup, configuration, and cleanup processes makes it easy for new contributors to get started quickly.

Sources: README.md:100-103, CONTRIBUTING.md:22-27