| Project | Status | |
|---|---|---|
| CI/CD |   | |
| Quality | ||
| Community |       | |
| Meta |        |
This is a reference application that you can use to get your next Litestar application running quickly.
It contains most of the boilerplate required for a production web API with features like:
- Latest Litestar configured with best practices
- Integration with SQLAlchemy 2.0, SAQ (Simple Asynchronous Queue), Structlog, and Granian
- Extends built-in Litestar click CLI
- Frontend integrated with Vite and includes Jinja2 templates that integrate with Vite websocket/HMR support
- Multi-stage Docker build using a minimal Python 3.13 runtime image.
- Optional Multi-stage Distroless Docker build.
- Pre-configured user model that includes teams and associated team roles
- Examples of using guards for superuser and team-based auth.
- Examples using raw SQL for more complex queries
Take what you need and adapt it to your own projects
To quickly get a development environment running, run the following:
make install . .venv/bin/activatecp .env.local.example .env make start-infra # this starts a database and redis instance only # this will start the SAQ worker, Vite development process, and Litestar uv run app run # to stop the database and redis, run make stop-infraIf you want to run the entire development environment containerized, you can run the following:
docker compose upWe have documented the process to help you get the repository up and running. Check out the documentation for more information.
Command Examples
❯ app Usage: app [OPTIONS] COMMAND [ARGS]... Litestar CLI. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --app TEXT Module path to a Litestar application (TEXT) │ │ --app-dir DIRECTORY Look for APP in the specified directory, by adding │ │ this to the PYTHONPATH. Defaults to the current │ │ working directory. │ │ (DIRECTORY) │ │ --help -h Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ Using Litestar app from env: 'app.asgi:app' Loading environment configuration from .env ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │ assets Manage Vite Tasks. │ │ database Manage SQLAlchemy database components. │ │ info Show information about the detected Litestar app. │ │ routes Display information about the application's routes. │ │ run Run a Litestar app. │ │ schema Manage server-side OpenAPI schemas. │ │ sessions Manage server-side sessions. │ │ users Manage application users and roles. │ │ version Show the currently installed Litestar version. │ │ workers Manage background task workers. │ ╰──────────────────────────────────────────────────────────────────────────────╯ Alembic integration is built directly into the CLI under the database command.
The following shows the commands available with the database CLI command.
❯ app database Using Litestar app from env: 'app.asgi:create_app' Usage: app database [OPTIONS] COMMAND [ARGS]... Manage SQLAlchemy database components. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │ downgrade Downgrade database to a specific revision. │ │ init Initialize migrations for the project. │ │ make-migrations Create a new migration revision. │ │ merge-migrations Merge multiple revisions into a single new revision. │ │ show-current-revision Shows the current revision for the database. │ │ stamp-migration Mark (Stamp) a specific revision as current without │ │ applying the migrations. │ │ upgrade Upgrade database to a specific revision. │ ╰──────────────────────────────────────────────────────────────────────────────╯ To upgrade the database to the latest revision, you can use the following command:
❯ app database upgrade Using Litestar app from env: 'app.asgi:create_app' Starting database upgrade process ─────────────────────────────────────────────── Are you sure you you want migrate the database to the "head" revision? [y/n]: y 2023-10-01T19:44:13.536101Z [debug ] Using selector: EpollSelector 2023-10-01T19:44:13.623437Z [info ] Context impl PostgresqlImpl. 2023-10-01T19:44:13.623617Z [info ] Will assume transactional DDL. 2023-10-01T19:44:13.667920Z [info ] Running upgrade -> c3a9a11cc35d, init 2023-10-01T19:44:13.774932Z [debug ] new branch insert c3a9a11cc35d 2023-10-01T19:44:13.783804Z [info ] Pool disposed. Pool size: 5 Connections in pool: 0 Current Overflow: -5 Current Checked out connections: 0 2023-10-01T19:44:13.784013Z [info ] Pool recreatingThe following shows the commands available with the worker CLI command. This controls the saq worker processes. However, when using the SAQ_USE_SERVER_LIFESPAN=True environment variable, the background workers are automatically started and stopped with the Litestar HTTP server.
❯ app worker Using Litestar app from env: 'app.asgi:create_app' Usage: app worker [OPTIONS] COMMAND [ARGS]... Manage application background workers. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --help -h Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │ run Starts the background workers. │ ╰──────────────────────────────────────────────────────────────────────────────╯ To run the application through Granian (HTTP1 or HTTP2) using the standard Litestar CLI, you can use the following:
❯ app run --help Using Litestar app from env: 'app.asgi:app' Loading environment configuration from .env Usage: app run [OPTIONS] Run a Litestar app. The app can be either passed as a module path in the form of <module name>.<submodule>:<app instance or factory>, set as an environment variable LITESTAR_APP with the same format or automatically discovered from one of these canonical paths: app.py, asgi.py, application.py or app/__init__.py. When auto-discovering application factories, functions with the name ``create_app`` are considered, or functions that are annotated as returning a ``Litestar`` instance. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --port -p INTEGER Serve under this port │ │ (INTEGER) │ │ [default: 8000] │ │ --wc,--web-concurrency… -W INTEGER RANGE The number of processes │ │ [1<=x<=7] to start. │ │ (INTEGER RANGE) │ │ [default: 1; 1<=x<=7] │ │ --threads INTEGER RANGE [x>=1] The number of threads. │ │ (INTEGER RANGE) │ │ [default: 1; x>=1] │ │ --blocking-threads INTEGER RANGE [x>=1] The number of blocking │ │ threads. │ │ (INTEGER RANGE) │ │ [default: 1; x>=1] │ │ --threading-mode THREADMODES Threading mode to use. │ │ (THREADMODES) │ │ --http HTTPMODES HTTP Version to use │ │ (HTTP or HTTP2) │ │ (HTTPMODES) │ │ --opt Enable additional event │ │ loop optimizations │ │ --backlog INTEGER RANGE [x>=128] Maximum number of │ │ connections to hold in │ │ backlog. │ │ (INTEGER RANGE) │ │ [default: 1024; x>=128] │ │ --host -H TEXT Server under this host │ │ (TEXT) │ │ [default: 127.0.0.1] │ │ --ssl-keyfile FILE SSL key file (FILE) │ │ --ssl-certificate FILE SSL certificate file │ │ (FILE) │ │ --create-self-signed-c… If certificate and key │ │ are not found at │ │ specified locations, │ │ create a self-signed │ │ certificate and a key │ │ --http1-buffer-size INTEGER RANGE Set the maximum buffer │ │ [x>=8192] size for HTTP/1 │ │ connections │ │ (INTEGER RANGE) │ │ [default: 417792; │ │ x>=8192] │ │ --http1-keep-alive/--n… Enables or disables │ │ HTTP/1 keep-alive │ │ [default: │ │ http1-keep-alive] │ │ --http1-pipeline-flush… Aggregates HTTP/1 │ │ flushes to better │ │ support pipelined │ │ responses │ │ (experimental) │ │ --http2-adaptive-windo… Sets whether to use an │ │ adaptive flow control │ │ for HTTP2 │ │ --http2-initial-connec… INTEGER Sets the max │ │ connection-level flow │ │ control for HTTP2 │ │ (INTEGER) │ │ --http2-initial-stream… INTEGER Sets the │ │ `SETTINGS_INITIAL_WIND… │ │ option for HTTP2 │ │ stream-level flow │ │ control │ │ (INTEGER) │ │ --http2-keep-alive-int… OPTIONAL Sets an interval for │ │ HTTP2 Ping frames │ │ should be sent to keep │ │ a connection alive │ │ (OPTIONAL) │ │ --http2-keep-alive-tim… INTEGER Sets a timeout for │ │ receiving an │ │ acknowledgement of the │ │ HTTP2 keep-alive ping │ │ (INTEGER) │ │ --http2-max-concurrent… INTEGER Sets the │ │ SETTINGS_MAX_CONCURREN… │ │ option for HTTP2 │ │ connections │ │ (INTEGER) │ │ --http2-max-frame-size INTEGER Sets the maximum frame │ │ size to use for HTTP2 │ │ (INTEGER) │ │ --http2-max-headers-si… INTEGER Sets the max size of │ │ received header frames │ │ (INTEGER) │ │ --http2-max-send-buffe… INTEGER Set the maximum write │ │ buffer size for each │ │ HTTP/2 stream │ │ (INTEGER) │ │ --url-path-prefix TEXT URL path prefix the app │ │ is mounted on │ │ (TEXT) │ │ --debug -d Run app in debug mode │ │ --pdb,--use-pdb -P Drop into PDB on an │ │ exception │ │ --respawn-failed-worke… Enable workers respawn │ │ on unexpected exit │ │ --reload -r Reload server on │ │ changes │ │ --help -h Show this message and │ │ exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ 
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
