From fed9239a38ee911c9e4d66af489c1d84881805f2 Mon Sep 17 00:00:00 2001
From: Thomas Schneider <thomas@fsmpi.rwth-aachen.de>
Date: Wed, 18 Sep 2024 22:56:11 +0200
Subject: [PATCH] README: Production setup instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
… and some fixes in the examples.
---
README.rst | 50 ++++++++++++++++++++++++-
examples/config/config.py | 2 +-
examples/data/templates/_layout.html.j2 | 2 +-
3 files changed, 50 insertions(+), 4 deletions(-)
diff --git a/README.rst b/README.rst
index 6b1d3fd..cb36c8e 100644
--- a/README.rst
+++ b/README.rst
@@ -61,7 +61,7 @@ configuration:
.. code:: shell-session
% cp -r examples instance
- % $EDITOR instance/config.py
+ % $EDITOR instance/config/config.py
Do replace ``SECRET_KEY`` with a unique, random value; and customise
``SQLALCHEMY_DATABASE_URI`` according to your environment. See `SQLAlchemy
@@ -90,7 +90,50 @@ every time, you can use a ``.env`` file:
Production setup
----------------
-Don’t. This is not ready yet.
+It is recommended to use our pre-built `Python package`_ (wheel) or `container
+image`_. Building the package yourself is left as an exercise to the reader
+(hint: it is a standard Python package, you need Node.js, pass
+``--config-setting without-npm`` to ``pyproject-build`` if you do not want it to
+build the frontend for you, but then you need to run ``npm run build``
+beforehand).
+
+The container image ships with all supported features. For the Python package,
+some features require optional dependencies: ``auth-ldap``, ``auth-saml``,
+``auth-oauth``, ``all-auth``, ``db-postgres``, ``db-mysql``, ``all-db``,
+``all``. For example, to install the package with support for SAML login and
+Postgres database:
+
+.. code:: shell-session
+
+ % pip install "schilder2000[auth-saml,db-postgres]" --index-url https://git.fsmpi.rwth-aachen.de/api/v4/projects/305/packages/pypi/simple
+
+Configuration and runtime data is stored in the instance directory. For
+container installs, mount a volume to ``/usr/local/var/schilder2000-instance/``.
+For package installs, this is ``{{ python prefix }}/var/schilder2000-instance``;
+if in doubt, try to run ``flask -A schilder2000``, the error should tell you
+where it expects the instance directory. Example config and data is located in
+the ``examples`` directory. The templates there get their footer text and logo
+from the application config and should also be useful as an example to write
+your own templates.
+
+The main application config is located in ``config/config.py``. Customise it as
+needed, the example config should provide enough comments.
+
+An example config for Gunicorn_ is provided in ``gunicorn.conf.py``. If you
+want to use another WSGI server, configure it to use
+``schilder2000:create_app()`` as application object. Note that this is a
+factory function that returns the application callable, you have to call it!
+
+Unless you use SQLite, create the database in your database server. In all
+cases, run the migrations:
+
+.. code:: shell-session
+
+ % flask -A schilder2000 alembic upgrade head
+
+If you want to use your webserver to directly serve static files, route
+``/static`` to ``{{ python packages directory }}/schilder2000/static`` and
+``/instance/static`` to ``{{ instance path }}/data/static``.
.. _schildergenerator: https://git.fsmpi.rwth-aachen.de/schilder/schildergenerator
@@ -99,3 +142,6 @@ Don’t. This is not ready yet.
.. _PDM-Backend: https://backend.pdm-project.org/
.. _pip: https://pip.pypa.io/
.. _`SQLAlchemy documentation`: https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls
+.. _`Python package`: https://git.fsmpi.rwth-aachen.de/schilder/schilder2000/-/packages
+.. _`container image`: https://git.fsmpi.rwth-aachen.de/schilder/schilder2000/container_registry/33
+.. _Gunicorn: https://gunicorn.org/
diff --git a/examples/config/config.py b/examples/config/config.py
index f792cc1..a6b2cc5 100644
--- a/examples/config/config.py
+++ b/examples/config/config.py
@@ -7,7 +7,7 @@ from pathlib import Path
SQLALCHEMY_DATABASE_URI = "postgresql+psycopg:///schilder2000"
-# SQLALCHEMY_DATABASE_URI = "sqlite:///schilder2000.db" # Relative to instance directory
+# SQLALCHEMY_DATABASE_URI = "sqlite:///data/schilder2000.db" # Relative to instance directory
# SQLALCHEMY_DATABASE_URI = "mysql:///schilder2000"
# To generate a secret key:
diff --git a/examples/data/templates/_layout.html.j2 b/examples/data/templates/_layout.html.j2
index 9056e07..9d2e639 100644
--- a/examples/data/templates/_layout.html.j2
+++ b/examples/data/templates/_layout.html.j2
@@ -20,7 +20,7 @@
</div>
<div id="logo">
- <img src="{{ url_for('instance.static', filename='geier.png') }}" />
+ <img src="{{ url_for('instance.static', filename=config['SCHILD_LOGO']) }}" />
</div>
</footer>
</body>
--
GitLab