98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
# Fatimas Calendar
|
|
|
|
A mobile-first Flask calendar with session authentication and infinite week scrolling.
|
|
|
|
Amounts and worked/vacation/sick statuses selected for dates are stored persistently in `instance/calendar.sqlite`, which is created automatically on first launch.
|
|
|
|
## Run it
|
|
|
|
```sh
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
waitress-serve --host=0.0.0.0 --port=9009 flask_fatima:app
|
|
```
|
|
|
|
To use a different port, substitute it in the command (for example,
|
|
`--port=8080`). The application exposes its WSGI callable as `flask_fatima:app`, so it
|
|
can also be used by platforms that ask for an application entry point.
|
|
|
|
Set the username, password, and Flask signing key in `config.yaml` before starting. This file is excluded from Git. Use `config.example.yaml` as the documented template when setting up another machine.
|
|
|
|
The two paid quick-choice buttons are configured in the same file:
|
|
|
|
```yaml
|
|
amounts:
|
|
presets:
|
|
- "55"
|
|
- "27.50"
|
|
```
|
|
|
|
The €0 and custom-amount controls remain available automatically.
|
|
|
|
## Reverse proxy path
|
|
|
|
The app is served below `/fatima` by default. Configure the external path in
|
|
`config.yaml`:
|
|
|
|
```yaml
|
|
flask:
|
|
url_prefix: "/fatima"
|
|
log_file: "/tmp/fatima.log"
|
|
database: "instance/calendar.sqlite"
|
|
```
|
|
|
|
Set `URL_PREFIX` in the environment to override this value at deployment time.
|
|
Use an empty value (`url_prefix: ""` or `URL_PREFIX=`) to serve from `/` instead.
|
|
The reverse proxy must preserve the prefix when forwarding requests to Waitress.
|
|
|
|
## Import the Excel calendar
|
|
|
|
Preview an import without changing the database:
|
|
|
|
```sh
|
|
python scripts/import_excel.py /path/to/fatima.xlsx
|
|
```
|
|
|
|
The preview prints the absolute workbook and database paths, current database
|
|
row counts and date range, discovered workbook values, and overwrite counts.
|
|
Check that the printed database path is the same file used by the production
|
|
app before applying the import.
|
|
|
|
Add `--apply` to import:
|
|
|
|
```sh
|
|
python scripts/import_excel.py /path/to/fatima.xlsx --apply
|
|
```
|
|
|
|
The importer refuses to write if the database is missing, has the wrong schema,
|
|
or the workbook contains no importable data. It creates a consistent SQLite
|
|
backup before writing, reads every imported value back after committing, and
|
|
prints the final row counts and date range. If production uses a non-default
|
|
database location, specify it explicitly:
|
|
|
|
```sh
|
|
python scripts/import_excel.py /path/to/fatima.xlsx --database /absolute/path/calendar.sqlite --apply
|
|
```
|
|
|
|
On the iPhone, visit `http://<your-computer-on-the-local-network>:9009/fatima/`.
|
|
Waitress listens on all network interfaces with the command above. For anything
|
|
exposed beyond a trusted home network, put it behind an HTTPS reverse proxy.
|
|
|
|
For deployments, `APP_CONFIG` can point to a YAML file elsewhere. `SECRET_KEY`,
|
|
`APP_USERNAME`, `APP_PASSWORD`, `DATABASE`, and `LOG_FILE` environment variables optionally
|
|
override the corresponding values. `DATABASE` should be an absolute path to the
|
|
SQLite file used in production.
|
|
|
|
The YAML `flask.database` path is resolved relative to the directory containing
|
|
the selected config file. If it is omitted, the app uses
|
|
`instance/calendar.sqlite` beside `flask_fatima.py`; it no longer relies on
|
|
Flask's environment-dependent inferred instance directory.
|
|
|
|
At startup, the app prints a database summary to the Waitress log containing the
|
|
resolved path, amount and status totals, distinct recorded-date total, and date
|
|
range. Compare that path and those totals with the importer's output to confirm
|
|
that both processes use the same database. The timestamped summary is also
|
|
appended to the configured `flask.log_file` each time the app starts. It defaults
|
|
to `/tmp/fatima.log` and can be overridden at deployment time with `LOG_FILE`.
|