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