Skip to content

Commit e4b3369

Browse files
JacobCoffeecofin
JacobCoffee
authored and
cofin
committed
docs(WIP): add some usage docs
1 parent bcfb051 commit e4b3369

File tree

5 files changed

+189
-0
lines changed

5 files changed

+189
-0
lines changed

‎docs/examples/app.service‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[Unit]
2+
Description=Litestar Fullstack App
3+
After=network.target
4+
5+
[Service]
6+
User=some-user
7+
Group=some-group
8+
WorkingDirectory=/opt/litestar-app/
9+
Environment="PATH=/opt/litestar-app/.venv/bin"
10+
ExecStart=/opt/litestar-app/.venv/bin/app run-all --host 127.0.0.1 --port 8000 --http-workers 2
11+
12+
[Install]
13+
WantedBy=multi-user.target

‎docs/usage/deployment.rst‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
==========
2+
Deployment
3+
==========
4+
5+
.. note:: This section is a work in progress.
6+
Would you like to contribute? See the :doc:`/contribution-guide`.
7+
8+
No matter how you decide to deploy your application, this is a Litestar app and the
9+
:doc:`Litestar Deployment Guide <litestar:topics/deployment/index>` is a great place to start.
10+
11+
Docker
12+
------
13+
14+
This repository contains example ``Dockerfile``'s and ``docker-compose.yml``'s for deploying
15+
your application for development and production.
16+
17+
Development
18+
^^^^^^^^^^^
19+
20+
Everyone's development environment is different, but we've included a ``docker-compose.infra.yml`` file that
21+
contains the required infrastructure services for running the application.
22+
This includes a PostgreSQL database, a Redis cache, local mail with `MailHog <https://github.com/mailhog/MailHog>`_,
23+
and object storage with `Minio <https://min.io/>`_.
24+
25+
This allows you to just `docker compose up` to start your services, and then run the application
26+
locally with (for example) the Litestar CLI: ``litestar run --debug --reload``.
27+
28+
We also have a ``Dockerfile`` for development:
29+
30+
.. dropdown:: Example ``Dockerfile`` for development
31+
32+
.. literalinclude:: ../../deploy/docker/dev/Dockerfile
33+
:language: dockerfile
34+
:linenos:
35+
36+
Production
37+
^^^^^^^^^^
38+
39+
.. dropdown:: Example ``Dockerfile`` for production
40+
41+
.. literalinclude:: ../../deploy/docker/run/Dockerfile
42+
:language: dockerfile
43+
:linenos:
44+
45+
For Docker Compose, run the ``docker-compose.yml`` file, replacing the environment
46+
variables as needed with your own values.
47+
48+
Railway
49+
-------
50+
51+
This repository also has a template on `Railway <https://railway.app/template/KmHMvQ?referralCode=BMcs0x>`_.
52+
53+
.. note:: This link is a referral link that will give us a credit if you decide to utilize the service
54+
and host your application(s) on their platform. This helps us to continue to provide great open source
55+
software for the community by offsetting our hosting costs, and doesn't cost you anything extra.
56+
57+
Cloud Platforms
58+
---------------
59+
60+
.. todo:: Add examples for deploying to cloud platforms.
61+
Would you like to contribute? See the :doc:`/contribution-guide`.
62+
63+
64+
Service
65+
-------
66+
67+
You can also wrap this application into a ``systemd`` service, or use a process manager like
68+
`Supervisor <http://supervisord.org/>`_.
69+
70+
.. dropdown:: Example ``systemd`` service
71+
72+
.. literalinclude:: ../examples/app.service
73+
:language: ini
74+
:linenos:
75+
76+
.. dropdown:: Manage the ``systemd`` service
77+
78+
.. code-block:: bash
79+
80+
# Enable the service.
81+
sudo systemctl enable app
82+
83+
# Stop the service.
84+
sudo systemctl stop app
85+
86+
# (Re)start the service.
87+
sudo systemctl restart app

‎docs/usage/index.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,6 @@ Usage
88
installation
99
development
1010
startup
11+
deployment
12+
user-management
13+
task-queue

‎docs/usage/task-queue.rst‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
===========
2+
Task Queues
3+
===========
4+
5+
This application features a Redis-backed job/task queue thanks to the :doc:`SAQ <saq:index>` library.
6+
You can use it to run one-off tasks, or recurring tasks on a cron-like schedule.
7+
8+
We are utilizing the `litestar-saq <https://github.com/cofin/litestar-saq>`_ plugin for native
9+
integration with Litestar.
10+
11+
Background
12+
----------
13+
14+
Your application's task queue serves a variety of purposes, this section aims to explain when and why you would
15+
want to use a task queue.
16+
17+
Cron jobs are essential for updating the database, performing regular cleanup, sending scheduled emails for various
18+
purposes, and conducting auditing or alerting activities.
19+
20+
Startup jobs focus on initializing essential services, loading initial data, conducting health checks, starting
21+
monitoring services, and allocating necessary resources like database connections.
22+
23+
Conversely, shutdown jobs ensure the graceful release of resources, synchronization of
24+
data with storage, completion of background jobs, and logging of shutdown activities.
25+
26+
Additionally, one-off jobs handle on-demand processing of user-generated content, execution of ad-hoc database tasks,
27+
administrative operations like account resets or data migrations, and event-driven tasks triggered by
28+
specific user actions or system events.
29+
30+
.. tip:: There are several alternatives to ``SAQ``, but we have chosen it for its speed, ease of use, and feature set.
31+
Some other options include:
32+
33+
* Cron jobs via the OS
34+
* `Systemd timers <https://wiki.archlinux.org/title/systemd/Timers>`_
35+
* `RQ <https://github.com/rq/rq>`_
36+
* `ARQ <https://github.com/samuelcolvin/arq>`_
37+
* `SAQ <https://github.com/tobymao/saq>`_
38+
* `Celery <https://docs.celeryq.dev/en/stable/>`_
39+
40+
How
41+
---
42+
43+
Jobs are set up on a per-domain basis. The ``Worker`` class is instantiated when the application starts up.
44+
This calls :func:`litetar_saq.cli.run_worker_process` that has looks at certain directories to find jobs.
45+
46+
Each domain has a directory in it for jobs, in the pattern of ``src/app/domain/$DOMAIN/jobs``. There are separate
47+
modules for each type of job (``scheduled``, ``startup``, ``shutdown``, and ``tasks``).
48+
49+
It is self-explanatory, jobs in the ``startup`` directory are run on startup, etc.
50+
Scheduled jobs are the only slightly unique ones, in that they are a list of :class:`CronJob <saq.job.CronJob>`'s.
51+
That looks something like:
52+
53+
.. code-block:: python
54+
55+
scheduled_tasks: list[CronJob] = [
56+
CronJob(
57+
function=generate_analytics_report,
58+
cron="*/30 * * * *",
59+
heartbeat=30,
60+
unique=True,
61+
timeout=120,
62+
),
63+
CronJob(
64+
function=send_daily_digest,
65+
cron="*/35 * * * *",
66+
heartbeat=30,
67+
unique=True,
68+
timeout=120,
69+
),
70+
]
71+
72+
So you see we have to scheduled jobs every 30 and 35 minutes. When the app starts up, these will run just as a
73+
system cron job would.

‎docs/usage/user-management.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
===============
2+
User Management
3+
===============
4+
5+
This application features a user management system, including teams. We have built
6+
API endpoints and a CLI for managing them as you see fit.
7+
8+
.. todo:: Document the API endpoints and CLI commands for managing users and teams.
9+
Would you like to contribute? See the :doc:`/contribution-guide`.
10+
11+
.. click:: app.cli:user_management_app
12+
:prog: app
13+
:nested: full

0 commit comments

Comments
 (0)