+++ /dev/null
- SGBlog -- Git-based CGI/inetd blogging/phlogging engine
- =======================================================
-
-DESCRIPTION
-
-SGBlog is a simple blogging engine with a Git-based storage, CGI
-interface for HTTP-server, inetd interface for serving as Gopher server.
-It can be used as a cgit replacement for readonly Git repository viewing
-and Atom feed generation. But it has better features:
-
-* URLs are tried to be converted to clickable links
-* SHA1 hashes are tried to be converted to blog links itself
-* Relative <link rel> links are included for easy navigation
-* Each page has ETag and it is checked against the request for client-side
- caching
-* Pages can be gzip-compressed, depending on Accept-Encoding header
-* Gopher protocol support for phlog creation
-* Commenting support
-
-CONFIGURATION
-
-SGBlog is configured via Hjson configuration file:
-
- {
- GitPath: /home/git/pub/stargrave-blog.git
- Branch: refs/heads/english
- Title: "English Stargrave's blog"
-
- BaseURL: http://blog.stargrave.org
- URLPrefix: /english
-
- AtomId: "urn:uuid:18e2f27c-a668-4e85-822e-b902376be5e3"
- AtomAuthor: Sergey Matveev
-
- # 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 <link rel="vcs-git">
- GitURLs: [
- git://git.stargrave.org/stargrave-blog.git
- https://git.stargrave.org/git/stargrave-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
- }
-
-Gopher mode can use the same configuration file, but it requires much
-less options:
-
- {
- GitPath: /home/git/pub/stargrave-blog.git
- Branch: refs/heads/english
- Title: "English Stargrave's blog"
-
- AboutURL: http://blog.stargrave.org/
-
- CommentsNotesRef: refs/notes/comments
- CommentsEmail: something@example.com
-
- GopherDomain: phlog.stargrave.org
- }
-
-COMMENTS
-
-Each comment is just a plaintext with From and Date headers. They are
-stored in concatenated netstring serialized format as a Git note to
-corresponding commit. They are added through email by feeding email
-message to sgblog-comment-add.
-
-LICENCE
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as
-published by the Free Software Foundation, version 3 of the License.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
--- /dev/null
+\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 Supports on the fly generation of
+ @url{https://en.wikipedia.org/wiki/Atom_(feed), Atom} feeds
+@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 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{<link rel>} 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::
+* 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" <<EOF
+This is the comments contents.
+Could be multilined of course.
+EOF
+@end example
+
+Comments are stored in Git as a @url{https://git-scm.com/docs/git-notes, note}.
+Those objects could be updated without touching the base commit itself.
+
+Each comment is just a plaintext with @code{From} and @code{Date}
+headers. @code{From} is a name of email sender (with email address
+stripped off).
+
+Technically comments are stored in concatenated
+@url{https://en.wikipedia.org/wiki/Netstring, netstring}. Only
+@code{text/plain} or @code{multipart/signed+text/plain} email messages
+are accepted and only with UTF-8, US-ASCII, ISO-8859-1 character sets.
+Sane people won't send HTML email anyway, but this is just a precaution.
+
+@node Installation
+@unnumbered Installation
+
+SGBlog's is written on Go and uses its modules. Hopefully you can
+install it just by running:
+
+@example
+$ go get go.stargrave.org/sgblog/cmd/sgblog
+$ go get go.stargrave.org/sgblog/cmd/sgblog-comment-add # if you need commenting
+@end example
+
+Unfortunately by default it uses HTTPS and Go's third party servers
+(@code{sum.golang.org}, @code{proxy.golang.org}) that trust neither
+@code{CACert.org}'s CA (used previously) nor @code{ca.cypherpunks.ru}
+CA. So either disable their usage and trust that certificate:
+@code{GOPRIVATE=go.stargrave.org/sgblog}, or clone its source code
+manually and build in place:
+@url{git://git.stargrave.org/sgblog.git},
+@url{https://git.stargrave.org/git/sgblog.git}.
+
+For enabling blog availability you have to use HTTP server with CGI
+interface. Example part of @url{http://www.lighttpd.net/, lighttpd}'s
+configuration:
+
+@example
+$HTTP["host"] == "blog.example.com" @{
+ server.document-root = www_dir + "/blog.example.com"
+ $HTTP["url"] =~ "^/example" @{
+ alias.url += ("/example" => "/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 <link rel="vcs-git">
+ 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
+@}
+@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
+@}
+@end example
+
+@bye