Metadata-Version: 2.5
Name: flshbd
Version: 0.0.9
Summary: FlashBoard
Project-URL: Documentation, https://codeberg.org/rokor/flshbd#readme
Project-URL: Issues, https://codeberg.org/rokor/flshbd/issues
Project-URL: Source, https://codeberg.org/rokor/flshbd
Author-email: Robert Kormann <rokor@kormann.info>
License-Expression: Unlicense
License-File: LICENSE.txt
Keywords: dashboard,flask
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.13
Requires-Dist: click>=8.0.0
Requires-Dist: flask>=3.0.0
Requires-Dist: werkzeug>=3.0.0
Provides-Extra: dotenv
Requires-Dist: python-dotenv>=1.0.0; extra == 'dotenv'
Provides-Extra: gunicorn
Requires-Dist: gunicorn>=21.0.0; extra == 'gunicorn'
Provides-Extra: pam
Requires-Dist: python-pam>=2.0.0; extra == 'pam'
Description-Content-Type: text/markdown

# flshbd

**A simple, Flask-based dashboard**

[![PyPI - Version](https://img.shields.io/pypi/v/flshbd.svg)](https://pypi.org/project/flshbd)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flshbd.svg)](https://pypi.org/project/flshbd)

-----

## Table of Contents

- [Installation](#installation)
- [FlashBoard](#flashboard)
- [Administration](#administration)
- [Protecting services on subdomains](#protecting-services-on-subdomains)
- [License](#license)

## Installation

_**Remark**_ _FlashBoard_ is not published yet on PyPI.

```console
pip install flshbd
```

Optional installs are `pam` for Linux's [Pluggable Authentication Module](https://github.com/linux-pam/linux-pam) and `gunicorn` ([Gunicorn](https://gunicorn.org/)) as [WSGI server](https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface).

---

_**Alpha** Software_

This software is in **Alpha** State. Check the [changelog](CHANGELOG.md) for information on potential changes in the upcoming versions. Furthermore, as long as we are in *Alpha* (micro versions), there might be breaking changes.

---

## FlashBoard

_FlashBoard_ is a small Flask-based web application that provides an interface to organize and access -- mainly local -- tools or services. The dashboard features a clean header/sidebar/main/footer layout with user authentication, and access control based on user groups.

Users are organized in (user) groups, and sites are collected in site groups. The sidebar dynamically displays only these site groups a user has access to, based on her or his (user) group memberships. This allows for a personalized dashboard experience. The information about users and sites, their groups and the access table are stored in a SQLite3 database. The user and site groups can be changed on-the-fly during normal operation of _FlashBoard_, and is backed by a static model for testing and development.

The sidebar can be hidden and shown via the hamburger button in the header. On small screens (max. 768px width) the sidebar is hidden by default, and can be toggled open the same way.

_FlashBoard_ supports for its sites both, iframe-based content (_FlashBoard_-external services, typically on the same machine, or within the same LAN, and shown as site) in the main (view), and Jinja2-based template content (_FlashBoard_-internal sites). Session management is handled through client-side cookies with a configurable inactivity timeout.

## Administration

The dashboard includes a CLI for managing it, `fld dash <start/stop/status>`, and can operate in the environments _development_ (Flask-internal server in debug mode), or _production_ (Gunicorn- or Flask server-based, default).
The SQLite3 databases, one for _development_ within the current (typ. project) folder `flshbd-data`, and a user-based folder `~/.config/flshbd` (XDG compliant) for _production_, are administered also via the same command `fld` on CLI. The structure of `fld` is `fld [--env <production/development>] command [command options] subcommand [subcommand options] [parameter]`. Most commands should be obvious, e.g., the command for _production_ user management reads `fld user <list/add/modify/delete>`. Use `--help` (short `-h`) at each command level for the available options.

On the first server start, the database is auto-initialized with an empty schema, if not there (parallel to the templates and static files, see below). It can be populated by hand (e.g., `fld user add ...`), or from the static model running `fld db migrate`. The latter copies the static three `user/password` pairs, `admin/admin123`, `user1/user123`, and `user2/user223` (of course, salted and hashed in the databases), and contents for user groups, site and site groups. Check it, using the CLI commands, e.g., `fld user list -v`. Of course, now you can login using the static user credentials, and inspect the default sites and site groups, which are accessible for the user groups.

**Warning** These static users MUST be deleted (or at least their password changed) in a _production_ environment for obvious reasons!

Users and sites can be active or inactive. Site goups are sorted alphabetically within the sidebar, as well as sites within site groups. This can be overruled, e.g., for sites via `fld site modify <site> --sort-order <integer>` (defaults to 0, smaller is earlier in the list). Misaligned sites or site groups might lead to non-existing links within _FlashBoard_. In this case, the top-most site is shown. It is therefore useful to place an informative site there. All objects have a `name` (`username` for users) used internally and for the CLI, and a `description` (`full-name` for users) used for the dashboards.

The title of _FlashBoard_ can be set, e.g., to "My Dashboard" via `fld db config set title "My Dashboard"`, or reset by `fld db config set title ""`. The title keyword and its value is stored within the database in a (string-based) key/value table `config`. Using the same key/value scheme, the keys `info` and `important` create messages above the login area. Important messages overwrite info messages. Values of these keys can only be text messages, HTML is not allowed.

Templates and static files are taken from the environment's data directory (`flshbd-data/` in _development_, `~/.config/flshbd/` in _production_): on the first start they are populated automatically with the bundled copies shipped with _FlashBoard_, and can then be customized per environment (e.g., additional partials for template sites, which `fld site add --type template` validates against the resolved template folder). Set the environment variables `FLSHBD_TEMPLATE_FOLDER` and `FLSHBD_STATIC_FOLDER` to use custom locations instead. Note that template sites are Jinja2-rendered with the privileges of the _FlashBoard_ process.

The folders are resolved once when the server process starts, so changing them requires a restart (Flask and Gunicorn alike); edits to template files are picked up live only in _development_, while static files are always read from disk per request. Details in `AGENTS.md`.

All `FLSHBD_*` environment variables can alternatively be set in a `.env` file within the environment's data directory (`flshbd-data/.env` in _development_, `~/.config/flshbd/.env` in _production_): on the first start, a documented copy of the bundled defaults is placed there (never overwritten), and can then be edited per environment. Loading the file requires the optional dependency `python-dotenv` (`pip install flshbd[dotenv]`). The precedence is: exported environment variable first, `.env` value second, built-in default third. The values are read once at process start, so changes require a restart.

The signing of the session cookie is performed by an ephemeral secret key, which is created when starting a _FlashBoard_ session via `fld dash start`. As a consequence, all existing sessions become invalid, when _FlashBoard_ is (re)started. To avoid this, create an environment variable `FLSHBD_SECRET_KEY` (`fld dash generate-secret-key` might help).

The session inactivity timeout (a sliding timeout, default 1800 s = 30 min) can be adjusted via the `FLSHBD_SESSION_LIFETIME` environment variable, whose value is the timeout in seconds (e.g. `FLSHBD_SESSION_LIFETIME=3600`). Unset or invalid values fall back to the default.

## Protecting services on subdomains

_FlashBoard_ can also guard iframe-type services running on subdomains (e.g. `service.example.com`) while _FlashBoard_ itself runs behind a reverse proxy at `example.com`. This uses Nginx's [`ngx_http_auth_request_module`](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html): for every request to the subdomain, Nginx first makes an internal subrequest to _FlashBoard_'s `/auth/verify` endpoint, which checks the session cookie and — if a site is given — whether the user has access to that site.

Please see [Nginx auth](docs/nginx_auth.md) for more details on this functionality.

## License

`flshbd` is distributed under the terms of the [Unlicense](https://unlicense.org) license.
