caddysnake

README

Caddy Snake 🐍

Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go.

This plugin provides native support for Python apps.

It embeds the Python interpreter inside Caddy and serves requests directly without going through a reverse proxy.

Supports both WSGI and ASGI, which means you can run all types of frameworks like Flask, Django and FastAPI.

Quickstart

Requirements

• Python >= 3.9 + dev files
• C compiler and build tools
• Go >= 1.21 and Xcaddy

Install requirements on Ubuntu 24.04:

$ sudo apt-get install python3-dev build-essential pkg-config golang
$ go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

You can also build with Docker.

Example usage: Flask

main.py

from flask import Flask

app = Flask(__name__)

@app.route("/hello-world")
def hello():
    return "Hello world!"

Caddyfile

http://localhost:9080 {
    route {
        python {
            module_wsgi "main:app"
        }
    }
}

Run:

$ pip install Flask
$ CGO_ENABLED=1 xcaddy build --with github.com/mliezun/caddy-snake
$ ./caddy run --config Caddyfile

$ curl http://localhost:9080/hello-world
Hello world!

See how to setup Hot Reloading

Example usage: FastAPI

main.py

from fastapi import FastAPI

@app.get("/hello-world")
def hello():
    return "Hello world!"

Caddyfile

http://localhost:9080 {
    route {
        python {
            module_asgi "main:app"
        }
    }
}

Run:

$ pip install fastapi
$ CGO_ENABLED=1 xcaddy build --with github.com/mliezun/caddy-snake
$ ./caddy run --config Caddyfile

$ curl http://localhost:9080/hello-world
Hello world!

NOTE: It's possible to enable/disable lifespan events by adding the lifespan on|off directive to your Caddy configuration. In the above case the lifespan events are disabled because the directive was omitted.

See how to setup Hot Reloading

Use docker image

There are docker images available with the following Python versions: 3.9, 3.10, 3.11, 3.12

Example usage:

FROM ghcr.io/mliezun/caddy-snake:latest-py3.12

WORKDIR /app

# Copy your project into app
COPY . /app

# Caddy snake is already installed and has support for Python 3.12
CMD ["caddy", "run", "--config", "/app/Caddyfile"]

Build with Docker

There's a template file in the project: builder.Dockerfile. It supports build arguments to configure which Python or Go version is desired for the build.

Make sure to use the same Python version as you have installed in your system.

You can copy the contents of the builder Dockerfile and execute the following commands to get your Caddy binary:

docker build -f builder.Dockerfile --build-arg PY_VERSION=3.9 -t caddy-snake .

docker run --rm -v $(pwd):/output caddy-snake

NOTE

It's also possible to provide virtual environments with the following syntax:

python {
    module_wsgi "main:app"
    venv "./venv"
}

What it does behind the scenes is to append venv/lib/python3.x/site-packages to python sys.path.

Disclaimer: Currently, when you provide a venv it gets added to the global sys.path, which in consequence means all apps have access to those packages.

Hot reloading

Currently the Python app is not reloaded by the plugin if a file changes. But it is possible to setup using watchmedo to restart the Caddy process.

watchmedo auto-restart -d . -p "*.py" --recursive \
    -- caddy run --config Caddyfile

Dev resources

• Python C API Docs
• Python C API New Type Tutorial
• Bjoern WSGI
• WSGO
• embedding-python-in-golang | WSGI Django implementation
• Apache mod_wsgi
• FrankenPHP
• WSGI Standard PEP 3333
• ASGI Spec

LICENSE

MIT License.

Documentation

Overview

Caddy plugin to serve Python apps.

Index

• type AppServer
• type Asgi
  • func NewAsgi(asgi_pattern string, venv_path string, lifespan bool) (*Asgi, error)
  • func (m *Asgi) Cleanup() (err error)
  • func (m *Asgi) HandleRequest(w http.ResponseWriter, r *http.Request) error
• type AsgiOperations
• type AsgiRequestHandler
  • func NewAsgiRequestHandler(w http.ResponseWriter, r *http.Request) *AsgiRequestHandler
• type CaddySnake
  • func (CaddySnake) CaddyModule() caddy.ModuleInfo
  • func (m *CaddySnake) Cleanup() error
  • func (f *CaddySnake) Provision(ctx caddy.Context) error
  • func (f CaddySnake) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (f *CaddySnake) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (m *CaddySnake) Validate() error
• type Wsgi
  • func NewWsgi(wsgi_pattern string, venv_path string) (*Wsgi, error)
  • func (m *Wsgi) Cleanup() error
  • func (m *Wsgi) HandleRequest(w http.ResponseWriter, r *http.Request) error
• type WsgiRequestHandler

Types

type AppServer

type AppServer interface {
	Cleanup() error
	HandleRequest(w http.ResponseWriter, r *http.Request) error
}

AppServer defines the interface to interacting with a WSGI or ASGI server

type Asgi

type Asgi struct {
	// contains filtered or unexported fields
}

Asgi stores a reference to a Python Asgi application

func NewAsgi

func NewAsgi(asgi_pattern string, venv_path string, lifespan bool) (*Asgi, error)

NewAsgi imports a Python ASGI app

func (*Asgi) Cleanup

func (m *Asgi) Cleanup() (err error)

Cleanup deallocates CGO resources used by Asgi app

func (*Asgi) HandleRequest

func (m *Asgi) HandleRequest(w http.ResponseWriter, r *http.Request) error

HandleRequest passes request down to Python ASGI app and writes responses and headers.

type AsgiOperations

type AsgiOperations struct {
	// contains filtered or unexported fields
}

AsgiOperations stores operations that should be executed in the background

type AsgiRequestHandler

type AsgiRequestHandler struct {
	// contains filtered or unexported fields
}

AsgiRequestHandler stores pointers to the request and the response writer

func NewAsgiRequestHandler

func NewAsgiRequestHandler(w http.ResponseWriter, r *http.Request) *AsgiRequestHandler

NewAsgiRequestHandler initializes handler and starts queue that consumes operations in the background.

type CaddySnake

type CaddySnake struct {
	ModuleWsgi string `json:"module_wsgi,omitempty"`
	ModuleAsgi string `json:"module_asgi,omitempty"`
	Lifespan   string `json:"lifespan,omitempty"`
	VenvPath   string `json:"venv_path,omitempty"`
	// contains filtered or unexported fields
}

CaddySnake module that communicates with a Python app

func (CaddySnake) CaddyModule

func (CaddySnake) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*CaddySnake) Cleanup

func (m *CaddySnake) Cleanup() error

Cleanup frees resources uses by module

func (*CaddySnake) Provision

func (f *CaddySnake) Provision(ctx caddy.Context) error

Provision sets up the module.

func (CaddySnake) ServeHTTP

func (f CaddySnake) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*CaddySnake) UnmarshalCaddyfile

func (f *CaddySnake) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler.

func (*CaddySnake) Validate

func (m *CaddySnake) Validate() error

Validate implements caddy.Validator.

type Wsgi

type Wsgi struct {
	// contains filtered or unexported fields
}

Wsgi stores a reference to a Python Wsgi application

func NewWsgi

func NewWsgi(wsgi_pattern string, venv_path string) (*Wsgi, error)

NewWsgi imports a WSGI app

func (*Wsgi) Cleanup

func (m *Wsgi) Cleanup() error

Cleanup deallocates CGO resources used by Wsgi app

func (*Wsgi) HandleRequest

func (m *Wsgi) HandleRequest(w http.ResponseWriter, r *http.Request) error

HandleRequest passes request down to Python Wsgi app and writes responses and headers.

type WsgiRequestHandler

type WsgiRequestHandler struct {
	// contains filtered or unexported fields
}

WsgiRequestHandler tracks the state of a HTTP request to a WSGI App