DOCSEARCHbyAlgolia
Submit Docs

pad.ws Documentation

repository·main·Indexed 26 days ago

https://github.com/coderamp-labs/pad.ws

pad.ws is a hybrid application combining an Excalidraw-based interactive whiteboard with a cloud development environment powered by Coder. It enables developers to switch between visual ideation and coding within a single browser interface, featuring an integrated IDE with terminal and VS Code access. The project includes a FastAPI backend and supports self-hosting via Docker Compose with Keycloak for OIDC authentication, PostgreSQL for persistence, and Redis for caching.

Tokens
10.3K
Snippets
13
Records
79
Agent score
88%

What's inside pad.ws

  1. Overview of pad.ws

    main

    pad.ws is a whiteboard application that functions as a browser-based development environment. It combines an interactive whiteboard powered by Excalidraw with a fully fledged IDE powered by Coder.

    Key features include:

    • Interactive Whiteboard: Sketch and visualize ideas using Excalidraw.
    • Integrated IDE: Access terminals and VS Code directly within the whiteboard.
    • Cloud Development: Access your development environment from any device via the browser.
    • Desktop Integration: Access your VM from desktop clients like VS Code and Cursor.

  2. Configure Keycloak for OIDC

    main

    Keycloak acts as the OIDC provider for Coder and the Pad App. Follow these steps to configure it:

    1. Access Admin Console: Go to http://localhost:8080.
    2. Create a Realm: Create a new realm (e.g., pad-ws).
    3. Create a Client:
      • Client ID: e.g., pad-ws-client.
      • Client Authentication: Enable this.
      • Valid Redirect URIs: Add * (for development only).
    4. Retrieve Credentials:
      • Go to Clients -> [Your Client ID] -> Credentials tab.
      • Copy the Client secret.
      • Update .env with:
        OIDC_REALM=your_oidc_realm
OIDC_CLIENT_ID=your_client_id
OIDC_CLIENT_SECRET=your_client_secret
    5. Create a User:
      • Go to Users -> Create user.
      • Important: Check the Email verified box.
      • Set a password in the Credentials tab.
    6. Configure Audience Mapper:
      • Go to Clients -> [Your Client ID] -> Client Scopes.
      • Select the dedicated scope: [clientid]-dedicated.
      • Click Configure a new mapper -> Audience.
      • Set Included Client Audience to match your Client ID.
      • Ensure Add to access token is On.

  3. Self-host pad.ws using Docker Compose

    main

    To self-host pad.ws for development and testing, you can use the provided docker-compose.yml.

    ⚠️ WARNING: The current setup is intended for localhost development and testing only. It is not secure for production use without significant additional configuration.

    Prerequisites

    • Linux Host (Tested on Ubuntu)
    • Docker & Docker Compose installed

    Setup Steps

    1. Initialize Environment Variables Copy the template to create your .env file:

      cp .env.template .env

    2. Start Infrastructure Services Run the following commands to start the required containers:

      # Start PostgreSQL for persistence
docker compose up -d postgres 

# Start Redis for caching and sessions
docker compose up -d redis

# Start Keycloak for OIDC authentication
docker compose up -d keycloak 

# Start Coder for development environments
docker compose up -d coder

# Start the Pad App (FastAPI backend and frontend)
docker compose up -d pad

    3. Access the Application Once all services are running and configured, access the app at http://localhost:8000.

    cp .env.template .env
docker compose up -d postgres
docker compose up -d redis
docker compose up -d keycloak
docker compose up -d coder
docker compose up -d pad

  4. Configure Coder for pad.ws

    main

    Coder powers the cloud development environments. To integrate it with pad.ws, follow these steps:

    1. Get Docker Group ID: Run this command on your host to find the ID needed for permissions:

      getent group docker | cut -d: -f3

      Add this to your .env as DOCKER_GROUP_ID.

    2. Setup Coder Instance:

      • Run docker compose up -d coder.
      • Access the UI at http://localhost:7080 and create an admin user.
      • Create a template using "Start from template" (e.g., using a docker-containers base image).

    3. Retrieve Coder API Details:

      • API Key: In Coder UI, go to Account -> API Keys and generate a token. Add to .env as CODER_API_KEY.
      • Template ID: Visit http://localhost:7080/api/v2/templates to find the id of your template. Add to .env as CODER_TEMPLATE_ID.
      • Organization ID: Visit http://localhost:7080/api/v2/organizations to find your organization id. Add to .env as CODER_DEFAULT_ORGANIZATION.

    4. Workspace Naming (Optional): If you use a custom workspace name, set CODER_WORKSPACE_NAME in your .env. Otherwise, it defaults to ubuntu.

    getent group docker | cut -d: -f3

  6. Initialize CoderAPI client

    main

    To use the CoderAPI client, you must ensure the following environment variables are set in your configuration:

    • CODER_API_KEY: Your Coder session token.
    • CODER_URL: The base URL of your Coder instance.
    • CODER_TEMPLATE_ID: The ID of the template to use for workspace creation.
    • CODER_DEFAULT_ORGANIZATION: The default organization ID.

    If CODER_API_KEY or CODER_URL are missing, the constructor will raise a ValueError.

  8. Configure Keycloak environment variables

    main

    The keycloak service (used for OIDC/Authentication) requires these environment variables:

    • KEYCLOAK_PORT: The port on which Keycloak will be accessible.
    • KEYCLOAK_ADMIN: The admin username.
    • KEYCLOAK_ADMIN_PASSWORD: The admin password.
    • POSTGRES_DB: The database name (used for KC_DB_URL).
    • POSTGRES_USER: The database username (used for KC_DB_USERNAME).
    • POSTGRES_PASSWORD: The database password (used for KC_DB_PASSWORD).

  9. Configure PostgreSQL environment variables

    main

    When self-hosting pad.ws using Docker Compose, the postgres service requires the following environment variables to initialize the database:

    • POSTGRES_USER: The username for the database.
    • POSTGRES_PASSWORD: The password for the database.
    • POSTGRES_DB: The name of the database to create.

  10. Configure pad.ws application environment variables

    main

    The pad service (the main application) requires the following environment variables to connect to its dependencies and handle authentication:

    Authentication (OIDC)

    • OIDC_CLIENT_ID: The client ID for OIDC.
    • OIDC_CLIENT_SECRET: The client secret for OIDC.
    • OIDC_SERVER_URL: The base URL of the OIDC server (e.g., http://localhost:${KEYCLOAK_PORT}).
    • OIDC_REALM: The OIDC realm name.
    • REDIRECT_URI: The callback URL for authentication.

    Database & Cache

    • POSTGRES_USER: Database username.
    • POSTGRES_PASSWORD: Database password.
    • POSTGRES_DB: Database name.
    • POSTGRES_HOST: Database host (set to localhost in the compose file).
    • POSTGRES_PORT: Database port.
    • REDIS_HOST: Redis host.
    • REDIS_PORT: Redis port.
    • REDIS_PASSWORD: Redis password.

    Coder Integration

    • CODER_API_KEY: API key for communicating with Coder.
    • CODER_URL: The base URL of the Coder instance.
    • CODER_TEMPLATE_ID: The ID of the Coder template to use.
    • CODER_DEFAULT_ORGANIZATION: The default organization in Coder.

    Application Settings

    • API_WORKERS: Number of API workers.
    • FRONTEND_URL: The URL of the frontend application.

  11. Configure OIDC for the Session class

    main

    The Session class requires an oidc_config dictionary containing the following keys:

    • server_url: The base URL of the OIDC provider.
    • realm: The OIDC realm name.
    • client_id: The OIDC client identifier.
    • client_secret: The OIDC client secret (required for token refresh).
    • redirect_uri: The URI to which the provider redirects after authentication.

  12. Configure Coder environment variables

    main

    The coder service requires the following environment variables for integration with Keycloak and PostgreSQL:

    • CODER_PORT: The port used for the Coder access URL.
    • OIDC_REALM: The Keycloak realm name.
    • OIDC_CLIENT_ID: The OIDC client ID.
    • OIDC_CLIENT_SECRET: The OIDC client secret.
    • CODER_ADDITIONAL_CSP_POLICY: Additional Content Security Policy settings.
    • DOCKER_GROUP_ID: The group ID for accessing /var/run/docker.sock.
    • POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB: Database credentials used to construct the CODER_PG_CONNECTION_URL.