Site icon Efficient Coder

Self-Host Pad.ws: Your Complete Guide to Whiteboard-as-an-IDE with Docker

高效码农

Pad.ws: The Complete Guide to Self-Hosting a Whiteboard-as-an-IDE with Docker and Coder

Pad.ws is a browser-based development environment that merges an interactive whiteboard with a fully fledged IDE. This guide provides a step-by-step process for self-hosting the application using Docker Compose, integrating Excalidraw for visualization and Coder for cloud environments, configured with PostgreSQL, Redis, and Keycloak.

Introduction: Redefining the Development Environment

The modern developer’s workflow is often fragmented. You sketch an architecture diagram in one tool, switch to a terminal to run commands, and open a separate IDE to write code. This constant context switching breaks the flow of creativity and efficiency. Pad.ws addresses this fragmentation by transforming the browser into a unified workspace where visual ideation and coding coexist seamlessly.
By combining the open-source power of Excalidraw for the whiteboard interface and Coder for the backend cloud development environments, Pad.ws offers a unique “Whiteboard as an IDE” experience. Whether you are drawing system diagrams, sketching UI mockups, or writing complex logic, everything happens in a single, persistent interface. This guide is designed to walk you through every technical detail required to deploy this powerful environment on your own infrastructure.

Core Features: Why Choose Pad.ws?

Before diving into the deployment specifics, it is essential to understand the capabilities that this architecture unlocks. Pad.ws is not just a drawing tool with a code snippet feature; it is a comprehensive development platform.

1. Interactive Whiteboard Powered by Excalidraw

At its core, the interface provides an infinite canvas for drawing and sketching. Leveraging Excalidraw, users can visualize ideas with a hand-drawn aesthetic that is perfect for system design and brainstorming. This isn’t just for static images; it is the foundation for your development environment.

2. Fully Fledged IDE Integration

Unlike standard web-based editors, Pad.ws integrates a complete development environment directly within the whiteboard. Users can access terminals and launch VS Code instances without ever leaving the browser tab. This means you can diagram a microservices architecture and immediately spin up the terminal to write the code for it.

3. Browser-Friendly Cloud Access

The entire environment lives in the cloud. This “browser-friendly” approach ensures that your development environment is accessible from any device, anywhere. You are no longer tied to a specific high-performance machine; the heavy lifting is handled by the backend infrastructure.

4. Seamless Workflow Transition

The primary goal is to eliminate friction. The workflow allows for instant switching between visual ideation and coding. You can draw a component, double-click it to enter the code, and jump back to the canvas to modify the design.

5. Support for Custom Tools

Flexibility is key for developers. Pad.ws allows you to access your Virtual Machine (VM) directly from your desktop client. It explicitly supports VS Code and Cursor, enabling you to use the editors you love while maintaining the connection to your cloud-based workspace.

Architecture Overview: How It Works

Understanding the components is crucial for a successful deployment. The application relies on a symbiotic relationship between three major elements:

  • Excalidraw: This serves as the user interface, handling the whiteboard functionality and the visual interaction layer.
  • Coder: This open-source tool powers the cloud development environments. It manages the remote workspaces, provisioning the infrastructure where the actual code execution and container orchestration happen.
  • The Pad App: Built on FastAPI, this application acts as the bridge. It serves the built frontend and provides the backend API required to interface with the Coder service.
    To support this architecture, the deployment requires a robust stack of infrastructure services: PostgreSQL for persistence, Redis for caching and session management, and Keycloak for secure identity management.

Prerequisites for Self-Hosting

While the official managed instance at pad.ws offers free Ubuntu dev environments during the beta phase, self-hosting gives you full control. Please note the following strict requirements:

  • Operating System: You must use a Linux Host. The deployment instructions and testing have been conducted exclusively on Ubuntu. Other distributions may work but are not officially supported in this guide.
  • Container Engine: You must have Docker and Docker Compose installed and running on your host machine. These tools are non-negotiable as the entire stack is containerized.

⚠️ Important Security Notice: This repository is currently in the early development stage. The configuration provided in the docker-compose.yml file is intended strictly for development and testing purposes. The simplified setup described below allows you to host Pad on localhost but is not safe for production use without additional security hardening, reverse proxy configuration, and firewall settings.

Step-by-Step Deployment Guide

This guide breaks down the deployment into six logical phases. Follow each step sequentially to ensure all dependencies are correctly linked.

Phase 1: Environment Configuration

The first step is to prepare your configuration file. This file will hold all the secrets and connection strings that the various services need to communicate.

  1. Copy the Template:
    Navigate to the root of your cloned repository. You will find a template file named .env.template. Copy this file to create your active configuration file. 
    cp .env.template .env
  2. Review the Variables:
    Open the newly created .env file in your text editor. You will see placeholder values. Do not proceed until you have reviewed and understood these defaults, as you will be updating this file with specific IDs and secrets in the subsequent steps.

Phase 2: Deploying PostgreSQL for Data Persistence

Data persistence is critical. You do not want your whiteboard canvases or application configurations to disappear when a container restarts. PostgreSQL is used to ensure the persistence of the whole deployment.

  • Execute the Command:
    Run the following command to start the PostgreSQL container using the configuration provided in your docker-compose.yml. 
    docker compose up -d postgres
  • Verification:
    Ensure the container is running. This database instance will eventually store all your canvas data and system configurations.

Phase 3: Configuring Redis for Caching and Sessions

Next, we deploy Redis. This in-memory data store is utilized by the application for caching and session management. Given the sensitivity of session data, authentication is mandatory.

  • Start the Container:
    Execute the command to launch the Redis service. 
    docker compose up -d redis
  • Secure the Instance:
    You must configure the Redis password to secure the instance. Open your .env file and locate the REDIS_PASSWORD variable. Update it with a strong, secure password. The application will use this password to authenticate with the Redis service.

Phase 4: Setting Up Keycloak for Identity Management (OIDC)

Security is handled by Keycloak, which acts as the OpenID Connect (OIDC) provider. It manages access and users for both the Coder service and the Pad application.

4.1 Launch Keycloak

Start the Keycloak container:

docker compose up -d keycloak

4.2 Access the Admin Console

Once the container is running, navigate to http://localhost:8080 in your web browser to access the Keycloak Administration Console.

4.3 Create a Realm

A Realm in Keycloak acts as a isolated tenant for your users.

  1. Hover over the dropdown in the top-left corner (usually labeled “Master”) and click Create Realm.
  2. Name it appropriately. For consistency with this guide, we suggest naming it pad-ws.
  3. Click Create.

4.4 Create a Client

The Client represents the application (Pad.ws) that will be requesting authentication.

  1. Go to the Clients menu and click Create client.
  2. Client ID: Assign a memorable ID, such as pad-ws-client.
  3. Client Authentication: Toggle this switch to On.
  4. Valid Redirect URIs: For local testing, add * to allow redirects from any URL. (Note: In production, you must specify exact URLs).
  5. Leave other settings as default and click Save.

4.5 Retrieve Client Credentials

You need the secret generated for your client to configure the backend.

  1. Navigate to the Clients page.
  2. Click on the Client ID you just created (pad-ws-client).
  3. Click on the Credentials tab.
  4. Copy the Client secret value displayed.
  5. Update .env: Paste this secret into your environment file under OIDC_CLIENT_SECRET.
  6. Also, update OIDC_REALM (e.g., pad-ws) and OIDC_CLIENT_ID (e.g., pad-ws-client) in your .env file.

4.6 Create a User

You need a user account to log in.

  1. Navigate to Users and click Create user.
  2. Fill in the required details (Username, Email, etc.).
  3. Critical Step: Ensure the switch for Email Verified is set to ON.
  4. Click Save.
  5. Go to the Credentials tab for the new user and set a temporary or permanent password.

4.7 Configure Audience Scope

This step ensures the tokens generated include the correct audience.

  1. Navigate to Clients -> [Your Client ID] -> Client Scopes.
  2. Click on the dedicated scope for your client (named [clientid]-dedicated).
  3. Click Configure a new mapper.
  4. Select Audience from the list.
  5. Included Client Audience: Ensure this matches your Client ID exactly.
  6. Add to access token: Toggle this to On.
  7. Click Add mapper.

Phase 5: Configuring the Coder Backend

Coder is the engine that powers the cloud development environments. Configuring it correctly involves granting it Docker permissions and linking it to Keycloak and your database.

5.1 Determine Docker Group ID

Coder needs permission to interact with the Docker daemon on your host to manage workspaces.

  • Run the following command to find your host’s Docker group ID: 
    getent group docker | cut -d: -f3
  • Update .env: Paste the numeric ID into the DOCKER_GROUP_ID variable in your .env file.

5.2 Launch Coder

Start the Coder container:

docker compose up -d coder

5.3 Initial Access and Admin Setup

  1. Open http://localhost:7080 in your browser.
  2. You will be prompted to create the first administrator user. Create an admin user (e.g., admin).

5.4 Create a Workspace Template

  1. After logging in, navigate to Templates.
  2. Click Create Template or use the “Start from template” option.
  3. Select a base image. The documentation suggests using docker-containers or a simple Ubuntu image. Configure it according to your needs and publish the template.

5.5 Generate Coder API Key

The Pad app needs an API key to communicate with Coder programmatically.

  1. Click your profile picture in the top-right corner of the Coder UI.
  2. Navigate to Account -> API Keys.
  3. Click Generate new token.
  4. Copy the generated token.
  5. Update .env: Paste this token into the CODER_API_KEY variable.

5.6 Retrieve Template ID

You must tell Pad app which template to use for workspaces.

  1. Visit the Coder API endpoint in your browser: http://localhost:7080/api/v2/templates.
  2. You will see a JSON response. Find the id field corresponding to the template you created in the previous step.
  3. Copy this UUID.
  4. Update .env: Set the CODER_TEMPLATE_ID variable.
    • Example: CODER_TEMPLATE_ID=85fb21ba-085b-47a6-9f4d-94ea979aaba9

5.7 Retrieve Organization ID

  1. Visit http://localhost:7080/api/v2/organizations.
  2. Locate the id of your organization (typically the default one).
  3. Update .env: Set the CODER_DEFAULT_ORGANIZATION variable.
    • Example: CODER_DEFAULT_ORGANIZATION=70f6af06-ef3a-4b4c-a663-c03c9ee423bb

5.8 Configure Workspace Name (Optional)

By default, the system assumes the workspace name is ubuntu. If you used a custom name for your workspace in Coder, you must specify it in the .env file using the CODER_WORKSPACE_NAME variable.

Phase 6: Launching the Pad Application

With all the infrastructure (PostgreSQL, Redis, Keycloak, Coder) configured and communicating, you can now start the main application.
The Pad App is a FastAPI application that serves the built frontend files and handles the backend API logic required to interface with Coder.

  • Final Review: Double-check your .env file. Ensure that REDIS_PASSWORD, OIDC_CLIENT_SECRET, DOCKER_GROUP_ID, CODER_API_KEY, CODER_TEMPLATE_ID, and CODER_DEFAULT_ORGANIZATION are all filled in correctly.
  • Start the Service: 
    docker compose up -d pad

Accessing Your Deployment

If all steps were followed correctly, your self-hosted Whiteboard-as-an-IDE is now live.

  1. Open your browser and navigate to http://localhost:8000.
  2. You should see the Pad.ws login screen.
  3. Enter the credentials for the user you created in Keycloak.
    Congratulations! You are now running a fully functional, self-hosted development environment where you can sketch ideas and write code in the same unified interface.

Troubleshooting and FAQ

Even with a step-by-step guide, issues can arise during complex deployments. Here are answers to common questions based on the configuration process.

I cannot log in at localhost:8000. What should I check?

If the login fails, the issue is almost always in the Keycloak configuration. Verify the following in your .env file:

  • Does OIDC_CLIENT_SECRET match exactly what is shown in the Keycloak Client Credentials tab?
  • Is the OIDC_REALM name spelled correctly?
  • Did you verify the user’s email address in Keycloak? If Email Verified is not ticked, the user cannot log in.

Why does Coder fail to start or create workspaces?

Coder requires specific permissions to manage Docker containers. Ensure that the DOCKER_GROUP_ID in your .env file matches the output of the getent group docker | cut -d: -f3 command on your host machine. If the IDs do not match, Coder cannot access the Docker socket.

Do I need to configure Nginx or SSL?

For the development setup described in this guide, no. However, because the warning states this setup is not safe for real-life use, you must configure a reverse proxy (like Nginx) with SSL/TLS termination for any production deployment to ensure data encryption in transit.

Can I use a different database instead of PostgreSQL?

The current configuration is specifically built for PostgreSQL to ensure persistence of canvases and configs. While the underlying frameworks might support other databases, this specific Docker Compose setup relies on the PostgreSQL image. Altering this would require significant modifications to the setup not covered in this guide.

Where are my whiteboard drawings stored?

Your drawings (canvases) and application configurations are stored in the PostgreSQL database deployed in Phase 2. As long as the Docker volume for this container persists, your data is safe.

Conclusion

Pad.ws represents a significant shift in how developers can interact with their code and ideas. By self-hosting this environment, you gain a powerful, browser-based tool that combines the visual freedom of a whiteboard with the technical rigor of a cloud IDE. While the setup requires careful coordination of Keycloak, Coder, and databases, the result is a personalized, seamless development workspace tailored to your specific needs.

Exit mobile version