From 80f54135939fae9a8700ee101edc3d41c15a50fd Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 21 Mar 2024 15:55:45 +0100 Subject: [PATCH 01/30] Rename howitz venv Otherwise pip might complain about several directories having the same name: howitz venv dir and howitz module dir --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 44223955..a42ad0dc 100644 --- a/README.rst +++ b/README.rst @@ -10,8 +10,8 @@ Install safely Make and activate a virtualenv, install dependencies in that virtualenv:: - $ python3 -m venv howitz - $ source howitz/bin/activate + $ python3 -m venv howitzvenv + $ source howitzvenv/bin/activate $ pip install -e . Howitz is deeply dependent on the library ``zinolib``. When developing Howitz, From 1044407a5bdb79b88bc57aaee098e78cf9ae3cd9 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 21 Mar 2024 16:26:35 +0100 Subject: [PATCH 02/30] Format zinolib setup for dev as a tip Makes it easier to see this info and use it. Also marks this info clearly as an optional one --- README.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index a42ad0dc..94572864 100644 --- a/README.rst +++ b/README.rst @@ -14,10 +14,14 @@ Make and activate a virtualenv, install dependencies in that virtualenv:: $ source howitzvenv/bin/activate $ pip install -e . -Howitz is deeply dependent on the library ``zinolib``. When developing Howitz, -it might be prudent to add zinolib manually to the virtualenv by downloading -the source, entering the directory and running ``pip install -e .``. This will -make it very easy to switch between versions and branches of zinolib. + +Tip: + + Howitz is deeply dependent on the library ``zinolib``. When developing Howitz, + it might be prudent to add zinolib manually to the virtualenv by downloading + the source, entering the directory and running ``pip install -e .``. This will + make it very easy to switch between versions and branches of zinolib. + Run in development-mode ----------------------- From 64f773f159f601ae4ba144edd8ef9a4791dd78cd Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 21 Mar 2024 16:25:07 +0100 Subject: [PATCH 03/30] Highlight info about existence of example config file User testing showed that this info wasn't apparent enough for a new user --- README.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.rst b/README.rst index 94572864..5e5264ab 100644 --- a/README.rst +++ b/README.rst @@ -28,6 +28,11 @@ Run in development-mode You need to have either a minimal configuration file or set two environment varibles, see `Configuration`_. +Tip for quickly setting up an extensive config file for dev: + + Check out the `Example config-file for development`_ section. + + Either of:: $ python3 -m howitz From 81b3489c4c260a32cf15d73b7b821d0a099821fb Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 21 Mar 2024 16:38:11 +0100 Subject: [PATCH 04/30] Make run in dev-mode section more Howitz first-timer friendly --- README.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 5e5264ab..b96f3855 100644 --- a/README.rst +++ b/README.rst @@ -26,14 +26,14 @@ Tip: Run in development-mode ----------------------- -You need to have either a minimal configuration file or set two environment varibles, see `Configuration`_. - +You need to have either a minimal configuration file or set two environment variables, see `Configuration`_. Tip for quickly setting up an extensive config file for dev: Check out the `Example config-file for development`_ section. -Either of:: +After both installation (see `Install safely`_) and `Configuration`_ are done, you can run Howitz by running +either:: $ python3 -m howitz @@ -41,8 +41,14 @@ or:: $ flask --app howitz run -should get you a server running on http://127.0.0.1:5000/ The database is by -default put in the current directory. +This will get you a web interface running on http://127.0.0.1:5000/. +The database (see `User management`_) is by default put in the current directory. + +**NB!**: + + If you get an error when attempting to log in for the first time, make sure you have created a user in the Howitz + database, see `Managing the Howitz user database`_. + Run in production ----------------- From bba85db5cfa89b497b15d6ef426f3b4854b94c95 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 21 Mar 2024 16:43:12 +0100 Subject: [PATCH 05/30] Add info about configuration to the run in prod section Don't assume user has read the run in dev section before reading this section --- README.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.rst b/README.rst index b96f3855..2349e67e 100644 --- a/README.rst +++ b/README.rst @@ -53,6 +53,14 @@ The database (see `User management`_) is by default put in the current directory Run in production ----------------- +You need to have either a minimal configuration file or set two environment variables, see `Configuration`_. + +Tip for quickly setting up an extensive config file: + + Check out the `Example config-file for development`_ section. Make sure config file is appropriate for production, + see `Config file for production`_. + + Always use an installed howitz. * gunicorn: ``gunicorn 'howitz:create_app()'`` From ac9f5f14c18c842c66e03471bbe27e9538cde9e4 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 21 Mar 2024 16:46:48 +0100 Subject: [PATCH 06/30] Remove confusion about what is tld There was confusion for a first-timer about what this value should be because of "tld" --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 2349e67e..416dd33a 100644 --- a/README.rst +++ b/README.rst @@ -159,11 +159,11 @@ Via configuration file:: SECRET_KEY = "long string!" [zino.connections.default] - server = "some.server.tld" + server = "zino.server.domain" Directly via environment variables:: - HOWITZ_SECRET_KEY="long string!" HOWITZ_ZINO1_SERVER="some.server.tld" + HOWITZ_SECRET_KEY="long string!" HOWITZ_ZINO1_SERVER="zino.server.domain" All config options can be overruled by environment variables. Prefix with "HOWITZ\_" for Flask-specific options and "HOWITZ_ZINO1\_" for Zino-specific From a3566da9107810a9339e08382f7c9803a734b375 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 21 Mar 2024 16:47:15 +0100 Subject: [PATCH 07/30] Polish in configuration section --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 416dd33a..659455fe 100644 --- a/README.rst +++ b/README.rst @@ -151,9 +151,9 @@ listen-address (127.0.0.1), port (5000) and storage location (./howitz.sqlite3). However, at minimum you also need to pass in a SECRET_KEY for Flask and a zino server to fetch events from. -These can be passed via a configuration file, ".howitz.toml" (in the current directory or user home directory) or via environment variables. +These can be passed via a configuration file, ".howitz.toml" (stored in the current directory or user home directory) or via environment variables. -Via configuration file:: +Via ".howitz.toml" configuration file:: [flask] SECRET_KEY = "long string!" From 75af5a2ca03977b8cd02993964debeaf8283f2e9 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 21 Mar 2024 17:32:10 +0100 Subject: [PATCH 08/30] Add section explaining howitz db values --- README.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.rst b/README.rst index 659455fe..622ab2fd 100644 --- a/README.rst +++ b/README.rst @@ -127,6 +127,23 @@ Get help for each sub-command with appending "--help", for instance:: -t, --token TEXT --help Show this message and exit. +About username, password and token values +----------------------------------------- + +When running `commands `_ to Howitz user database, you may need to provide all or some of the options. + +``USERNAME`` + an **existing** username on your Zino server. **You will need to provide it when logging in to Howitz on web.** + +``TOKEN`` + token assigned to a given username on on your Zino server. In the original Zino protocol this value is referred to as a *Secret*. + Store it in the Howitz database once and forget about it when logging in to Howitz on web. + +``PASSWORD`` + a password of your choice. This one is purely Howitz-specific. **You will need to provide it when logging in to Howitz on web.** + + + All available commands ---------------------- From 6bcf61513d4147671187edd3dec537bdd3fa75c3 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Fri, 22 Mar 2024 08:51:49 +0100 Subject: [PATCH 09/30] Set poll interval to 60s in example dev config file --- dev-howitz.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-howitz.toml b/dev-howitz.toml index d0197984..c38e3404 100644 --- a/dev-howitz.toml +++ b/dev-howitz.toml @@ -5,7 +5,7 @@ DEBUG = true [howitz] storage = "./howitz.sqlite3" devmode = true -poll_interval = 30 +poll_interval = 60 timezone='LOCAL' [zino.connections.default] From 86af3b10c183d3df9e78baf921b80e68fe8d1f07 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Fri, 22 Mar 2024 08:56:10 +0100 Subject: [PATCH 10/30] Comment out alternative zino profiles section in example config It shows how to configure alternative connections, yet doesnt require any action for new users when they copy values from the example config file to the actual config file --- dev-howitz.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dev-howitz.toml b/dev-howitz.toml index c38e3404..57e2daac 100644 --- a/dev-howitz.toml +++ b/dev-howitz.toml @@ -11,8 +11,8 @@ timezone='LOCAL' [zino.connections.default] server = -[zino.connections.other] -server = +#[zino.connections.other] +#server = [logging] version = 1 From 53c29c7a9ef48a3a22c69204567c8e66e9582f23 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Fri, 22 Mar 2024 11:04:59 +0100 Subject: [PATCH 11/30] Add step-by-step section about running Howitz --- README.rst | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/README.rst b/README.rst index 622ab2fd..c194e86a 100644 --- a/README.rst +++ b/README.rst @@ -2,6 +2,57 @@ Howitz - Zino web client with HTMx and Flask ============================================ + +Running Howitz step-by-step overview +==================================== + +1. Preparation step: + 1. Make sure you have ``python3``, ``pip`` and ``git`` installed. + 2. Download `Howitz from the GitHub repo `_. + +2. Installation step: + 1. Activate `venv`, from the project root folder run:: + + $ python3 -m venv howitzvenv + $ source howitzvenv/bin/activate + + 2. Install dependencies, from the project root folder run:: + + $ pip install -e . + + Read more about installation in the `Install safely`_ section. + +3. Configuration step: + The easiest way to configure Howitz is via ``toml`` file. + + 1. Create empty ``.howitz.toml`` file in the project root folder. + 2. Copy values from the example config file ``dev-howitz.toml`` to the ``.howitz.toml``. + 3. Open ``.howitz.toml`` file and fill out 2 of the required config values: ``SECRET_KEY`` and ``server``. Those values are left empty in the example config file. + 4. Play around with the config values in `.howitz.toml`` file if desired. + + Read more about other configuration methods, and different configurations options and variables in the `Configuration`_ section. + +4. User management step: + 1. Check if you have an existing user in the Howitz database, from the project root folder run:: + + $ flask --app howitz user list + + 2. Create a new user if you do not have one already, from the project root folder run:: + + $ flask --app howitz user create USERNAME PASSWORD TOKEN + + Read more about user management and other commands in the `User management`_ section. + +5. Run Howitz: + 1. Start Howitz as a flask app, from the project root folder run:: + + $ python3 -m howitz + + 2. Open Howitz in browser. By default in dev, Howitz will be accessible on http://127.0.0.1:5000. + + Read more about running Howitz in the `Play around`_ section. + + Play around =========== From c1fd048e1b1e5662930dc128c9bb88d5b2c7ae2e Mon Sep 17 00:00:00 2001 From: Johanna England Date: Thu, 4 Apr 2024 15:38:02 +0200 Subject: [PATCH 12/30] Change label of url --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index c194e86a..9a43da31 100644 --- a/README.rst +++ b/README.rst @@ -8,7 +8,7 @@ Running Howitz step-by-step overview 1. Preparation step: 1. Make sure you have ``python3``, ``pip`` and ``git`` installed. - 2. Download `Howitz from the GitHub repo `_. + 2. Download Howitz from the `GitHub repo `_. 2. Installation step: 1. Activate `venv`, from the project root folder run:: From 0de11d2dad70f17480489344c12a147214243c49 Mon Sep 17 00:00:00 2001 From: Johanna England Date: Thu, 4 Apr 2024 15:41:48 +0200 Subject: [PATCH 13/30] Adding articles, changing prepositions --- README.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/README.rst b/README.rst index 9a43da31..e88a88a5 100644 --- a/README.rst +++ b/README.rst @@ -23,10 +23,10 @@ Running Howitz step-by-step overview Read more about installation in the `Install safely`_ section. 3. Configuration step: - The easiest way to configure Howitz is via ``toml`` file. + The easiest way to configure Howitz is via a ``toml`` file. - 1. Create empty ``.howitz.toml`` file in the project root folder. - 2. Copy values from the example config file ``dev-howitz.toml`` to the ``.howitz.toml``. + 1. Create an empty ``.howitz.toml`` file in the project root folder. + 2. Copy the values from the example config file ``dev-howitz.toml`` to ``.howitz.toml``. 3. Open ``.howitz.toml`` file and fill out 2 of the required config values: ``SECRET_KEY`` and ``server``. Those values are left empty in the example config file. 4. Play around with the config values in `.howitz.toml`` file if desired. @@ -48,7 +48,7 @@ Running Howitz step-by-step overview $ python3 -m howitz - 2. Open Howitz in browser. By default in dev, Howitz will be accessible on http://127.0.0.1:5000. + 2. Open Howitz in the browser. By default in dev, Howitz will be accessible at http://127.0.0.1:5000. Read more about running Howitz in the `Play around`_ section. @@ -92,7 +92,7 @@ or:: $ flask --app howitz run -This will get you a web interface running on http://127.0.0.1:5000/. +This will get you a web interface running at http://127.0.0.1:5000/. The database (see `User management`_) is by default put in the current directory. **NB!**: @@ -108,8 +108,8 @@ You need to have either a minimal configuration file or set two environment vari Tip for quickly setting up an extensive config file: - Check out the `Example config-file for development`_ section. Make sure config file is appropriate for production, - see `Config file for production`_. + Check out the `Example config-file for development`_ section. Make sure the config file is appropriate for + production, see `Config file for production`_. Always use an installed howitz. @@ -125,7 +125,7 @@ User management =============== Due to how Zino protocol 1 does logins, the password (here called token) needs -to be stored in plain text in every client. For security-reasons it is not +to be stored in plain text in every client. For security reasons it is not desirable to ever store this token in a cookie or otherwise in a browser, so instead the token is stored where the browser cannot get to it, in a user database local to the frontend server. @@ -133,7 +133,7 @@ database local to the frontend server. When logging in to Howitz a user uses a normal password (not the token) which is used to safely fetch the token for connecting to the zino protocol 1 server. This password can be treated like any other password and be put in a vault or -a password-manager. +a password manager. The mapping from websafe password to legacy token is done via a user database. The Zino backend server admin creates a token and username. The frontend server @@ -187,7 +187,7 @@ When running `commands `_ to Howitz user database, you m an **existing** username on your Zino server. **You will need to provide it when logging in to Howitz on web.** ``TOKEN`` - token assigned to a given username on on your Zino server. In the original Zino protocol this value is referred to as a *Secret*. + token assigned to a given username on your Zino server. In the original Zino protocol this value is referred to as a *Secret*. Store it in the Howitz database once and forget about it when logging in to Howitz on web. ``PASSWORD`` @@ -221,7 +221,7 @@ for Flask and a zino server to fetch events from. These can be passed via a configuration file, ".howitz.toml" (stored in the current directory or user home directory) or via environment variables. -Via ".howitz.toml" configuration file:: +Via a ".howitz.toml" configuration file:: [flask] SECRET_KEY = "long string!" @@ -233,19 +233,19 @@ Directly via environment variables:: HOWITZ_SECRET_KEY="long string!" HOWITZ_ZINO1_SERVER="zino.server.domain" -All config options can be overruled by environment variables. Prefix with +All config options can be overruled by environment variables. Prefix them with "HOWITZ\_" for Flask-specific options and "HOWITZ_ZINO1\_" for Zino-specific options. It is also possible to override logging by setting "HOWITZ_LOGGING" to a string of a python dict but we do not recommend it, use a config file instead. -Poll interval for events table can be changed by adding for example ``poll_interval = 30`` to +The poll interval for the events table can be changed by adding for example ``poll_interval = 30`` to the ``[howitz]``-section or setting the environment variable ``HOWITZ_POLL_INTERVAL`` to a new value. Poll interval values represented seconds and must be integers. The default value is ``60`` seconds. Debugging can be turned on either by adding ``DEBUG = true`` to the ``[flask]``-section or setting the environment variable ``HOWITZ_DEBUG`` to ``1``. -Default timezone for timestamps is ``UTC``. Timezone information can be changed by adding ``timezone = "LOCAL"`` to +The default timezone for timestamps is ``UTC``. Timezone information can be changed by adding ``timezone = "LOCAL"`` to the ``[howitz]``-section or setting the environment variable ``HOWITZ_TIMEZONE`` to ``LOCAL``. Timezone values other than ``LOCAL`` and ``UTC`` provided in config will be ignored and fall back to ``UTC``. From c492252eb653d8b2b4c25eaaf8b9a7731e240e8d Mon Sep 17 00:00:00 2001 From: Johanna England Date: Thu, 4 Apr 2024 15:44:45 +0200 Subject: [PATCH 14/30] Change phrasing --- README.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.rst b/README.rst index e88a88a5..8df99a09 100644 --- a/README.rst +++ b/README.rst @@ -11,7 +11,7 @@ Running Howitz step-by-step overview 2. Download Howitz from the `GitHub repo `_. 2. Installation step: - 1. Activate `venv`, from the project root folder run:: + 1. Create and activate `venv`, from the project root folder run:: $ python3 -m venv howitzvenv $ source howitzvenv/bin/activate @@ -27,10 +27,10 @@ Running Howitz step-by-step overview 1. Create an empty ``.howitz.toml`` file in the project root folder. 2. Copy the values from the example config file ``dev-howitz.toml`` to ``.howitz.toml``. - 3. Open ``.howitz.toml`` file and fill out 2 of the required config values: ``SECRET_KEY`` and ``server``. Those values are left empty in the example config file. - 4. Play around with the config values in `.howitz.toml`` file if desired. + 3. Open ``.howitz.toml`` and fill out at least the config values: ``SECRET_KEY`` and ``server``. Those values are left empty in the example config file. + 4. Play around with the config values in ``.howitz.toml``, if desired. - Read more about other configuration methods, and different configurations options and variables in the `Configuration`_ section. + Read more about other configuration methods, different configurations options and variables in the `Configuration`_ section. 4. User management step: 1. Check if you have an existing user in the Howitz database, from the project root folder run:: @@ -59,7 +59,7 @@ Play around Install safely -------------- -Make and activate a virtualenv, install dependencies in that virtualenv:: +Create and activate a virtualenv, install dependencies in that virtualenv:: $ python3 -m venv howitzvenv $ source howitzvenv/bin/activate @@ -217,7 +217,7 @@ Configuration Howitz *can* run without a configuration file. Default values will be used for listen-address (127.0.0.1), port (5000) and storage location (./howitz.sqlite3). However, at minimum you also need to pass in a SECRET_KEY -for Flask and a zino server to fetch events from. +for Flask and a zino server address to fetch events from. These can be passed via a configuration file, ".howitz.toml" (stored in the current directory or user home directory) or via environment variables. @@ -240,7 +240,7 @@ a string of a python dict but we do not recommend it, use a config file instead. The poll interval for the events table can be changed by adding for example ``poll_interval = 30`` to the ``[howitz]``-section or setting the environment variable ``HOWITZ_POLL_INTERVAL`` to a new value. -Poll interval values represented seconds and must be integers. The default value is ``60`` seconds. +Poll interval values are in seconds and must be integers. The default value is ``60`` seconds. Debugging can be turned on either by adding ``DEBUG = true`` to the ``[flask]``-section or setting the environment variable ``HOWITZ_DEBUG`` to ``1``. @@ -256,11 +256,11 @@ Example config-file for development For development, copy the contents of the included file ``dev-howitz.toml`` to ``.howitz.toml`` in the same directory. 1. Set ``[flask] -> SECRET_KEY`` to some long string. -2. Set ``[zino.connections.default] -> server`` to a Zino 1 server. -3. Optionally set ``[zino.connections.other] -> server`` to a fallback Zino +2. Set ``[zino.connections.default] -> server`` to the address of a Zino 1 server. +3. Optionally set ``[zino.connections.other] -> server`` to the address of a fallback Zino 1 server. If the default server stops working you can swap "other" with "default" in the config-file and keep on working. If you don't set it to - anything, comment it out/remove it. + anything, keep it commented out or remove it. There's a handler "debug" that will copy everything DEBUG or higher to a file ``debug.log``, you might want to use this handler for your code. From ee5af75462e38d12c654ef3e042d8eaa83fd1a66 Mon Sep 17 00:00:00 2001 From: Johanna England Date: Thu, 4 Apr 2024 15:45:58 +0200 Subject: [PATCH 15/30] Change capitalization --- README.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 8df99a09..e89308ff 100644 --- a/README.rst +++ b/README.rst @@ -112,7 +112,7 @@ Tip for quickly setting up an extensive config file: production, see `Config file for production`_. -Always use an installed howitz. +Always use an installed Howitz. * gunicorn: ``gunicorn 'howitz:create_app()'`` * waitress: ``waitress-serve --call howitz:create_app`` @@ -131,7 +131,7 @@ instead the token is stored where the browser cannot get to it, in a user database local to the frontend server. When logging in to Howitz a user uses a normal password (not the token) which -is used to safely fetch the token for connecting to the zino protocol 1 server. +is used to safely fetch the token for connecting to the Zino protocol 1 server. This password can be treated like any other password and be put in a vault or a password manager. @@ -208,7 +208,7 @@ All available commands shows all known usernames ``update`` - is used to change the web password or zino token for an existing user + is used to change the web password or Zino token for an existing user Configuration @@ -217,7 +217,7 @@ Configuration Howitz *can* run without a configuration file. Default values will be used for listen-address (127.0.0.1), port (5000) and storage location (./howitz.sqlite3). However, at minimum you also need to pass in a SECRET_KEY -for Flask and a zino server address to fetch events from. +for Flask and a Zino server address to fetch events from. These can be passed via a configuration file, ".howitz.toml" (stored in the current directory or user home directory) or via environment variables. @@ -236,7 +236,7 @@ Directly via environment variables:: All config options can be overruled by environment variables. Prefix them with "HOWITZ\_" for Flask-specific options and "HOWITZ_ZINO1\_" for Zino-specific options. It is also possible to override logging by setting "HOWITZ_LOGGING" to -a string of a python dict but we do not recommend it, use a config file instead. +a string of a Python dict but we do not recommend it, use a config file instead. The poll interval for the events table can be changed by adding for example ``poll_interval = 30`` to the ``[howitz]``-section or setting the environment variable ``HOWITZ_POLL_INTERVAL`` to a new value. From 2c7366b4c390a65731730ea1844b44ad5df0062e Mon Sep 17 00:00:00 2001 From: Johanna England Date: Thu, 4 Apr 2024 15:46:38 +0200 Subject: [PATCH 16/30] Change formatting --- README.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index e89308ff..9cb91218 100644 --- a/README.rst +++ b/README.rst @@ -147,7 +147,7 @@ fashion. Managing the Howitz user database --------------------------------- -Users are by default stored in the file "./howitz.sqlite3", this can be changed +Users are by default stored in the file ``./howitz.sqlite``, this can be changed in the configuration file. While it is possible to use an sqlite3-client to alter the database, setting @@ -219,9 +219,10 @@ listen-address (127.0.0.1), port (5000) and storage location (./howitz.sqlite3). However, at minimum you also need to pass in a SECRET_KEY for Flask and a Zino server address to fetch events from. -These can be passed via a configuration file, ".howitz.toml" (stored in the current directory or user home directory) or via environment variables. +These can be passed via a configuration file, ``.howitz.toml`` (stored in the current directory or user home +directory) or via environment variables. -Via a ".howitz.toml" configuration file:: +Via a ``.howitz.toml`` configuration file:: [flask] SECRET_KEY = "long string!" @@ -262,7 +263,7 @@ For development, copy the contents of the included file ``dev-howitz.toml`` to ` "default" in the config-file and keep on working. If you don't set it to anything, keep it commented out or remove it. -There's a handler "debug" that will copy everything DEBUG or higher to a file +There's a handler ``debug`` that will copy everything DEBUG or higher to a file ``debug.log``, you might want to use this handler for your code. The handler ``error`` will likewise put everything WARNING or higher in the From 1b61ab81ff424a24b34c1f407f31f31475133f06 Mon Sep 17 00:00:00 2001 From: Johanna England Date: Fri, 5 Apr 2024 11:37:22 +0200 Subject: [PATCH 17/30] fixup! Change label of url --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 9cb91218..e9dec935 100644 --- a/README.rst +++ b/README.rst @@ -8,7 +8,7 @@ Running Howitz step-by-step overview 1. Preparation step: 1. Make sure you have ``python3``, ``pip`` and ``git`` installed. - 2. Download Howitz from the `GitHub repo `_. + 2. Download `Howitz from the GitHub repo `_. 2. Installation step: 1. Create and activate `venv`, from the project root folder run:: From 15185b2beab09ebbc5bbc05fc2a3054b8d8a1e47 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Fri, 5 Apr 2024 17:28:53 +0200 Subject: [PATCH 18/30] Set wsgi log level to warning in config example --- dev-howitz.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/dev-howitz.toml b/dev-howitz.toml index 57e2daac..db732f75 100644 --- a/dev-howitz.toml +++ b/dev-howitz.toml @@ -30,6 +30,7 @@ format = "%(asctime)s %(levelname)s %(name)s %(pathname)s:%(lineno)s:: %(message class = "logging.NullHandler" [logging.handlers.wsgi] +level = "WARNING" class = "logging.StreamHandler" stream = "ext://flask.logging.wsgi_errors_stream" formatter = "default" From 090a1ea60f9ec5e7724d4bb2f750aa8eaf33a409 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Fri, 5 Apr 2024 17:42:58 +0200 Subject: [PATCH 19/30] Add comment about alternative zino server configurations in example conf --- dev-howitz.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/dev-howitz.toml b/dev-howitz.toml index db732f75..fc070fca 100644 --- a/dev-howitz.toml +++ b/dev-howitz.toml @@ -11,6 +11,7 @@ timezone='LOCAL' [zino.connections.default] server = +## Comment out and fill out in order to configure another Zino server profile #[zino.connections.other] #server = From 2bf3e8440f40afb9b12d308366da1926b74b6e3f Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Fri, 5 Apr 2024 17:46:56 +0200 Subject: [PATCH 20/30] Comment out noisy logging setup in example config file --- dev-howitz.toml | 71 +++++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 35 deletions(-) diff --git a/dev-howitz.toml b/dev-howitz.toml index fc070fca..30f2ddd3 100644 --- a/dev-howitz.toml +++ b/dev-howitz.toml @@ -19,38 +19,39 @@ server = version = 1 [logging.root] -level = "DEBUG" - -[logging.formatters.default] -format = "%(levelname)s %(name)s in %(funcName)s: %(message)s" - -[logging.formatters.detail] -format = "%(asctime)s %(levelname)s %(name)s %(pathname)s:%(lineno)s:: %(message)s" - -[logging.handlers.null] -class = "logging.NullHandler" - -[logging.handlers.wsgi] -level = "WARNING" -class = "logging.StreamHandler" -stream = "ext://flask.logging.wsgi_errors_stream" -formatter = "default" - -[logging.handlers.error] -level = "WARNING" -class = "logging.FileHandler" -filename = "errors.log" -formatter = "detail" - -[logging.handlers.debug] -level = "DEBUG" -class = "logging.handlers.TimedRotatingFileHandler" -filename = "debug.log" -when = 'D' -formatter = "detail" - -[logging.loggers.zinolib] -handlers = ["debug", "wsgi"] - -[logging.loggers.howitz] -handlers = ["debug", "wsgi"] +level = "ERROR" + +## Comment out and tweak in order to configure logging level for dev or prod +#[logging.formatters.default] +#format = "%(levelname)s %(name)s in %(funcName)s: %(message)s" +# +#[logging.formatters.detail] +#format = "%(asctime)s %(levelname)s %(name)s %(pathname)s:%(lineno)s:: %(message)s" +# +#[logging.handlers.null] +#class = "logging.NullHandler" +# +#[logging.handlers.wsgi] +#level = "WARNING" +#class = "logging.StreamHandler" +#stream = "ext://flask.logging.wsgi_errors_stream" +#formatter = "default" +# +#[logging.handlers.error] +#level = "WARNING" +#class = "logging.FileHandler" +#filename = "errors.log" +#formatter = "detail" +# +#[logging.handlers.debug] +#level = "DEBUG" +#class = "logging.handlers.TimedRotatingFileHandler" +#filename = "debug.log" +#when = 'D' +#formatter = "detail" +# +#[logging.loggers.zinolib] +#handlers = ["debug", "wsgi"] +# +#[logging.loggers.howitz] +#handlers = ["debug", "wsgi"] From b3f8ad9a3329b09aff1784ceb2fe0f5121079461 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 30 May 2024 13:25:40 +0200 Subject: [PATCH 21/30] Polish wording --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index e9dec935..41ac354c 100644 --- a/README.rst +++ b/README.rst @@ -263,7 +263,7 @@ For development, copy the contents of the included file ``dev-howitz.toml`` to ` "default" in the config-file and keep on working. If you don't set it to anything, keep it commented out or remove it. -There's a handler ``debug`` that will copy everything DEBUG or higher to a file +As for logging, there is a handler ``debug`` that will copy everything DEBUG or higher to a file ``debug.log``, you might want to use this handler for your code. The handler ``error`` will likewise put everything WARNING or higher in the From 7692e0aab786e9b910db4771527d492ae08f782d Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Fri, 31 May 2024 16:46:18 +0200 Subject: [PATCH 22/30] Add minimal and dev toml-config example files --- README.rst | 7 +++-- dev-howitz.toml | 57 ----------------------------------------- howitz.dev.toml.example | 56 ++++++++++++++++++++++++++++++++++++++++ howitz.min.toml.example | 18 +++++++++++++ 4 files changed, 79 insertions(+), 59 deletions(-) delete mode 100644 dev-howitz.toml create mode 100644 howitz.dev.toml.example create mode 100644 howitz.min.toml.example diff --git a/README.rst b/README.rst index 41ac354c..6309ff50 100644 --- a/README.rst +++ b/README.rst @@ -26,7 +26,10 @@ Running Howitz step-by-step overview The easiest way to configure Howitz is via a ``toml`` file. 1. Create an empty ``.howitz.toml`` file in the project root folder. - 2. Copy the values from the example config file ``dev-howitz.toml`` to ``.howitz.toml``. + 2. Copy the values from the preferred example config file ``howitz.*.toml.example`` to ``.howitz.toml``. Here using the ``howitz.min.toml.example``:: + + $ cp howitz.min.toml.example .howitz.toml + 3. Open ``.howitz.toml`` and fill out at least the config values: ``SECRET_KEY`` and ``server``. Those values are left empty in the example config file. 4. Play around with the config values in ``.howitz.toml``, if desired. @@ -254,7 +257,7 @@ than ``LOCAL`` and ``UTC`` provided in config will be ignored and fall back to ` Example config-file for development ----------------------------------- -For development, copy the contents of the included file ``dev-howitz.toml`` to ``.howitz.toml`` in the same directory. +For development, copy the contents of the included file ``howitz.dev.toml.example`` to ``.howitz.toml`` in the same directory. 1. Set ``[flask] -> SECRET_KEY`` to some long string. 2. Set ``[zino.connections.default] -> server`` to the address of a Zino 1 server. diff --git a/dev-howitz.toml b/dev-howitz.toml deleted file mode 100644 index 30f2ddd3..00000000 --- a/dev-howitz.toml +++ /dev/null @@ -1,57 +0,0 @@ -[flask] -SECRET_KEY = -DEBUG = true - -[howitz] -storage = "./howitz.sqlite3" -devmode = true -poll_interval = 60 -timezone='LOCAL' - -[zino.connections.default] -server = - -## Comment out and fill out in order to configure another Zino server profile -#[zino.connections.other] -#server = - -[logging] -version = 1 - -[logging.root] -level = "ERROR" - -## Comment out and tweak in order to configure logging level for dev or prod -#[logging.formatters.default] -#format = "%(levelname)s %(name)s in %(funcName)s: %(message)s" -# -#[logging.formatters.detail] -#format = "%(asctime)s %(levelname)s %(name)s %(pathname)s:%(lineno)s:: %(message)s" -# -#[logging.handlers.null] -#class = "logging.NullHandler" -# -#[logging.handlers.wsgi] -#level = "WARNING" -#class = "logging.StreamHandler" -#stream = "ext://flask.logging.wsgi_errors_stream" -#formatter = "default" -# -#[logging.handlers.error] -#level = "WARNING" -#class = "logging.FileHandler" -#filename = "errors.log" -#formatter = "detail" -# -#[logging.handlers.debug] -#level = "DEBUG" -#class = "logging.handlers.TimedRotatingFileHandler" -#filename = "debug.log" -#when = 'D' -#formatter = "detail" -# -#[logging.loggers.zinolib] -#handlers = ["debug", "wsgi"] -# -#[logging.loggers.howitz] -#handlers = ["debug", "wsgi"] diff --git a/howitz.dev.toml.example b/howitz.dev.toml.example new file mode 100644 index 00000000..4ed30377 --- /dev/null +++ b/howitz.dev.toml.example @@ -0,0 +1,56 @@ +[flask] +SECRET_KEY = +DEBUG = true + +[howitz] +storage = "./howitz.sqlite3" +devmode = true +poll_interval = 60 +timezone='LOCAL' + +[zino.connections.default] +server = + +## Comment out and fill out in order to configure another Zino server profile +#[zino.connections.other] +#server = + +[logging] +version = 1 + +[logging.root] +level = "ERROR" + +# Tweak in order to configure desired logging level +[logging.formatters.default] +format = "%(levelname)s %(name)s in %(funcName)s: %(message)s" + +[logging.formatters.detail] +format = "%(asctime)s %(levelname)s %(name)s %(pathname)s:%(lineno)s:: %(message)s" + +[logging.handlers.null] +class = "logging.NullHandler" + +[logging.handlers.wsgi] +class = "logging.StreamHandler" +stream = "ext://flask.logging.wsgi_errors_stream" +formatter = "default" + +[logging.handlers.error] +level = "WARNING" +class = "logging.FileHandler" +filename = "errors.log" +formatter = "detail" + +[logging.handlers.debug] +level = "DEBUG" +class = "logging.handlers.TimedRotatingFileHandler" +filename = "debug.log" +when = 'D' +formatter = "detail" + +[logging.loggers.zinolib] +handlers = ["debug", "wsgi"] + +[logging.loggers.howitz] +handlers = ["debug", "wsgi"] diff --git a/howitz.min.toml.example b/howitz.min.toml.example new file mode 100644 index 00000000..96daf84f --- /dev/null +++ b/howitz.min.toml.example @@ -0,0 +1,18 @@ +[flask] +SECRET_KEY = +DEBUG = true + +[howitz] +storage = "./howitz.sqlite3" +devmode = true +poll_interval = 60 +timezone='LOCAL' + +[zino.connections.default] +server = + +[logging] +version = 1 + +[logging.root] +level = "ERROR" From 6188a8e848713f0c287f6859edb54d768a11529b Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Mon, 3 Jun 2024 11:29:37 +0200 Subject: [PATCH 23/30] Give a more universal name to an extended example config file --- README.rst | 4 ++-- howitz.dev.toml.example => howitz.toml.example | 0 2 files changed, 2 insertions(+), 2 deletions(-) rename howitz.dev.toml.example => howitz.toml.example (100%) diff --git a/README.rst b/README.rst index 6309ff50..3d3d43d0 100644 --- a/README.rst +++ b/README.rst @@ -26,7 +26,7 @@ Running Howitz step-by-step overview The easiest way to configure Howitz is via a ``toml`` file. 1. Create an empty ``.howitz.toml`` file in the project root folder. - 2. Copy the values from the preferred example config file ``howitz.*.toml.example`` to ``.howitz.toml``. Here using the ``howitz.min.toml.example``:: + 2. Copy the values from the preferred example config file ``howitz.*.example`` to ``.howitz.toml``. Here using the ``howitz.min.toml.example``:: $ cp howitz.min.toml.example .howitz.toml @@ -257,7 +257,7 @@ than ``LOCAL`` and ``UTC`` provided in config will be ignored and fall back to ` Example config-file for development ----------------------------------- -For development, copy the contents of the included file ``howitz.dev.toml.example`` to ``.howitz.toml`` in the same directory. +For development, copy the contents of the included file ``howitz.toml.example`` to ``.howitz.toml`` in the same directory. 1. Set ``[flask] -> SECRET_KEY`` to some long string. 2. Set ``[zino.connections.default] -> server`` to the address of a Zino 1 server. diff --git a/howitz.dev.toml.example b/howitz.toml.example similarity index 100% rename from howitz.dev.toml.example rename to howitz.toml.example From b5211da4e38139f339d304076ae2ce2abb283db8 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Mon, 3 Jun 2024 11:35:15 +0200 Subject: [PATCH 24/30] Give a more appropriate name to section about dev config file Since this section is mostly filled with general and universal info about the the values in the toml config file --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 3d3d43d0..bd77fb9a 100644 --- a/README.rst +++ b/README.rst @@ -83,7 +83,7 @@ Run in development-mode You need to have either a minimal configuration file or set two environment variables, see `Configuration`_. Tip for quickly setting up an extensive config file for dev: - Check out the `Example config-file for development`_ section. + Check out the `Example config-file (for development)`_ section. After both installation (see `Install safely`_) and `Configuration`_ are done, you can run Howitz by running @@ -111,7 +111,7 @@ You need to have either a minimal configuration file or set two environment vari Tip for quickly setting up an extensive config file: - Check out the `Example config-file for development`_ section. Make sure the config file is appropriate for + Check out the `Example config-file (for development)`_ section. Make sure the config file is appropriate for production, see `Config file for production`_. @@ -254,7 +254,7 @@ the ``[howitz]``-section or setting the environment variable ``HOWITZ_TIMEZONE`` than ``LOCAL`` and ``UTC`` provided in config will be ignored and fall back to ``UTC``. -Example config-file for development +Example config-file (for development) ----------------------------------- For development, copy the contents of the included file ``howitz.toml.example`` to ``.howitz.toml`` in the same directory. From 2b2089c1319ea12e51fde8ba00400848847f5398 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Mon, 3 Jun 2024 11:58:27 +0200 Subject: [PATCH 25/30] Set root log level to DEBUG in extended example config file --- howitz.toml.example | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/howitz.toml.example b/howitz.toml.example index 4ed30377..a74bee66 100644 --- a/howitz.toml.example +++ b/howitz.toml.example @@ -19,7 +19,7 @@ server = version = 1 [logging.root] -level = "ERROR" +level = "DEBUG" # Tweak in order to configure desired logging level [logging.formatters.default] From acbc9f63f9a1dd38089e24a52885a497c90f87ae Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 6 Jun 2024 15:04:52 +0200 Subject: [PATCH 26/30] Fix typo --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index bd77fb9a..cadba830 100644 --- a/README.rst +++ b/README.rst @@ -280,7 +280,7 @@ It is better to control ``[flask] -> SECRET_KEY`` and hardcoding them in the config file. It's best to delete them from the config file. -``[flask] -> DEBUG`` should be ``false``. You can stil override it via an +``[flask] -> DEBUG`` should be ``false``. You can still override it via an environment variable. ``[logging]`` will need adjustments. Increase the level of the ``wsgi``-handler From 49d058803280885021f573e9c8b714142a2874d1 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 6 Jun 2024 15:18:40 +0200 Subject: [PATCH 27/30] Remind to set devmode to false when configuring for prod --- README.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.rst b/README.rst index cadba830..e01eecd3 100644 --- a/README.rst +++ b/README.rst @@ -283,6 +283,8 @@ file. ``[flask] -> DEBUG`` should be ``false``. You can still override it via an environment variable. +``[howitz] -> devmode`` should be ``false``. + ``[logging]`` will need adjustments. Increase the level of the ``wsgi``-handler or only use the ``error`` handler. Change the error-handler to ship its log somewhere else, via syslog or Sentry or similar. From cede3c98eb80041a2b56899e215a979de8f986b8 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 6 Jun 2024 15:19:10 +0200 Subject: [PATCH 28/30] Remind to check out configuring for production section --- README.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.rst b/README.rst index e01eecd3..35724ffd 100644 --- a/README.rst +++ b/README.rst @@ -35,6 +35,10 @@ Running Howitz step-by-step overview Read more about other configuration methods, different configurations options and variables in the `Configuration`_ section. + **NB!**: + + When configuring for production, make sure that ``.howitz.toml`` is appropriately adjusted as described in the `Config file for production`_ section. + 4. User management step: 1. Check if you have an existing user in the Howitz database, from the project root folder run:: From bcbcf69a3a9d4cf298565a97007cca5c7b8857b3 Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Thu, 6 Jun 2024 16:54:06 +0200 Subject: [PATCH 29/30] Clarify the purpose of the refresh_interval value --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index b6cf497a..f4155c09 100644 --- a/README.rst +++ b/README.rst @@ -246,8 +246,8 @@ All config options can be overruled by environment variables. Prefix them with options. It is also possible to override logging by setting "HOWITZ_LOGGING" to a string of a Python dict but we do not recommend it, use a config file instead. -The refresh interval for the events table can be changed by adding for example ``refresh_interval = 10`` to -the ``[howitz]``-section or setting the environment variable ``HOWITZ_REFRESH_INTERVAL`` to a new value. +The refresh interval value specifies the frequency with which Howitz checks the Zino server for updates on events in the table. This value can be modified by adding, for example, ``refresh_interval = 10`` to +the ``[howitz]``-section, or by setting the environment variable ``HOWITZ_REFRESH_INTERVAL`` to a new value. Refresh interval values are in seconds and must be integers. The default value is ``5`` seconds. Debugging can be turned on either by adding ``DEBUG = true`` to the From 5a5b36611724464540f9b6cd2b4bc6f31d198e1c Mon Sep 17 00:00:00 2001 From: Ilona Podliashanyk Date: Fri, 7 Jun 2024 10:40:57 +0200 Subject: [PATCH 30/30] Attempt to describe refresh interval val without architecture details --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index f4155c09..c48164ec 100644 --- a/README.rst +++ b/README.rst @@ -246,7 +246,7 @@ All config options can be overruled by environment variables. Prefix them with options. It is also possible to override logging by setting "HOWITZ_LOGGING" to a string of a Python dict but we do not recommend it, use a config file instead. -The refresh interval value specifies the frequency with which Howitz checks the Zino server for updates on events in the table. This value can be modified by adding, for example, ``refresh_interval = 10`` to +The refresh interval value specifies the frequency with which events are checked for updates, i.e., are synchronized. This value can be modified by adding, for example, ``refresh_interval = 10`` to the ``[howitz]``-section, or by setting the environment variable ``HOWITZ_REFRESH_INTERVAL`` to a new value. Refresh interval values are in seconds and must be integers. The default value is ``5`` seconds.