gourmetj-springboot/README.md

# Gourmet Recipe Manager - Spring Boot - Version 2

This is a port of Thomas Hinkle (thinkle) Gourmet Recipe Manager.

As explained in the original version, thinkle's original Gourmet Recipe Manager
desktop app has suffered frequently over the years by changes made to external
components that it depended on and unfortunately he has not had the time to
repair the the app after recent upgrades (including Python 3 and Gnome library) changes broke it.

Java is not only "write once/run anywhere", but also was designed for an environment
where changes should not break existing Java apps. Hence the port. It was easier
than trying to learn all the new external resources used by the Python version,
make detailed repairs and wait for it to break again.

## Functionality

This version of the system should provide all of the basic Recipe management functions, including adding new recipes, pasting in lists of ingredients, and managing
shopping categories. The ultimate intent is to provide all functions that the original Python app did.

## Building the app

You must have Maven installed on your system to build a copy of the app
from scratch. You must have Java 11 or later installed on your
system to run Maven and to run the app.

This project can be built on the command line using the
``mvn clean install`` command if you have Maven installed in
your PATH.

Note that the first time you run Maven, it may download a lot of
data from the Internet. This data will be cached by Maven so
thereafter, you will not need an Internet connection unless
there are changes to the app.

## Running the app

This project can be run from the command line by using the
``mvn spring-boot:run`` command. Or do an install build and
use the JAR file that Maven builds in the ``target`` directory.
for example:
```
java -jar target/gourmetj-0.1.1-SNAPSHOT.jar
```

The actual JAR name will vary depending on the build version.
You can copy this jar to any location you prefer.

You must have a recipe database file (see below) to store the
recipes in. By default, it will be looked for in your
home directory.

As of the 0.1.4 release, the parts of the application that can
alter the database are now password-protected. You will need
a ``.gourmetpw`` file to contain your userid/password
definitions. By default it should be in the same directory
that you are running the application from. A sample password file
is included in this project.

To actually access the application, open your web browser
to ``http://localhost:8080``

## Database

This product uses the same database as the Python-based version
of the system, which is a SQLite3 database named ``recipes.db``.

At the moment this app cannot build a database from scratch,
so you must use an existing copy of a ``recipes.db`` file.

## Note on JavaServer Faces
The Spring Boot version supersedes a previous port based on the Apache Tobago JSF tag library. It uses the PrimeFaces JSF tag library, as presently that platform has better Spring Boot support. Plus Tobago is quite different from most of the
extension tag libraries to the point where it almost isn't JSF.

## New in Version 2.0

### Database change

The backing database as defined in the project is now MySQL
instead of SQLite. The SQLite JDBC driver may have been a bit
casual about a few things compared to MySQL. The JPA should work
for either database now, although it should be noted that SQLite
isn't really intended for multi-user webapps and should only be
employed when you run this app on your local desktop.

### Improved graphics support

A lot of recipe websites publish images in webp form. Support
for webp has now been added.

### Better session management

JSF tends to depend on session-scope context. Sessions, however
time out and this has been an annoyance when a recipe is being
displayed. To minimize this, better timeout mechanisms have been
installed and the recipe browser keeps last-search and search-type
values in long-lived cookies on the client. The server will read
and cache them, but if the server times out, it will automatically
re-read the cookies on the next request.

When editing, the AJAX controls tended to get confused when a
session timed out. New changes give a "save work" warning 5 minutes
before timeout, and force a timeout from JavaScript that
exits the unattended page before the user can run afoul of the
lost session.

Note that by default, JSF caches ViewState in a session so every
JSF View can cause a session to be created, not just Views that
reference View- or SessionScoped backing beans. This is alterable
by setting an option in the faces-config.
force 

### Developer/deployer note.
Because of caching, updated installations
may not render properly. Manually request the "/main.xtml" resource
and that should flush out stale info being used by "/main.jsf".

Followup: Excess payloads were being added to the welcome page
that caused HTTP "400" errors fetching resources. A fix has
been made, although the ultimate solution will probably be more
JSF-friendly.

Security note: The gourmetj password file is a simple CSV file
with "userid","password" plain text, NOT htpasswd form. Modify the
SpringSecurityConfig if you want something more rigorous. 

## Minor release 2.0.1

This release can build an installable RPM for Red Hat-compatible
systems, including CentOS and its relatives and Fedora.

Just run ``mvn install`` and the RPM will be produced under the
``/target/rpm`` directory.