Brohammad / Brohammad/VoxForge

Write a horizontal scaling guide (multi-worker + sticky sessions)

Open
#28 0 comments 0 reactions 0 assignees View on GitHub
documentation help wanted
Dominant language
Python
Stars
4
Forks
1
Avg merge
5d 13m
Merged PRs (30d)
10

Description

## Summary

Production compose uses one uvicorn worker. `docs/deployment/operations.md` has three bullets. Roadmap v1.1 wants a real scaling guide.

## Context

- Known limitation: single uvicorn worker
- WebSocket voice needs sticky sessions if you add replicas
- Postgres/Redis should move to managed services before app replicas

## Scope

New doc e.g. `docs/deployment/scaling.md` covering:
- Why `--workers 1` today
- Sticky sessions / WebSocket routing
- Session state in Redis vs in-process
- Knowledge worker and LiveKit worker as separate services
- What breaks if you naively set workers > 1

Link it from operations.md, deployment README, and known-limitations.

## Out of scope

Implementing multi-instance production in this repo’s default compose.

Contributor guide

Open the contributing guide

Research direction

Start with docs/deployment/operations.md, the deployment README, and the known-limitations documentation to understand the current single-worker setup and existing links. Create the scaling guide covering the listed worker, session, routing, and service-separation topics, then link it from all three locations. Done means the documentation explains the multi-worker risks and scaling prerequisites without changing the default compose deployment.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, fastapi, postgres, python, redis
Domain
backend, devops, documentation, infrastructure
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
75/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.