2 @documentencoding UTF-8
6 Copyright @copyright{} 2020 @email{stargrave@@stargrave.org, Sergey Matveev}
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}.
17 Its main competitive features:
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
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!
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:
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
47 @item @url{https://en.wikipedia.org/wiki/Gzip, gzip} compress both HTML
49 @item Respect @url{https://en.wikipedia.org/wiki/HTTP_ETag, ETag}
50 caching for both of them above
53 @url{http://blog.stargrave.org/example/, Here} is an example blog.
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.
62 Comments are posted through the email interface, just by sending the
63 message to special address. For example:
66 $ mutt "mailto:comment@@blog.example.com?subject=BlaBlaBla%20(576540a5b98517b46d0efc791bb90b9121bf147e)" <<EOF
67 This is the comments contents.
68 Could be multilined of course.
72 Comments are stored in Git as a @url{https://git-scm.com/docs/git-notes, note}.
73 Those objects could be updated without touching the base commit itself.
75 Each comment is just a plaintext with @code{From} and @code{Date}
76 headers. @code{From} is a name of email sender (with email address
79 Only @code{text/plain} or @code{multipart/signed+text/plain} email
80 messages are accepted and only with UTF-8, US-ASCII, ISO-8859-1
81 character sets. Sane people won't send HTML email anyway, but this is
84 Comments are stored in @dfn{recfiles} --
85 @url{https://www.gnu.org/software/recutils/, GNU recutils}
86 human-editable plaintext database format. But they do not contain
91 %doc: SGBlog's comment
92 %mandatory: From Date Body
99 Each post can have any number of attached topics (also known as tags or
100 categories). They are whitespace separated single words kept in separate
101 @url{https://git-scm.com/docs/git-notes, note} namespace. You can
102 add/change comments with commands like:
105 $ git notes --ref=topics add -m "linux hate" @@
106 $ git push origin mybranch refs/notes/topics
109 To reset incorrectly added topic:
112 $ git update-ref refs/notes/topics refs/notes/topics^
116 @unnumbered Installation
118 SGBlog's is written on Go and uses its modules. Hopefully you can
119 install it just by running:
122 $ go get go.stargrave.org/sgblog/cmd/sgblog
123 $ go get go.stargrave.org/sgblog/cmd/sgblog-comment-add # if you need commenting
126 Unfortunately by default it uses HTTPS and Go's third party servers
127 (@code{sum.golang.org}, @code{proxy.golang.org}) that trust neither
128 @code{CACert.org}'s CA (used previously) nor @code{ca.cypherpunks.ru}
129 CAs. So either disable their usage and trust that certificate:
130 @code{GOPRIVATE=go.stargrave.org/sgblog}, or clone its source code
131 manually and build in place:
132 @url{git://git.stargrave.org/sgblog.git},
133 @url{https://git.stargrave.org/sgblog.git}.
135 For enabling blog availability you have to use HTTP server with CGI
136 interface. Example part of @url{http://www.lighttpd.net/, lighttpd}'s
140 $HTTP["host"] == "blog.example.com" @{
141 server.document-root = www_dir + "/blog.example.com"
142 $HTTP["url"] =~ "^/example" @{
143 alias.url += ("/example" => "/path/to/sgblog")
144 cgi.assign = ("sgblog" => "/path/to/sgblog")
145 setenv.add-environment = (
146 "SGBLOG_CFG" => "/path/to/example.hjson",
152 And be sure that you have read access to the Git repository, for example
153 by placing @code{lighttpd} user into @code{git} group.
155 Example @command{inetd} configuration (for phlog):
158 gopher stream tcp6 nowait lighttpd /path/to/sgblog sgblog -gopher /path/to/gopher.hjson
161 Example @command{UCSPI-TCP} service running under
162 @url{http://cr.yp.to/daemontools.html, daemontools}:
165 # mkdir -p /var/service/.phlog-ipv6/log
166 # cd /var/service/.phlog-ipv6
170 uid=\`id -u lighttpd\`
173 exec tcpserver -DHR -u $uid -g $gid -l 0 $addr gopher \
174 sgblog -gopher /path/to/gopher.hjson
177 # cat > log/run <<EOF
179 exec setuidgid whatever-user multilog t ./main
182 # chmod -R 755 /var/service/.phlog-ipv6
183 # mv /var/service/.phlog-ipv6 /var/service/phlog-ipv6
186 For comments workability you have to configure your SMTP server to feed
187 incoming messages to @command{sgblog-comment-add} utility. For example,
188 Postfix'es @file{/etc/aliases} can contain:
191 comment: "| /path/to/sgblog-comment-add -git-dir /path/to/blog.git -committer-email comment@@blog.example.com"
194 to run that utility for all @code{comment@@} address messages.
195 You must have enough permission to be able to write to Git repository,
196 but Postfix by default runs all that commands from a @code{nobody} user.
197 So possibly you will need to @code{setuid} that executable give
198 permission for @code{nobody} running:
201 -rwsr-x--- git:nobody sgblog-comment-add
204 And also do not forget about @code{lighttpd} user's (possibly in
205 @code{git} group) read permission permissions. Make sure
206 @command{sgblog-comment-add} runs with correctly set @code{-umask} (027
207 by default) for newly created Git objects/files.
210 @unnumbered Configuration
212 SGBlog is configured via Hjson configuration file. More or less
213 self-describing blog configuration looks like that and contains many
218 GitPath: /home/sgblog/blog.git
219 Branch: refs/heads/example
220 Title: "Example blog"
222 BaseURL: http://blog.example.com
225 AtomId: "urn:uuid:54e6e53f-c615-48f1-812c-6f6b094ebbdd"
228 # URL to CSS file, optional
230 # Email address of the webmaster, optional
231 Webmaster: "webmaster@@example.com"
232 # URL to about page, optional
234 # Optional list of optional Git URLs for corresponding <link rel="vcs-git">
236 git://git.example.com/blog.git
237 https://git.example.com/git/blog.git
240 # If that ref is set, then comments will be loaded from it
241 CommentsNotesRef: refs/notes/comments
242 # Display link for comment writing, if email is set
243 CommentsEmail: something@@example.com
245 # If that ref is set, then topics will be loaded from it
246 TopicsNotesRef: refs/notes/topics
247 # Optional file for topics state caching
248 TopicsCachePath: /path/to/sgblog-topics-cache.gob
252 Gopher configuration can use the same file, but it requires much less
257 GitPath: /home/sgblog/blog.git
258 Branch: refs/heads/example
259 Title: "Example blog"
261 GopherDomain: phlog.example.com
263 AboutURL: http://blog.example.com/
266 CommentsNotesRef: refs/notes/comments
267 CommentsEmail: something@@example.com
269 # Both are optional too
270 TopicsNotesRef: refs/notes/topics
271 TopicsCachePath: /path/to/sgblog-topics-cache.gob