Introducing the Penpot Docker Extension: One-Click Deployment for Self-Hosted Design

Penpot is an open-source design and prototyping platform built for cross-domain teams. The Penpot Docker Extension simplifies the process of getting a powerful design environment up and running, transforming a multi-step setup into a one-click deployment.

Why run Penpot as a Docker Extension?

Docker Extensions provide the power to integrate external tools directly into the Docker Desktop dashboard, extending its core functionality. Building this extension allows us to leverage Docker Desktop as a powerful platform for deployment and management:

1. Extend Docker Desktop: Extensions add new functionality, allowing the community and partners to contribute to Docker Desktop's capabilities.

2. Improve Workflows: They connect your favorite development tools, allowing you to integrate workflows and create automation.

3. Distribution Channel: Extensions provide a mechanism for reaching millions of developers who rely on Docker Desktop. You can discover 3rd party tools easily within the interface.

Features: Seamless Management of Your Penpot Stack

The Penpot Docker Extension is focused on providing real-time visibility and control over all necessary Penpot services. The user interface allows deployment and management of the self-hosted instance.

Core Management Capabilities

• One-Click Deployment: Start a complete Penpot stack with a single action.
• Status Monitoring: View the real-time status of all Penpot services. This monitoring includes detailed status indicators like Running (active and operational), Starting (initializing), Stopped (not running), Healthy (health checks are passing), and Unhealthy (health checks are failing).
• Service Management: You can easily Start, Stop, and Restart individual services.
• Quick Access: Direct links are provided to access the Penpot UI (Port 9001) and MailCatcher (Port 1080).
• Logs Viewer: Troubleshoot issues quickly by viewing the last 100 log lines for any Penpot service.
  --------------------------------------------------------------------------------
  

Diving Deep: The Complete Penpot Stack Architecture

The extension is designed to deploy a complete, functional Penpot stack, consisting of six distinct services:

To run this stack successfully, you need Docker Desktop (latest version), a minimum of 4GB RAM available for Docker, and ensured availability of ports 9001 and 1080 on your host.
--------------------------------------------------------------------------------

Under the Hood: Building the Extension

Developing this extension involved leveraging the Docker Extensions SDK, which provides the tools necessary to customize and enhance Docker Desktop.

Technology Stack and Structure

The extension is built primarily using React and TypeScript for the customized user interface. Seamless style integration, which is crucial for a native feel, is achieved using the Docker Material UI Theme npm package.

The codebase language breakdown is notably technical:

• TypeScript: 50.7%

• Go: 35.7%

• Dockerfile: 8.3%

• Makefile: 4.2%

• HTML: 1.1%

Extensions are packaged as specially formatted Docker images, a process aided by the Extensions CLI tool. Key files defining the extension include:

• Dockerfile: Contains everything required to build the extension and run it in Docker Desktop.

• metadata.json: This is a fundamental element found at the root of the image filesystem that describes the content, name, description, and version of the extension.

• ui folder: This high-level folder contains the front-end source code, which is a React app.

• docker.svg: The icon displayed in the left-menu of the Docker Desktop Dashboard.

The extension includes both a UI part and backend parts that run either on the host or within the Desktop virtual machine.

Configuration and Updating

The extension ships with development-friendly defaults:

• Email verification and secure session cookies are disabled (ideal for localhost setup).

• MailCatcher is utilized as the SMTP server for easily testing emails.

• Telemetry is enabled with the "docker-extension" referer.

Customizing Configuration

To modify the Penpot configuration (e.g., for production use cases like enabling email verification, configuring a real SMTP server, or setting a strong PENPOT_SECRET_KEY), you must:

1. Stop the Penpot services.

2. Edit the docker-compose.yaml file within the extension directory.

3. Modify environment variables as required.

4. Restart the services.

Updating Penpot Versions

To update Penpot to a specific version (e.g., 2.4.3), you can use an environment variable:

1. Stop all existing Penpot services.

2. Set the desired version: export PENPOT_VERSION=2.4.3.

3. Restart the services.If the PENPOT_VERSION variable is left unset, the extension will automatically use the latest available version.

Installation Guide

You have two primary options for installing the Penpot Docker Extension:

Option 1: Install from Docker Hub

For the quickest installation, use the docker extension install command:

docker extension install ajeetraina777/penpot-docker-extension:2.0.1

Option 2: Build and Install Locally

If you wish to build the extension directly from the source code, follow these steps:

Option 2: Build and Install Locally

1. Clone this repository:

git clone https://github.com/ajeetraina/penpot-docker-extension.git
cd penpot-docker-extension

2. Build the extension:

make build-extension

3. Install the extension:

make install-extension

Open Docker Dashboard and select Extensions to see Penpot Docker Extension appear on the left sidebar.

Visit https://localhost:9001 to access the Penpot dashboard.

In essence, the Penpot Docker Extension acts as a highly specialized control panel for the Penpot design platform.

It eliminates the complexity of orchestrating multiple services manually, providing a centralized location within Docker Desktop where you can monitor health, view logs, and manage the lifecycle of your self-hosted design environment, much like a pilot managing all complex aircraft systems from a single, organized cockpit.

Want to learn more? Catch me up on 26th November at 15:00 UTC at Penpot Community Hours #3 where I will join Yami and Medet. Here's the registration link https://app.formbricks.com/s/wwbc1672np7jbrul5unsjuma

Penpot Community Hours #3: Self-Host Deep Dive

Hi everyone 👋 When we discussed our community plans late last year, we mentioned the concept of hosting online get-togethers for our beloved community members. I’m happy to announce that Penpot Community Hours #3 will happen on 26 November 2025 at 15:00 UTC with myself, @yami and our guest from Docker, Ajeet! What are these events? The goal of Penpot Community Hours is simple: Provide our community members an opportunity to feel even closer to Penpot, fire away questions, discuss…

Penpot Communitymedetcan