\input texinfo
@documentencoding UTF-8
@settitle SGBlog
@copying
Copyright @copyright{} 2020 @email{stargrave@@stargrave.org, Sergey Matveev}
@end copying
@node Top
@top
SGBlog is minimalistic and simple Git-backed CGI/inetd
@url{https://en.wikipedia.org/wiki/Blog, blogging} and
@url{https://en.wikipedia.org/wiki/Phlog, phlogging} engine
with email-backed comments support, written on @url{https://golang.org/, Go}.
Its main competitive features:
@itemize
@item Single binary, responsible for both blog and phlog
@item @url{https://git-scm.com/, Git} DVCS as a storage for posts and comments
@item Single small @url{https://hjson.github.io/, Hjson} configuration file
@item Uses @url{https://en.wikipedia.org/wiki/Common_Gateway_Interface, CGI}
interface (simplicity, remember?) for dealing with HTTP-server
@item Uses @url{https://en.wikipedia.org/wiki/Inetd, inetd} interface
for working as @url{https://en.wikipedia.org/wiki/Gopher_(protocol), Gopher}
server
@item Topics (tags/categories) support
@item Supports on the fly generation of
@url{https://en.wikipedia.org/wiki/Atom_(feed), Atom} feeds
for posts, comments and per-post comments
@item Single binary for email-backed comments posting
@item If access is granted, then everyone can easily create an offline
copy of your blog/phlog!
@end itemize
All of that, except for comments, topics and phlog, could be achieved
with some Git viewer like @url{https://git.zx2c4.com/cgit/about/, cgit}.
But SGBlog also is able to:
@itemize
@item Convert URLs to clickable links
@item Convert SHA1-like hashes to blog links itself
@item Include relative @code{} links for ease of navigation in
some browsers
@item @url{https://en.wikipedia.org/wiki/Gzip, gzip} compress both HTML
pages and Atom feeds
@item Respect @url{https://en.wikipedia.org/wiki/HTTP_ETag, ETag}
caching for both of them above
@end itemize
@url{http://blog.stargrave.org/example/, Here} is an example blog.
SGBlog is free software, licenced under
@url{https://www.gnu.org/licenses/agpl-3.0.html, GNU AGPLv3}:
see the file COPYING for copying conditions.
@menu
* Comments::
* Topics::
* Installation::
* Configuration::
@end menu
@node Comments
@unnumbered Comments
Comments are posted through the email interface, just by sending the
message to special address. For example:
@example
$ mutt "mailto:comment@@blog.example.com?subject=576540a5b98517b46d0efc791bb90b9121bf147e" < "/path/to/sgblog")
cgi.assign = ("sgblog" => "/path/to/sgblog")
setenv.add-environment = (
"SGBLOG_CFG" => "/path/to/example.hjson",
)
@}
@}
@end example
And be sure that you have read access to the Git repository, for example
by placing @code{lighttpd} user into @code{git} group.
Example @command{inetd} configuration (for phlog):
@example
gopher stream tcp nowait lighttpd /path/to/sgblog sgblog -gopher /path/to/gopher.hjson
gopher stream tcp6 nowait lighttpd /path/to/sgblog sgblog -gopher /path/to/gopher.hjson
@end example
For comments workability you have to configure your SMTP server to feed
incoming messages to @command{sgblog-comment-add} utility. For example,
Postfix'es @file{/etc/aliases} can contain:
@example
comment: "| /path/to/sgblog-comment-add -git-dir /path/to/blog.git -committer-email comment@@blog.example.com"
@end example
to run that utility for all @code{comment@@} address messages.
You must have enough permission to be able to write to Git repository,
but Postfix by default runs all that commands from a @code{nobody} user.
So possibly you will need to @code{setuid} that executable give
permission for @code{nobody} running:
@example
-rwsr-x--- git:nobody sgblog-comment-add
@end example
And also do not forget about @code{lighttpd} user's (possibly in
@code{git} group) read permission permissions. Make sure
@command{sgblog-comment-add} runs with correctly set @code{-umask} (027
by default) for newly created Git objects/files.
@node Configuration
@unnumbered Configuration
SGBlog is configured via Hjson configuration file. More or less
self-describing blog configuration looks like that and contains many
optional fields:
@example
@{
GitPath: /home/sgblog/blog.git
Branch: refs/heads/example
Title: "Example blog"
BaseURL: http://blog.example.com
URLPrefix: /example
AtomId: "urn:uuid:54e6e53f-c615-48f1-812c-6f6b094ebbdd"
AtomAuthor: John Doe
# URL to CSS file, optional
CSS: /style.css
# Email address of the webmaster, optional
Webmaster: "webmaster@@example.com"
# URL to about page, optional
AboutURL: /
# Optional list of optional Git URLs for corresponding
GitURLs: [
git://git.example.com/blog.git
https://git.example.com/git/blog.git
]
# If that ref is set, then comments will be loaded from it
CommentsNotesRef: refs/notes/comments
# Display link for comment writing, if email is set
CommentsEmail: something@@example.com
# If that ref is set, then topics will be loaded from it
TopicsNotesRef: refs/notes/topics
# Optional file for topics state caching
TopicsCachePath: /path/to/sgblog-topics-cache.gob
@}
@end example
Gopher configuration can use the same file, but it requires much less
options:
@example
@{
GitPath: /home/sgblog/blog.git
Branch: refs/heads/example
Title: "Example blog"
GopherDomain: phlog.example.com
AboutURL: http://blog.example.com/
# Both are optional
CommentsNotesRef: refs/notes/comments
CommentsEmail: something@@example.com
# Both are optional too
TopicsNotesRef: refs/notes/topics
TopicsCachePath: /path/to/sgblog-topics-cache.gob
@}
@end example
@bye