The framework implements logging in and logging out over a session-based, RESTful JSON API. It includes the full application stack:
- database initialisation
- database interface (C language)
- REST interface (JSON)
All parts are documented as fully as possible, from the database schema to the REST API.
The framework is portable for most modern UNIX systems as provided by oconfigure. This includes OpenBSD, NetBSD, FreeBSD, Linux, Mac OS X, Solaris, and IllumOS.
You'll only use this framework once for your project---it's not something that's installed.
Copy all files into your project directory.
Then read and edit the Makefile: it will list all of the variables you'll need to set for your installation. Override these in a Makefile.local or directly in the Makefile.
Then deploy in the usual way:
% ./configure % make # make install
There are several additional targets:
installwww: only HTML and JS sources
installapi: REST OAS2.0 API docs
installcgi: CGI script and a fresh copy of the database (warning: this will replace the existing database)
updatecgi: install only the CGI script
If you want to create a user, use
encrypt(1) to generate a password
hash and insert those into the database prior to
(The hashing method depends upon the operating system.)
Assuming a user
email@example.com and substituting
yourpassword for your
yourhash for the output of the encryption:
% make % printf 'yourpassword' | encrypt % sqlite3 yourprog.db sqlite> insert into user values ('firstname.lastname@example.org', 'yourhash', 1); sqlite> .quit
printf instead of
echo is so that the trailing newline is not
considered part of the password.
You can also run this on your live database, of course.
kcgi-framework includes the building blocks for an OpenBSD port by including necessary files.
The port is in the OpenBSD directory. As-is, it installs the CGI script in /var/www/cgi-bin and the database and database specification in /var/www/data.
The port uses the
yourprog-upgrade 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.
It's possible to embed this directly into the port PLIST, if desired.
Of course, this is something you'll need to carefully test! It uses ort-sqldiff(1), which has its limitations.
All sources use the ISC (like OpenBSD) license. See the LICENSE.md file for details.