A WebSocket Client/Server Skeleton Using FastAPI

A production-ready WebSocket client/server app using FastAPI.

docker run --rm --name websocket-python-example -p 8080:8080 -it jecklgamis/websocket-python-example:main

Tech Stack

• FastAPI - async web framework with WebSocket support
• websockets - WebSocket client library
• Pydantic v2 - validation and settings management
• Docker - containerized deployment (Python 3.12-slim)
• Helm - Kubernetes deployment chart
• Ruff - linting and formatting
• pytest - testing with async support

Project Structure

├── app/
│   ├── __init__.py        # Global logging init (INFO level)
│   ├── main.py            # FastAPI application entry point
│   ├── config.py          # Environment-specific settings (dev/test/prod)
│   └── routers/           # API route handlers
│       └── websocket.py   # WebSocket /ws endpoint
├── tests/                 # Test suite
├── deployment/
│   └── k8s/helm/          # Helm chart and deploy Makefile
├── websocket_client.py    # WebSocket client
├── run-server.sh          # Start the server
├── run-client.sh          # Start the client
├── Dockerfile
├── Makefile
└── pyproject.toml

Getting Started

Prerequisites

• Python 3.12+
• uv (recommended)
• Docker (for containerized deployment)

# Clone the repository
git clone git@github.com:jecklgamis/websocket-python-example.git && cd websocket-python-example

# Install dependencies
make install-deps

# Start the dev server (uses .env.dev by default)
make run-dev

The server will be available at http://localhost:8080. This will reload on file changes.

Running the Client

./run-client.sh

Type a message and press Enter to send. The server echoes it back. Press Ctrl+C to quit.

Using Docker

# Build and run
make up

# Or separately
make docker-image
make docker-run

Endpoints

Interactive API docs are available at /docs (Swagger UI) and /redoc.

Development

# Run tests
make test

# Lint and type-check
make lint

# Auto-fix and format
make format

# Dependency vulnerability scan
make audit

# Full pipeline (clean, install, format, lint, test, docker-image)
make all

Helm Chart

A Helm chart is provided in deployment/k8s/helm/ for Kubernetes deployment.

cd deployment/k8s/helm

# Dry run to verify
make dry-run

# Install
make install

# Upgrade after changes
make upgrade

# Rollback
make rollback

# Uninstall
make uninstall

Default configuration in chart/values.yaml:

Configuration

Settings are managed via environment variables and loaded from env-specific files. Set APP_ENV to select the environment:

# Run with a specific environment
APP_ENV=prod make run

Environment Variables

Source

Full source code available on GitHub: jecklgamis/websocket-python-example

• python
• fastapi
• websocket
• docker
• kubernetes