diff --git a/source/guide_streamlit.rst b/source/guide_streamlit.rst new file mode 100644 index 00000000..d33ae86a --- /dev/null +++ b/source/guide_streamlit.rst @@ -0,0 +1,167 @@ +.. highlight:: console + +.. author:: Torben + +.. tag:: lang-python +.. tag:: streamlit +.. tag:: web +.. tag:: audience-developers + +###### +Streamlit +###### + +.. tag_list:: + +Streamlit_ is a high-level Python Web framework focussing on data visualization. This guide is based on the :lab:`Django ` guide. + +---- + +.. note:: For this guide, you should be familiar with the basic concepts of + + * :manual:`Python ` and its package manager pip + * :manual:`Supervisord ` to set up your service + +License +======= + +All relevant legal information can be found here + + * https://streamlit.io/terms-of-use + +Prerequisites +============= + +Your URL needs to be setup: + +.. include:: includes/web-domain-list.rst + +.. note:: For this guide we will use *mysiteproject* as the project's name and will install it to ``~/mysiteproject``. + +Installation +============ + +Install the latest Streamlit version. + +.. code-block:: console + + [isabell@stardust ~]$ pip3.11 install --user streamlit + [isabell@stardust ~]$ + +Create Project +============== + +Create a top-level directory for your project somewhere. We use `~/mysiteproject` for this guide. + +.. code-block:: console + + [isabell@stardust ~]$ mkdir ~/mysiteproject + [isabell@stardust ~]$ mkdir ~/mysiteproject/.streamlit + [isabell@stardust ~]$ + +.. warning:: While it does not matter how you name it and where you put it, we suggest that you do **not** put this directory under any path served to the web (e.g. ``~/html``), to avoid exposing your files. + +Configuration +============= + +Edit ``~/mysiteproject/.streamlit/config.toml`` + +.. code-block:: python + + [browser] + gatherUsageStats = false + + [server] + headless = true + port = 8501 + baseUrlPath = "/mysiteproject" + +If running in web server document root "/" you can use the default value: + +.. code-block:: python‚ + baseUrlPath = "" + +`Streamlit configuration documentation `_ for more information. + +Add Web Backend +=============== + +.. code-block:: console + + [isabell@stardust ~]$ uberspace web backend set /mysiteproject --http --port 8501 + Set backend for /mysiteproject to port 8501; please make sure something is listening! + You can always check the status of your backend using "uberspace web backend list". + [isabell@stardust ~]$ + +.. note:: if deployed to web root, use ``/`` instead of ``/mysiteproject`` + +Setup Service +============= + +Create ``~/etc/services.d/mysiteproject.ini`` with the following content (take care to adapt the given directory and project name according to your chosen values): + +.. code-block:: ini + :emphasize-lines: 2,3 + + [program:mysiteproject] + directory=%(ENV_HOME)s/mysiteproject + command=streamlit run app.py + +After creating the configuration, tell :manual:`supervisord ` to refresh its configuration and start the service: + +:: + + [isabell@stardust ~]$ supervisorctl reread + mysiteproject: available + [isabell@stardust ~]$ supervisorctl update + mysiteproject: updated process group + [isabell@stardust ~]$ supervisorctl status + mysiteproject RUNNING pid 11137, uptime 0:04:25 + [isabell@stardust ~]$ + +Your service should be in the state ``RUNNING``. If it still is in ``STARTING`` instead, no worries! You might just have to wait sometime and try the command again (up to 15 seconds). It might already run fine anyway though. Otherwise check the logs in ``~/logs/supervisord.log``. + +Configure Web Backend +--------------------- + +.. include:: includes/web-backend.rst + +Your backend should now point to the service; let's check it: + +.. code-block:: console + :emphasize-lines: 1 + + [isabell@stardust ~]$ uberspace web backend list + /mysiteproject http:8501 => OK, listening: PID 11264, /usr/bin/python3.11 /home/isabell/.local/bin/streamlit run app.py + + [isabell@stardust ~]$ + +Finishing Installation +====================== + +Perform a CURL request to the configured URL, to see if your installation succeeded: + +.. code-block:: console + :emphasize-lines: 1,2 + + [isabell@stardust ~]$ curl -I https://isabell.uber.space/mysiteproject + HTTP/1.1 301 Moved Permanently + Server: nginx + Date: Mon, 09 Dec 2024 20:53:12 GMT + Content-Type: text/html + Content-Length: 162 + Connection: keep-alive + Location: https://isabell.uber.space/mysiteproject + + [isabell@stardust ~]$ + +Documentation +============= + +.. _official docs: https://docs.streamlit.io/ + +---- + +Tested with Streamlit 1.40.2, Python 3.11, Uberspace 7.15 + +.. author_list::