| 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), 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 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
To quickly get a development environment running, run the following:
make install
. .venv/bin/activate❯ 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. │
╰──────────────────────────────────────────────────────────────────────────────╯
❯ 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. │
╰──────────────────────────────────────────────────────────────────────────────╯
❯ 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 recreating❯ 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 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. │
╰──────────────────────────────────────────────────────────────────────────────╯
Commands to help you get this repository running.
Most of the development related tasks are included in the Makefile. To install an environment with all development packages run:
make installThis command does the following:
- install
pdmif it is not available in the path. - create a virtual environment with all dependencies configured
- build assets to be hosted by production asset server
There is a sample .env file located in the root of the repository.
cp .env.example .envNote SECRET_KEY, DATABASE_URI, and REDIS_URL are the most important config settings. Be sure to set this properly.
You can generate a SECRET_KEY by running:
❯ openssl rand -base64 32
+U9UcN0meCsxkShMINkqZ7pcwpEpOC9AwOArZI6mYDU=You can run most of the database commands with the integrated CLI tool.
To deploy migration to the database, execute:
❯ app database upgrade
2023-06-16T16:55:17.048183Z [info ] Context impl PostgresqlImpl.
2023-06-16T16:55:17.048251Z [info ] Will assume transactional DDL.if DEV_MODE is set to true, the base template expects that Vite will be running. When you start the application, it will try to start the vite service with the HMR websocket connection enabled.
❯ app run-all -p 8080
Using Litestar app from env: 'app.asgi:create_app'
2023-10-01T20:19:06.493377Z [info ] starting all application services.
2023-10-01T20:19:06.493500Z [info ] starting Background worker processes.
2023-06-16T16:58:38.055247Z [info ] starting Vite
2023-06-16T16:58:38.056850Z [info ] Starting HTTP Server.
2023-06-16T16:58:38.791943Z [info ] Started server process [29108]
2023-06-16T16:58:38.792012Z [info ] Waiting for application startup.
2023-06-16T16:58:38.794260Z [info ] Application startup complete.
2023-06-16T16:58:38.794876Z [info ] Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
2023-06-16T16:58:38.803751Z [info ] Starting working pool
2023-06-16T16:58:38.804423Z [info ] Worker is starting up.
2023-06-16T16:58:38.804519Z [info ] Worker is starting up.
2023-06-16T16:58:38.816324Z [info ] Performing background worker task.
2023-06-16T16:58:39.188218Z [info ] Vite message=> [email protected] dev> vite
2023-06-16T16:58:39.894411Z [info ] Vite message=Forced re-optimization of dependencies
2023-06-16T16:58:39.923813Z [info ] Vite message= VITE v4.3.9 ready in 676 ms
2023-06-16T16:58:39.924023Z [info ] Vite message= ➜ Local: http://localhost:3000/static/ ➜ Network: use --host to exposeif DEV_MODE is false, the server will look for the static assets that are produced from the npm run build command. This command is automatically executed and the assets are bundled when running pdm build.
To manually rebuild assets, use the following:
npm run build # generates static assets from vite and
# files from the above command can be found in `src/app/domain/web/public`.
app run-allSample output:
❯ npm run build
> [email protected] build
> vue-tsc && vite build
vite v4.1.2 building for production...
✓ 15 modules transformed.
Generated an empty chunk: "vue".
../public/assets/vue-5532db34.svg 0.50 kB
../public/manifest.json 0.57 kB
../public/assets/main-b75adab1.css 1.30 kB │ gzip: 0.67 kB
../public/assets/vue-4ed993c7.js 0.00 kB │ gzip: 0.02 kB
../public/assets/main-17f9b70b.js 1.50 kB │ gzip: 0.80 kB
../public/assets/@vue-5be96905.js 52.40 kB │ gzip: 21.07 kB
❯ app run-all
2023-02-19 22:53:08 [info ] starting application.
2023-02-19 22:53:08 [info ] starting Background worker processes.
2023-02-19 22:53:08 [info ] Starting HTTP Server.This command will remove any existing environment and install a new environment with the latest dependencies.
make installThis command will upgrade all components of the application at the same time. It automatically executes:
pdm upgradenpm updatepre-commit autoupdate
make upgradeThis command will automatically execute the pre-commit process for the project.
make lintThis command is a shorthand for executing app database make-migrations.
make migrationsThis command is a shorthand for executing app database upgrade.
make migrateThis command executes all tests for the project.
make test