The system, as is, minimally implements logging in and logging out over a session-based, RESTful JSON API. It has lots of documentation:
- initial database documentation via sqliteconvert
- RESTful documentation via Swagger
- well-documented C and JS source code
It's also portable within UNIX systems as provided by oconfigure.
You'll only use this repository once as a primer for your project. It's not something that's installed. I use this to quickly get started on a project without needing to re-implement basis user management.
This is a framework (or foundation), so you'll use this to get your project started. Begin by copying all files into your project directory. You'll also need kcgi and ksql, kwebapp, and sqliteconvert if you plan on using the database documentation.
Begin by reading the Makefile: it will list all of the
variables you'll need to set for your installation. Override these in a
Makefile.local. The default values assume an OpenBSD system with a
stock install. You'll probably need to set the following:
CPPFLAGS = -I/usr/local/include LDFLAGS = -L/usr/local/lib
make, you'll need to run
./configure to generate the
The current Makefile rules are as follows.
make to compile the sources.
make installwww to install the HTML and JS sources.
make installapi to install the Swagger RESTful documentation.
make installcgi to install the CGI script and a fresh copy of the
database. Warning: this will replace the existing database.
make updatecgi to install only the CGI script.
Most of my CGI scripts are managed by a package manager, not by hand-installation. kcgi-framework includes the building blocks for an OpenBSD package by including necessary files.
The port files exist in the OpenBSD directory. As-is, they
will install the CGI script in
/var/www/cgi-bin and the database and
database specification in
The CGI script is installed with no permission bits. This is because at initial installation, there's no database yet. And on upgrade, the database may not be in sync with the CGI script.
To solve this, the package manager will run the
script, which generates the difference between the database
specification for the existing database in
/var/www/data with the
current version's specification. It then patches the database and
installs the current specification. This keeps your database smoothly
up to date.
Of course, this is something you'll need to carefully test! It uses kwebapp-sqldiff(1), which has its limitations.
All sources use the ISC (like OpenBSD) license. See the LICENSE.md file for details.