BlÃ«rg Documentation

From e4bb47fae5fbdd876d9f133188dfe8ae65acbe9c Mon Sep 17 00:00:00 2001 From: Chip Black Date: Sat, 29 Mar 2014 15:24:41 -0500 Subject: [PATCH] Update documentation for perl-lib and install-environment --- www/css/doc.css | 6 ++++ www/doc/index.html | 90 +++++++++++++++++++++++++++++++++++++--------- 2 files changed, 80 insertions(+), 16 deletions(-) diff --git a/www/css/doc.css b/www/css/doc.css index be17dda..1173b95 100644 --- a/www/css/doc.css +++ b/www/css/doc.css @@ -11,6 +11,12 @@ h1, h2, h3, h4, h5 { clear: both; } +pre { + background-color: #090909; + color: #F7F7F7; + padding: 0.5em; +} + .pizzapie { width: 25%; font-family: sans-serif; diff --git a/www/doc/index.html b/www/doc/index.html index e98ef47..61b8035 100644 --- a/www/doc/index.html +++ b/www/doc/index.html @@ -3,6 +3,7 @@ BlÃ«rg Documentation + @@ -17,7 +18,7 @@ as either a standalone HTTP server, or a CGI. BlÃ«rg is written in pure C.

Installing +
Running BlÃ«rg
- Getting the source
- Requirements
- /passwd - Change a user's password
Libraries +
- C
- Perl
+
Design
- Motivation
-
Installing
+
Running BlÃ«rg

Getting the source
@@ -123,26 +130,17 @@ reason, it's better to use a subdomain (i.e., blerg.yoursite.com is easier than yoursite.com/blerg/). If you do want to put it in a subdirectory, you will have to modify www/js/blerg.js and change baseURL at the top as well as a number of other self-references -in that file and www/index.html. The CGI version should -work fine this way, but the HTTP version will require the request to be -rewritten, as it expects to be serving from the root. +in that file and www/index.html.
You cannot serve the database and client from different domains (i.e., yoursite.com vs othersite.net, or even foo.yoursite.com and bar.yoursite.com). This is a requirement of the web browser — the same origin policy will not allow an AJAX request to travel across -domains. - -
For the standalone web server:
+domains (though you can probably get around it these days with Cross-origin + resource sharing). -
Right now, blerg.httpd doesn't serve any static assets, -so you're going to have to put it behind a real webserver like apache, -lighttpd, nginx, or similar. Set the document root to the www -directory, then proxy /info, /create, /login, /logout, /get, /tag, and -/put to blerg.httpd. You can change the port blerg.httpd -listens on in config.h. - -
For the CGI version:
+
For straight CGI with Apache

Copy the files in www/ to the root of your web server. Copy blerg.cgi to your web server. Included in www-configs/ is @@ -150,10 +148,47 @@ a .htaccess file for Apache that will rewrite the URLs. If you need to call the CGI something other than blerg.cgi, the .htaccess file will need to be modified. +
For nginx
+ +
Nginx can't run CGI directly, and there's currently no FastCGI +version of BlÃ«rg, so you will have to run it under some kind of CGI to +FastCGI gateway, like the one described here on the nginx wiki. This +pretty much destroys the performance of BlÃ«rg, but it's all we've got +right now. +
The extra RSS CGI

There is an optional RSS cgi (rss.cgi) that will serve RSS feeds for users. Install this like blerg.cgi above. +As of 1.9.0, this is a perl FastCGI script, so you will have to make +sure the perl libraries are available to it. A good way of doing that +is to install to an environment directory, as described below. + +
Installing to an environment directory
+ +
The Makefile has support for installing BlÃ«rg into a directory that +includes tools, libraries, and configuration snippets for shell and web +servers. Use it as make install-environment + ENV_DIR=<directory>. Under <directory>/etc will be +a shell script that sets environment variables, and configuration +snippets for nginx and apache to do the same. This should make it +somewhat easier to use BlÃ«rg in a self-contained way. + +
For example, this will install BlÃ«rg to an environment directory +inside your home directory: + +
```
user@devhost:~/blerg$ make install-environment ENV_DIR=$HOME/blerg-env
+...
+user@devhost:~/blerg$ . ~/blerg-env/etc/env.sh
+
```
+ +
Then, you will be able to run tools like blergtool, and +it will operate on data inside ~/blerg-env/data. Likewise, +you can include +/home/user/blerg-env/etc/nginx-fastcgi-vars.conf or +/home/user/blerg-env/etc/apache-setenv.conf in your +webserver to make the CGI/FastCGI scripts to the same thing.
API
@@ -357,6 +392,29 @@ the password matches, the user's password is set to If the password doesn't match, or one of password or new_password are missing, the server returns JSON failure. +
Libraries
+ +
C
+ +
Most of BlÃ«rg's core functionality is packaged in a static library +called blerg.a. It's not designed to be public or +installed with `make install-environment`, but it should be relatively +straightforward to use it in C programs. Look at the headers under the +databse directory. + +
A secondary library called blerg_auth.a handles the +authentication layer of BlÃ«rg. To use it, look at +common/auth.h. + +
Perl
+ +
As of 1.9.0, BlÃ«rg includes a perl library called +Blerg::Database. It wraps the core and authentication +functionality in a perlish interface. The module has its own POD +documentation, which you can read with your favorite POD reader, from +the manual installed in an environment directory, or in HTML here. +
Design

Motivation
-- 2.25.1

For the standalone web server:

For the CGI version:

For straight CGI with Apache

For nginx

The extra RSS CGI

Installing to an environment directory