98 lines
3.1 KiB
Markdown
98 lines
3.1 KiB
Markdown
# PyServe
|
|
|
|
Python application orchestrator and HTTP server. Runs multiple ASGI/WSGI applications through a single entry point with process isolation, health monitoring, and auto-restart.
|
|
|
|
<img src="https://raw.githubusercontent.com/ShiftyX1/PyServe/refs/heads/master/images/logo.png" alt="PyServe Logo" width="150"/>
|
|
|
|
Website: [pyserve.org](https://pyserve.org) · Documentation: [docs.pyserve.org](https://docs.pyserve.org)
|
|
|
|
## Overview
|
|
|
|
PyServe manages multiple Python web applications (FastAPI, Flask, Django, etc.) as isolated subprocesses behind a single gateway. Each app runs on its own port with independent lifecycle, health checks, and automatic restarts on failure.
|
|
|
|
```
|
|
PyServe Gateway (:8000)
|
|
│
|
|
┌────────────────┼────────────────┐
|
|
▼ ▼ ▼
|
|
FastAPI Flask Starlette
|
|
:9001 :9002 :9003
|
|
/api/* /admin/* /ws/*
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
git clone https://github.com/ShiftyX1/PyServe.git
|
|
cd PyServe
|
|
make init
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```yaml
|
|
# config.yaml
|
|
server:
|
|
host: 0.0.0.0
|
|
port: 8000
|
|
|
|
extensions:
|
|
- type: process_orchestration
|
|
config:
|
|
apps:
|
|
- name: api
|
|
path: /api
|
|
app_path: myapp.api:app
|
|
|
|
- name: admin
|
|
path: /admin
|
|
app_path: myapp.admin:app
|
|
```
|
|
|
|
```bash
|
|
pyserve -c config.yaml
|
|
```
|
|
|
|
Requests to `/api/*` are proxied to the api process, `/admin/*` to admin.
|
|
|
|
## Process Orchestration
|
|
|
|
The main case of using PyServe is orchestration of python web applications. Each application runs as a separate uvicorn process on a dynamically or manually allocated port (9000-9999 by default). PyServe proxies requests to the appropriate process based on URL path.
|
|
|
|
For each application you can configure the number of workers, environment variables, health check endpoint path, and auto-restart parameters. If a process crashes or stops responding to health checks, PyServe automatically restarts it with exponential backoff.
|
|
|
|
WSGI applications (Flask, Django) are supported through automatic wrapping — just specify `app_type: wsgi`.
|
|
|
|
## In-Process Mounting
|
|
|
|
For simpler cases when process isolation is not needed, applications can be mounted directly into the PyServe process via the `asgi` extension. This is lighter and faster, but all applications share one process.
|
|
|
|
## Static Files & Routing
|
|
|
|
PyServe can serve static files with nginx-like routing: regex patterns, SPA fallback for frontend applications, custom caching headers. Routes are processed in priority order — exact match, then regex, then default.
|
|
|
|
## Reverse Proxy
|
|
|
|
Requests can be proxied to external backends. Useful for integration with legacy services or microservices in other languages.
|
|
|
|
## CLI
|
|
|
|
```bash
|
|
pyserve -c config.yaml
|
|
pyserve --host 0.0.0.0 --port 9000
|
|
pyserve --debug
|
|
pyserve --version
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
make test # run tests
|
|
make lint # linting
|
|
make format # formatting
|
|
```
|
|
|
|
## License
|
|
|
|
[MIT License](./LICENSE)
|