Skip to content

Litestar Fullstack Reference Application with Vue, Vite, SQLAlchemy, Docker, Task Queues, and more!

License

Notifications You must be signed in to change notification settings

JackGuoo/litestar-fullstack

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Litestar Logo - Light Litestar Logo - Dark

Project Status
CI/CD Tests and Linting Documentation Building
Quality Coverage Quality Gate Status Maintainability Rating Reliability Rating Security Rating
Community Reddit Discord Matrix Medium Twitter Blog
Meta Litestar Project types - Mypy License - MIT Litestar Sponsors linting - Ruff code style - Black All Contributors

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/activate
Command 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 recreating

Worker 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.

About

Litestar Fullstack Reference Application with Vue, Vite, SQLAlchemy, Docker, Task Queues, and more!

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 90.5%
  • Dockerfile 3.0%
  • Makefile 2.6%
  • Jinja 1.3%
  • Mako 0.7%
  • TypeScript 0.7%
  • Other 1.2%