Collaborative Whiteboard

A real-time collaborative whiteboard application built with FastAPI, Vue.js, and Valkey. Draw, collaborate, and share ideas in real-time with multiple users.

Features

• Real-time collaborative drawing
• Multiple users can draw simultaneously
• WebSocket-based synchronization
• Persistent storage with Valkey
• Responsive web interface

Prerequisites

Choose one of the following methods to run the application:

Option 1: Docker (Recommended)

• Docker (v20.10+)
• Docker Compose (v2.0+)

Option 2: Local Development with uv

• Python (3.11+)
• uv - Fast Python package installer
• Valkey

Installation & Setup

Option 1: Running with Docker (Recommended)

This is the easiest way to get started. Docker will handle all dependencies and setup automatically.

1. Clone the repository

   git clone <repository-url>
   cd demo

2. Start the application

   docker-compose up -d

   This will start:

   • Valkey server on port 6379
   • Whiteboard backend on port 8000

3. Access the application

   Open your browser and navigate to:

   http://localhost:8000
   

4. View logs (optional)

   docker-compose logs -f whiteboard-backend

5. Stop the application

   docker-compose down

   To remove volumes as well:

   docker-compose down -v

Option 2: Running Locally with uv

For local development without Docker, use uv for faster dependency installation.

1. Clone the repository

   git clone <repository-url>
   cd demo

2. Install uv (if not already installed)

   # On macOS and Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # On Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Install Valkey

   On macOS:

   brew install valkey
   brew services start valkey

   On Ubuntu/Debian:

   sudo apt-get install valkey-server
   sudo systemctl start valkey-server

   On Windows:

   • Use Valkey Docker image [https://valkey.io/download/]

4. Create a virtual environment and install dependencies

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -r requirements.txt

5. Configure environment variables (optional)

   Create a .env file in the root directory:

   VALKEY_HOST=localhost
   VALKEY_PORT=6379
   VALKEY_DB=0

6. Run the application

   cd backend
   uvicorn main:app --host 0.0.0.0 --port 8000 --reload

7. Access the application

   Open your browser and navigate to:

   http://localhost:8000
   

Development

Project Structure

demo/
├── backend/
│   ├── __init__.py
│   ├── main.py          # FastAPI application entry point
│   ├── api.py           # API routes and WebSocket handlers
│   ├── database.py      # Valkey connection and operations
│   ├── models.py        # Data models
│   └── connections.py   # WebSocket connection management
├── frontend/
│   ├── index.html       # Main HTML file
│   └── assets/          # Static assets (CSS, JS)
├── docker-compose.yml   # Docker Compose configuration
├── Dockerfile          # Docker image configuration
├── requirements.txt    # Python dependencies
└── README.md          # This file

Making Changes

When running with Docker, the application automatically reloads when you make changes to the code (hot reload enabled).

For local development with uv, the --reload flag enables hot reloading.

API Endpoints

HTTP Endpoints

• GET / - Serve the frontend application
• GET /assets/* - Serve static assets

WebSocket Endpoints

• WS /ws - Real-time collaboration WebSocket connection

Technologies Used

• Backend: FastAPI, Python 3.11
• Database: Valkey
• Frontend: Vue.js, HTML5 Canvas
• Real-time: WebSocket (Socket.IO)
• Containerization: Docker, Docker Compose

Troubleshooting

Docker Issues

Port already in use:

# Check what's using the port
netstat -ano | findstr :8000  # Windows
lsof -i :8000                 # macOS/Linux

# Change the port in docker-compose.yml
ports:
  - "8001:8000"  # Use 8001 instead

Container won't start:

# Check logs
docker-compose logs whiteboard-backend

# Rebuild containers
docker-compose up --build

Local Development Issues

Module not found:

# Reinstall dependencies
uv pip install -r requirements.txt

Port 8000 already in use:

# Run on a different port
uvicorn main:app --host 0.0.0.0 --port 8001

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is open source and available under the MIT License.

Support

For issues, questions, or contributions, please open an issue on the repository.