Leonard Richardson <leonardr@segfault.org>
Practically all NewsBruiser setup and configuration is done through
the Web. There's a lot of context-sensitive documentation presented as
part of the application, and there's not much point in recapping all
of that here. Instead, this document will talk about the minor
webserver configuration you might have to do, and the two
configuration files that you might need to change manually.
Webserver configuration
NewsBruiser doesn't care where it's installed. It can operate equally well running as a site-wide CGI or underneath your home directory. The only difficulty is that the NewsBruiser package contains both a CGI script, which needs to be run, and some static files like images and CSS files, which need to be sent right through to the web browser.
Now, if you've got control over your webserver configuration, you can set up a general alias to serve the content and a more specific alias to run the CGI script as a CGI.
Alias /nb/ /WEB_ROOT/newsbruiser/ ScriptAlias /nb/nb.cgi /WEB_ROOT/newsbruiser/nb.cgi
Just double check that your NewsBruiserData
subdirectory isn't accessible via the web, or people will be able to
see your private notebooks, the IP addresses of your commenters, and
other secret stuff. The NewsBruiser installation script installs an
.htaccess file in the NewsBruiserData directory to
prevent people from going there, but it never hurts to make sure.
If you don't have control over your webserver configuration, and
the webserver configuration you're stuck with isn't smart enough to
run CGIs as CGIs and serve everything else as content, you need to
split your NewsBruiser install into two directories. In one directory,
probably your personal cgi-bin/ directory, you will put
the NewsBruiser source code. The other directory will be your content
directory. Perhaps in a subdirectory of your webserver root, you'll
move the www/, themes/, and
resource/ directories. Then you'll need to enter the URL
of the content directory as baseContentURL in your cfg.py file. See below, or look in
cfg.py.sample for an example.
config.location: The Tip-Off File
By default, NewsBruiser puts its notebooks and configuration file in the NewsBruiserData subdirectory of the NewsBruiser installation directory. It creates a simple .htaccess file in that directory which denies web access to the directory, so that prying eyes can't reveal NewsBruiser secrets like passwords.
If this .htaccess trick doesn't work with your webserver or with your webserver's configuration, or if you just want the data directory to be elsewhere, then you can create the NewsBruiser data directory somewhere else, out of the webspace altogether. If you do this, you need to put a file called config.location in the top-level NewsBruiser installation directory. This file contains one line, which is the path to the NewsBruiser configuration file (the ".nbrc" file). NewsBruiser will assume that the installed notebooks are contained in subdirectories of the directory containing the configuration file.
For example, if you tell NewsBruiser to put its data directory into /home/me/.nbData/, then your config.location file needs to contain the following line:
/home/me/.nbData/.nbrc/
NewsBruiser will assume that the installed notebooks are the
notebook "foo' in /home/me/.nbData/foo, the notebook "bar" in
/home/me/.nbData/bar, etc. (Obviously, if there are
subdirectories which aren't really NewsBruiser notebooks, NewsBruiser
won't think they're notebooks.)
cfg.py: The Mad Scientists' Playground
Previous versions of NewsBruiser required that you change the Python file cfg.py. In almost all cases you will not need to do this anymore. The only entries in cfg.py you might need to change is baseURL and baseContentURL.
NewsBruiser tries to guess baseURL, and it almost always guesses correctly, but if it doesn't then you need to set it straight by changing cfg.py. It should be set to the relative URL to the directory in which you've installed NewsBruiser. For instance, if your webserver root is /home/httpd and you've put NewsBruiser in /home/httpd/cgi-bin/newsbruiser/, then your baseURL is "/cgi-bin/newsbruiser/".
By default, baseContentURL is the same as baseURL, but this might not work for you if your NewsBruiser directory is ScriptAliased and you can't access static content inside it. You can move NewsBruiser's themes/, resources/, and www/ directories into another directory elsewhere in your webspace, and designate that directory your baseContentURL (or just define another view into the NewsBruiser directory and use that).
There are a couple of other things you might want to change, like the automatic nice level and the URL rewriter. These are semidocumented features of NewsBruiser. The cfg.py file itself goes into more detail about those.