DragonFly On-Line Manual Pages

ephemera(8) DragonFly System Manager's Manual ephemera(8)

NAME
ephemera - SCGI Blog Server

SYNOPSIS
ephemera [-f <config_file> -u <user> -g <group> -m <instances> -i <interface> -p <port> -l <socket> -x]

DESCRIPTION
Ephemera is an SCGI application server dedicated to serving-up a single
blog. Ephemera is intended for developers who have their own hosts on
which they can install software, who know HTML5 and CSS, and who prefer
working with text-based tools. The post database is stored in a SQLite
database file.

There is no web interface for managing content because I would rather be
rolled in maple syrup and exposed to polar bears than use web-based
tools. You manage blog data with six munger(1) scripts that work with
plain text. To use these tools you need console access to the host on
which the server runs.

You can add posts from remote hosts like this:

ssh user@host '/usr/local/bin/add.munger /path/to/db/ephemera.sqlite' < post.txt

You can create a shell alias to make it simpler.

CONFIGURATION
To configure ephemera:

1. Configure the server options (listed under SERVER OPTIONS)
appropriately for your system.

2. Edit /usr/local/etc/ephemera.config appropriately for your blog.
Each setting is documented with a comment.

3. Configure your web server to forward requests for the resource you
have described with "path" in ephemera.config to the interface you
have described with "ephemera_flags" in /etc/rc.conf.

4. Add the "ephemera_enable" variable to /etc.conf. To have ephemera
started automatically on system start, set the value to "YES". To
require that ephemera be started manually, set the value to "NO".

5. Copy ephemera.css from /usr/local/share/ephemera to the directory
that you specified with "web_directory" in ephemera.config.

6. Start ephemera, and point your web browser at it.

7. Customize ephemera.css.

SERVER OPTIONS
The following command line options are available. To use an option,
insert it into the value of the ephemera_flags variable in /etc/rc.conf.
For example,

ephemera_enable="YES"
ephemera_flags="-p 5000 -i 127.0.0.1"

-f The -f option specifies the path to the directory containing
ephemera.config. This value defaults to /usr/local/etc.

-u

-g The -u and the -g options to specify the user and group of the server
processes. Both values default to "nobody". If you use the -l
option to make the server listen on a UNIX socket, then you must use
these options to ensure that ephemera runs with the same user or
group setting of the web server, or the webserver will not be able to
connect to the socket.

-m The -m option specifies how many workers processes should be run.
This value defaults to the number of CPUs on the host system. Each
worker process is a kqueue driven multiplexer.

-p The argument to the -p option specifies the port to listen on. The
port defaults to 4000.

-i By default, ephemera accepts connections on all interfaces it can
find capable of IPv4 or IPv6. The -i option overrides this behavior
to limit drood to accepting connections from a specified interface
only. Pass the IP address of the desired interface as argument.

-l The -l option specifies the path to a UNIX-domain socket for the
server to listen on. This option cannot be present on the command
line if the -p or -i options are also present. The server creates
the specified socket when it starts, unlinking the socket first if it
already exists in the filesystem. The owner and group of the socket
is changed to the values of the -u and -g options. The permissions
of the socket are set to srwxrwx---.

-x The -x option prevents ephemera from becoming a daemon. The server
runs in the foreground of the terminal where it is started. The
server is stopped with signals (ie., Control-C). The server will not
write its pid to /var/run/ephemera.pid.

MANAGING CONTENT
The management scripts are located in /usr/local/bin and are documented
internally with comments. Five are command line tools: create.munger,
add.munger, delete.munger, replace.munger, extract.munger. All scripts
require the path to the database file to be passed as a command line
argument.

The sixth script, edit.munger, is an interactive console program to view,
add, delete, edit, and search for posts in the database. The following
commands are available.

j Move the cursor up or down one line. These commands can
be preceded with a repeat count.

[

] Move the cursor up or down one paragraph. These commands
can be preceded with a repeat count.

[space]

[backspace] Scroll the screen forward or backward one screenful.
These commands can be preceded with a repeat count.

G Move the cursor to the top or the bottom of the current
screen.

$ Move the cursor to the start or end of the current line.

h Move the cursor forward or backward by one character.
These commands can be preceded with a repeat count.

b Move the cursor forward or backward by one word. These
commands can be preceded with a repeat count.

/ <pattern>

? <pattern> Search forward or backward in the current screen for a
match on a regular expression. Searches wrap-around.
These commands can be preceded with a repeat count.

N Repeat the last pattern search in the same or the opposite
direction. These commands can be preceded with a repeat
count.

q Quit the database editor.

e Extract the current post to a text file with the same name
as the post's database Id.

s Search the database using the SQLite full text search
interface. Articles containing matches are added to the
post list in reverse chronological order.

Control-l Load the post list with all posts in reverse chronological
order.

i Toggle on or off the display of post Ids in the post list.

a Add a new post to the database. The editor specifed by
the EDITOR environment variable is run on an empty file.

Insert the post's complete title on the first line.
Insert a blank line after the title line. The title is
wrapped in an <h3> element when it is sent to clients.

Insert the post's body after the blank line. Markup the
body to be proper HTML5. Both the title and body are
inserted into a left-floated div. Make block elements in
the body float left, or they will not render correctly.

d Delete the current post.

[enter] Load the current post into the viewer. When the viewer is
onscreen, the following additional commands are available:

[enter] Run the editor specified by the EDITOR
environment variable on the current post.

u Update the database. Do this when you exit
from your editor if you want to preserve your
changes.

q Return to the post listing.

AUTHORS
James Bailie <jimmy@mammothcheese.ca>
http://www.mammothcheese.ca

April 18, 2015