diff --git a/README.rst b/README.rst index 6b1d3fd0fbce32a9403b8be932f122514e2ede3c..cb36c8ec372fa04f852812a9741210c6c82125a4 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 f792cc1af3773f537ed57df93e66ebe4b7b2acaa..a6b2cc58edaeaa5e778bcbbb63ba7e1bb4666666 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 9056e07520d54ff3e8746d259bcbabb3d4ced800..9d2e639836c53379a27c12ee402059f55061fb95 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>