# 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)