From e4b33692c438c962f84d1761e064dbcd29c97654 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Fri, 24 Nov 2023 15:32:56 -0600 Subject: [PATCH] docs(WIP): add some usage docs --- docs/examples/app.service | 13 +++++ docs/usage/deployment.rst | 87 ++++++++++++++++++++++++++++++++++ docs/usage/index.rst | 3 ++ docs/usage/task-queue.rst | 73 ++++++++++++++++++++++++++++ docs/usage/user-management.rst | 13 +++++ 5 files changed, 189 insertions(+) create mode 100644 docs/examples/app.service create mode 100644 docs/usage/deployment.rst create mode 100644 docs/usage/task-queue.rst create mode 100644 docs/usage/user-management.rst diff --git a/docs/examples/app.service b/docs/examples/app.service new file mode 100644 index 00000000..ea04c323 --- /dev/null +++ b/docs/examples/app.service @@ -0,0 +1,13 @@ +[Unit] +Description=Litestar Fullstack App +After=network.target + +[Service] +User=some-user +Group=some-group +WorkingDirectory=/opt/litestar-app/ +Environment="PATH=/opt/litestar-app/.venv/bin" +ExecStart=/opt/litestar-app/.venv/bin/app run-all --host 127.0.0.1 --port 8000 --http-workers 2 + +[Install] +WantedBy=multi-user.target diff --git a/docs/usage/deployment.rst b/docs/usage/deployment.rst new file mode 100644 index 00000000..8c216aea --- /dev/null +++ b/docs/usage/deployment.rst @@ -0,0 +1,87 @@ +========== +Deployment +========== + +.. note:: This section is a work in progress. + Would you like to contribute? See the :doc:`/contribution-guide`. + +No matter how you decide to deploy your application, this is a Litestar app and the +:doc:`Litestar Deployment Guide ` is a great place to start. + +Docker +------ + +This repository contains example ``Dockerfile``'s and ``docker-compose.yml``'s for deploying +your application for development and production. + +Development +^^^^^^^^^^^ + +Everyone's development environment is different, but we've included a ``docker-compose.infra.yml`` file that +contains the required infrastructure services for running the application. +This includes a PostgreSQL database, a Redis cache, local mail with `MailHog `_, +and object storage with `Minio `_. + +This allows you to just `docker compose up` to start your services, and then run the application +locally with (for example) the Litestar CLI: ``litestar run --debug --reload``. + +We also have a ``Dockerfile`` for development: + +.. dropdown:: Example ``Dockerfile`` for development + + .. literalinclude:: ../../deploy/docker/dev/Dockerfile + :language: dockerfile + :linenos: + +Production +^^^^^^^^^^ + +.. dropdown:: Example ``Dockerfile`` for production + + .. literalinclude:: ../../deploy/docker/run/Dockerfile + :language: dockerfile + :linenos: + +For Docker Compose, run the ``docker-compose.yml`` file, replacing the environment +variables as needed with your own values. + +Railway +------- + +This repository also has a template on `Railway `_. + +.. note:: This link is a referral link that will give us a credit if you decide to utilize the service + and host your application(s) on their platform. This helps us to continue to provide great open source + software for the community by offsetting our hosting costs, and doesn't cost you anything extra. + +Cloud Platforms +--------------- + +.. todo:: Add examples for deploying to cloud platforms. + Would you like to contribute? See the :doc:`/contribution-guide`. + + +Service +------- + +You can also wrap this application into a ``systemd`` service, or use a process manager like +`Supervisor `_. + +.. dropdown:: Example ``systemd`` service + + .. literalinclude:: ../examples/app.service + :language: ini + :linenos: + +.. dropdown:: Manage the ``systemd`` service + + .. code-block:: bash + + # Enable the service. + sudo systemctl enable app + + # Stop the service. + sudo systemctl stop app + + # (Re)start the service. + sudo systemctl restart app diff --git a/docs/usage/index.rst b/docs/usage/index.rst index bd0dc92e..0978ab3e 100644 --- a/docs/usage/index.rst +++ b/docs/usage/index.rst @@ -8,3 +8,6 @@ Usage installation development startup + deployment + user-management + task-queue diff --git a/docs/usage/task-queue.rst b/docs/usage/task-queue.rst new file mode 100644 index 00000000..04d5aa84 --- /dev/null +++ b/docs/usage/task-queue.rst @@ -0,0 +1,73 @@ +=========== +Task Queues +=========== + +This application features a Redis-backed job/task queue thanks to the :doc:`SAQ ` library. +You can use it to run one-off tasks, or recurring tasks on a cron-like schedule. + +We are utilizing the `litestar-saq `_ plugin for native +integration with Litestar. + +Background +---------- + +Your application's task queue serves a variety of purposes, this section aims to explain when and why you would +want to use a task queue. + +Cron jobs are essential for updating the database, performing regular cleanup, sending scheduled emails for various +purposes, and conducting auditing or alerting activities. + +Startup jobs focus on initializing essential services, loading initial data, conducting health checks, starting +monitoring services, and allocating necessary resources like database connections. + +Conversely, shutdown jobs ensure the graceful release of resources, synchronization of +data with storage, completion of background jobs, and logging of shutdown activities. + +Additionally, one-off jobs handle on-demand processing of user-generated content, execution of ad-hoc database tasks, +administrative operations like account resets or data migrations, and event-driven tasks triggered by +specific user actions or system events. + +.. tip:: There are several alternatives to ``SAQ``, but we have chosen it for its speed, ease of use, and feature set. + Some other options include: + + * Cron jobs via the OS + * `Systemd timers `_ + * `RQ `_ + * `ARQ `_ + * `SAQ `_ + * `Celery `_ + +How +--- + +Jobs are set up on a per-domain basis. The ``Worker`` class is instantiated when the application starts up. +This calls :func:`litetar_saq.cli.run_worker_process` that has looks at certain directories to find jobs. + +Each domain has a directory in it for jobs, in the pattern of ``src/app/domain/$DOMAIN/jobs``. There are separate +modules for each type of job (``scheduled``, ``startup``, ``shutdown``, and ``tasks``). + +It is self-explanatory, jobs in the ``startup`` directory are run on startup, etc. +Scheduled jobs are the only slightly unique ones, in that they are a list of :class:`CronJob `'s. +That looks something like: + +.. code-block:: python + + scheduled_tasks: list[CronJob] = [ + CronJob( + function=generate_analytics_report, + cron="*/30 * * * *", + heartbeat=30, + unique=True, + timeout=120, + ), + CronJob( + function=send_daily_digest, + cron="*/35 * * * *", + heartbeat=30, + unique=True, + timeout=120, + ), + ] + +So you see we have to scheduled jobs every 30 and 35 minutes. When the app starts up, these will run just as a +system cron job would. diff --git a/docs/usage/user-management.rst b/docs/usage/user-management.rst new file mode 100644 index 00000000..02336f8a --- /dev/null +++ b/docs/usage/user-management.rst @@ -0,0 +1,13 @@ +=============== +User Management +=============== + +This application features a user management system, including teams. We have built +API endpoints and a CLI for managing them as you see fit. + +.. todo:: Document the API endpoints and CLI commands for managing users and teams. + Would you like to contribute? See the :doc:`/contribution-guide`. + +.. click:: app.cli:user_management_app + :prog: app + :nested: full