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

NAME
     ephemera - SCGI Blog Server

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

DESCRIPTION
     Ephemera is an event-driven SCGI application server dedicated to serving-
     up a single blog with no comment facility.

     Ephemera is for people who have their own hosts on which they can install
     software, who know HTML5 and CSS, and who prefer working with text-based
     tools. Posts are stored in an in-memory SQLite database that is read from
     disk at startup.  Yes, Sunshine, you can afford to keep the database in
     memory.  The entire works of Shakespeare in plain text are less than 6
     MiB.

   MANAGING CONTENT
     You write your posts in HTML5.  You can put whatever elements you like
     into your posts, but the database stores only the HTML.  If you want to
     reference other resources, you will need to create web-visible
     directories to hold those resources.

     There is no web interface for managing content because I would rather be
     rolled in seal oil and exposed to polar bears than use web-based tools.
     You manage the on-disk database with six munger(1) scripts that work with
     plain text.  Five are command-line tools that can be used for one-off
     operations or shell scripting.  The sixth is an interactive fullscreen
     database editor.  The scripts send the server a SIGHUP to notify it to
     reload the database.

     For example, you can add posts from remote hosts like this:

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

     My goodness.  That is a prime candidate for a shell alias.

     The management scripts are located in /usr/local/bin and are documented
     internally with comments.  All scripts require the path to the database
     file to be passed as a command line argument.

     The five command-line scripts are named create.munger, add.munger,
     replace.munger, delete.munger, and extract.munger.

     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.

     k

     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

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

     0

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

     l

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

     w

     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

     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.  If you include block
                    elements in your post bodies, then you must make them
                    float left to render properly.  This is true of ol, ul,
                    and pre elements.

     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.

   CONFIGURATION
     If it cannot allocate memory from the system, ephemera exits. You need to
     set the maximum number of simultaneous connections with the -m option to
     a value that is suitable for your host's resources.

     To configure ephemera:

     1.   Set the server options in /etc/rc.conf appropriately for your
          system.  See SERVER OPTIONS.

     2.   copy /usr/local/share/ephemera/ephemera.config to the location you
          specify with the -f server option.  Edit the file.  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.   Copy ephemera.css, Merriweather-Bold.ttf, Merriweather-BoldIt.ttf,
          Merriweather-Light.ttf, and Merriweather-LightIt.ttf from
          /usr/local/share/ephemera to the directory that you specified with
          "web_directory" in ephemera.config.

     5.   Start your web server.  Start ephemera with
          /usr/local/etc/rc.d/ephemera start.  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="-u www -g www -l /var/run/ephemera.socket"

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

     -m  The -m option specifies the number of simultaneous connections the
         server will accept.  The value defaults to 8192.

     -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.

     -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.  Use a UNIX socket instead of the loopback
         interface if the web server and ephemera run on the same host.  Using
         the loopback address unnecessarily interposes the TCP/IP stack
         between the two servers, which degrades performance.

         The -l option cannot be present on the command line if the -p or -i
         option is also present.  The server creates the socket on startup.
         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.

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

                               Wed, Oct 17, 2018