| Project | Status | |
|---|---|---|
| CI/CD |   |
|
| Quality | ||
| Community |       |
|
| Meta |        |
Litestar Fullstack Reference Application
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), and Structlog
- Extends built-in Litestar click CLI
- Frontend integrated with ViteJS and includes Jinja2 templates that integrate with Vite websocket/HMR support
- Multi-stage Docker build using a minimal Python 3.11 runtime image.
- 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
Quick Start
To quickly get a development environment running, run the following:
make install
. .venv/bin/activateCommand Examples
App Commands
❯ 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:create_app'
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ 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. │
│ run-all Starts the application server & worker in a single command. │
│ schema Manage server-side OpenAPI schemas. │
│ sessions Manage server-side sessions. │
│ users Manage application users. │
│ version Show the currently installed Litestar version. │
│ worker Manage application background workers. │
╰──────────────────────────────────────────────────────────────────────────────╯
Database Commands
❯ 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. │
╰──────────────────────────────────────────────────────────────────────────────╯
Upgrading the Database
❯ 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 recreatingWorker Commands
❯ 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. │
╰──────────────────────────────────────────────────────────────────────────────╯
Run Commands
To run the application through Uvicorn using the standard Litestar CLI, you can use the following:
❯ app run --help
Using Litestar app from env: 'app.asgi:create_app'
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 ────────────────────────────────────────────────────────────────────╮
│ --reload -r Reload server on │
│ changes │
│ --reload-dir -R TEXT Directories to watch │
│ for file changes │
│ (TEXT) │
│ --port -p INTEGER Serve under this port │
│ (INTEGER) │
│ [default: 8000] │
│ --wc,--web-concurrency -W INTEGER RANGE The number of HTTP │
│ [1<=x<=7] workers to launch │
│ (INTEGER RANGE) │
│ [default: 1; 1<=x<=7] │
│ --host -H TEXT Server under this host │
│ (TEXT) │
│ [default: 127.0.0.1] │
│ --fd,--file-descriptor -F INTEGER Bind to a socket from │
│ this file descriptor. │
│ (INTEGER) │
│ --uds,--unix-domain-so… -U TEXT Bind to a UNIX domain │
│ socket. │
│ (TEXT) │
│ --debug -d Run app in debug mode │
│ --pdb,--use-pdb -P Drop into PDB on an │
│ exception │
│ --help -h Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
The above command will not start the background workers. Those can be launched separately in another terminal.
Alternately, the run-all command will automatically start the background workers in separate processes.
❯ app run-all --help
Using Litestar app from env: 'app.asgi:create_app'
Usage: app run-all [OPTIONS] COMMAND [ARGS]...
Starts the application server & worker in a single command.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --host TEXT Host interface to listen │
│ on. Use 0.0.0.0 for all │
│ available interfaces. │
│ (TEXT) │
│ [default: 0.0.0.0] │
│ --port -p INTEGER Port to bind. (INTEGER) │
│ [default: 8000] │
│ --http-workers INTEGER RANGE [1<=x<=7] The number of HTTP worker │
│ processes for handling │
│ requests. │
│ (INTEGER RANGE) │
│ [default: 7; 1<=x<=7] │
│ --worker-concurrency INTEGER RANGE [x>=1] The number of │
│ simultaneous jobs a │
│ worker process can │
│ execute. │
│ (INTEGER RANGE) │
│ [default: 1; x>=1] │
│ --reload -r Enable reload │
│ --verbose -v Enable verbose logging. │
│ --debug -d Enable debugging. │
│ --help -h Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
Installation and Configuration
We have documented the process to help you get the repository up and running. Check out the documentation for more information.