README.texi

   1 \input texinfo
   2 @documentencoding UTF-8
   3 @settitle SGBlog
   4
   5 @copying
   6 Copyright @copyright{} 2020 @email{stargrave@@stargrave.org, Sergey Matveev}
   7 @end copying
   8
   9 @node Top
  10 @top
  11
  12 SGBlog is minimalistic and simple Git-backed CGI/inetd
  13 @url{https://en.wikipedia.org/wiki/Blog, blogging} and
  14 @url{https://en.wikipedia.org/wiki/Phlog, phlogging} engine
  15 with email-backed comments support, written on @url{https://golang.org/, Go}.
  16
  17 Its main competitive features:
  18
  19 @itemize
  20 @item Single binary, responsible for both blog and phlog
  21 @item @url{https://git-scm.com/, Git} DVCS as a storage for posts and comments
  22 @item Single small @url{https://hjson.github.io/, Hjson} configuration file
  23 @item Uses @url{https://en.wikipedia.org/wiki/Common_Gateway_Interface, CGI}
  24     interface (simplicity, remember?) for dealing with HTTP-server
  25 @item Uses @url{https://en.wikipedia.org/wiki/Inetd, inetd} interface
  26     for working as @url{https://en.wikipedia.org/wiki/Gopher_(protocol), Gopher}
  27     server
  28 @item Topics (tags/categories) support
  29 @item Supports on the fly generation of
  30     @url{https://en.wikipedia.org/wiki/Atom_(feed), Atom} feeds
  31     for posts, comments and per-post comments
  32 @item Single binary for email-backed comments posting
  33 @item If access is granted, then everyone can easily create an offline
  34     copy of your blog/phlog!
  35 @end itemize
  36
  37 All of that, except for comments, topics and phlog, could be achieved
  38 with some Git viewer like @url{https://git.zx2c4.com/cgit/about/, cgit}.
  39 But SGBlog also is able to:
  40
  41 @itemize
  42 @item Convert URLs to clickable links
  43 @item Convert SHA1-like hashes to blog links itself
  44 @item Include relative @code{<link rel>} links for ease of navigation in
  45     some browsers
  46 @item @url{https://en.wikipedia.org/wiki/Gzip, gzip} compress both HTML
  47     pages and Atom feeds
  48 @item Respect @url{https://en.wikipedia.org/wiki/HTTP_ETag, ETag}
  49     caching for both of them above
  50 @end itemize
  51
  52 @url{http://blog.stargrave.org/example/, Here} is an example blog.
  53
  54 SGBlog is free software, licenced under
  55 @url{https://www.gnu.org/licenses/agpl-3.0.html, GNU AGPLv3}:
  56 see the file COPYING for copying conditions.
  57
  58 @menu
  59 * Comments::
  60 * Topics::
  61 * Installation::
  62 * Configuration::
  63 @end menu
  64
  65 @node Comments
  66 @unnumbered Comments
  67
  68 Comments are posted through the email interface, just by sending the
  69 message to special address. For example:
  70
  71 @example
  72 $ mutt "mailto:comment@@blog.example.com?subject=576540a5b98517b46d0efc791bb90b9121bf147e" <<EOF
  73 This is the comments contents.
  74 Could be multilined of course.
  75 EOF
  76 @end example
  77
  78 Comments are stored in Git as a @url{https://git-scm.com/docs/git-notes, note}.
  79 Those objects could be updated without touching the base commit itself.
  80
  81 Each comment is just a plaintext with @code{From} and @code{Date}
  82 headers. @code{From} is a name of email sender (with email address
  83 stripped off).
  84
  85 Technically comments are stored in concatenated
  86 @url{https://en.wikipedia.org/wiki/Netstring, netstring}. Only
  87 @code{text/plain} or @code{multipart/signed+text/plain} email messages
  88 are accepted and only with UTF-8, US-ASCII, ISO-8859-1 character sets.
  89 Sane people won't send HTML email anyway, but this is just a precaution.
  90
  91 @node Topics
  92 @unnumbered Topics
  93
  94 Each post can have any number of attached topics (also known as tags or
  95 categories). They are whitespace separated single words kept in separate
  96 @url{https://git-scm.com/docs/git-notes, note} namespace. You can
  97 add/change comments with commands like:
  98
  99 @example
 100 $ git notes --ref=topics add -m "linux hate" @@
 101 @end example
 102
 103 @node Installation
 104 @unnumbered Installation
 105
 106 SGBlog's is written on Go and uses its modules. Hopefully you can
 107 install it just by running:
 108
 109 @example
 110 $ go get go.stargrave.org/sgblog/cmd/sgblog
 111 $ go get go.stargrave.org/sgblog/cmd/sgblog-comment-add # if you need commenting
 112 @end example
 113
 114 Unfortunately by default it uses HTTPS and Go's third party servers
 115 (@code{sum.golang.org}, @code{proxy.golang.org}) that trust neither
 116 @code{CACert.org}'s CA (used previously) nor @code{ca.cypherpunks.ru}
 117 CA. So either disable their usage and trust that certificate:
 118 @code{GOPRIVATE=go.stargrave.org/sgblog}, or clone its source code
 119 manually and build in place:
 120 @url{git://git.stargrave.org/sgblog.git},
 121 @url{https://git.stargrave.org/git/sgblog.git}.
 122
 123 For enabling blog availability you have to use HTTP server with CGI
 124 interface. Example part of @url{http://www.lighttpd.net/, lighttpd}'s
 125 configuration:
 126
 127 @example
 128 $HTTP["host"] == "blog.example.com" @{
 129   server.document-root = www_dir + "/blog.example.com"
 130   $HTTP["url"] =~ "^/example" @{
 131     alias.url += ("/example" => "/path/to/sgblog")
 132     cgi.assign = ("sgblog" => "/path/to/sgblog")
 133     setenv.add-environment = (
 134       "SGBLOG_CFG" => "/path/to/example.hjson",
 135     )
 136   @}
 137 @}
 138 @end example
 139
 140 And be sure that you have read access to the Git repository, for example
 141 by placing @code{lighttpd} user into @code{git} group.
 142
 143 Example @command{inetd} configuration (for phlog):
 144
 145 @example
 146 gopher stream tcp  nowait lighttpd /path/to/sgblog sgblog -gopher /path/to/gopher.hjson
 147 gopher stream tcp6 nowait lighttpd /path/to/sgblog sgblog -gopher /path/to/gopher.hjson
 148 @end example
 149
 150 For comments workability you have to configure your SMTP server to feed
 151 incoming messages to @command{sgblog-comment-add} utility. For example,
 152 Postfix'es @file{/etc/aliases} can contain:
 153
 154 @example
 155 comment: "| /path/to/sgblog-comment-add -git-dir /path/to/blog.git -committer-email comment@@blog.example.com"
 156 @end example
 157
 158 to run that utility for all @code{comment@@} address messages.
 159 You must have enough permission to be able to write to Git repository,
 160 but Postfix by default runs all that commands from a @code{nobody} user.
 161 So possibly you will need to @code{setuid} that executable give
 162 permission for @code{nobody} running:
 163
 164 @example
 165 -rwsr-x--- git:nobody sgblog-comment-add
 166 @end example
 167
 168 And also do not forget about @code{lighttpd} user's (possibly in
 169 @code{git} group) read permission permissions. Make sure
 170 @command{sgblog-comment-add} runs with correctly set @code{-umask} (027
 171 by default) for newly created Git objects/files.
 172
 173 @node Configuration
 174 @unnumbered Configuration
 175
 176 SGBlog is configured via Hjson configuration file. More or less
 177 self-describing blog configuration looks like that and contains many
 178 optional fields:
 179
 180 @example
 181 @{
 182   GitPath: /home/sgblog/blog.git
 183   Branch: refs/heads/example
 184   Title: "Example blog"
 185
 186   BaseURL: http://blog.example.com
 187   URLPrefix: /example
 188
 189   AtomId: "urn:uuid:54e6e53f-c615-48f1-812c-6f6b094ebbdd"
 190   AtomAuthor: John Doe
 191
 192   # URL to CSS file, optional
 193   CSS: /style.css
 194   # Email address of the webmaster, optional
 195   Webmaster: "webmaster@@example.com"
 196   # URL to about page, optional
 197   AboutURL: /
 198   # Optional list of optional Git URLs for corresponding <link rel="vcs-git">
 199   GitURLs: [
 200     git://git.example.com/blog.git
 201     https://git.example.com/git/blog.git
 202   ]
 203
 204   # If that ref is set, then comments will be loaded from it
 205   CommentsNotesRef: refs/notes/comments
 206   # Display link for comment writing, if email is set
 207   CommentsEmail: something@@example.com
 208
 209   # If that ref is set, then topics will be loaded from it
 210   TopicsNotesRef: refs/notes/topics
 211   # Optional file for topics state caching
 212   TopicsCachePath: /path/to/sgblog-topics-cache.gob
 213 @}
 214 @end example
 215
 216 Gopher configuration can use the same file, but it requires much less
 217 options:
 218
 219 @example
 220 @{
 221   GitPath: /home/sgblog/blog.git
 222   Branch: refs/heads/example
 223   Title: "Example blog"
 224
 225   GopherDomain: phlog.example.com
 226
 227   AboutURL: http://blog.example.com/
 228
 229   # Both are optional
 230   CommentsNotesRef: refs/notes/comments
 231   CommentsEmail: something@@example.com
 232
 233   # Both are optional too
 234   TopicsNotesRef: refs/notes/topics
 235   TopicsCachePath: /path/to/sgblog-topics-cache.gob
 236 @}
 237 @end example
 238
 239 @bye