rklotz

README

rKlotz

Yet another simple single-user file-based golang-driven blog engine

Run locally

You need to have Docker installed and running.

docker run --rm -it -p 8080:8080 vgarvardt/rklotz

Then open http://127.0.0.1:8080 in your browser.

Build and run locally

You need to have Go 1.12+ and Docker installed and running.

git clone git@github.com:vgarvardt/rklotz.git
cd rklotz
make deps
make build
docker run -it -p 8080:8080 vgarvardt/rklotz:`cat ./VERSION` server

Then open http://127.0.0.1:8080 in your browser.

Build your own blog based on rKlotz

See github.com/vgarvardt/itskrig.com for example on how to build your blog using rKlotz as base image.

Posts

Posts in rKlotz are just files written in some markup language. Currently only Markdown (md extension) is supported.

Post file has the following structure:

• Line 1: Post title
• Line 2: Post publishing date - posts are ordered by publishing date in reverse chronological order. Date must be in RFC822Z format
• Line 3: Post tags - comma-separated tags list
• Line 4: Reserved for further usage
• Line 5: Post delimiter - +++ for Markdown, not necessary that line number, may be preceded by any number of lines before delimiter
• Line 6: Post body - may be preceded by any number of lines before post body, after delimiter

Post teaser will be extracted from the post body automatically to be displayed on the posts list pages. If you want to set post teaser explicitly - use +++teaser delimiter.

Post path is determined automatically from its path, relative to posts root path (see settings).

Posts examples are available in asserts/posts.

Settings

Currently, the following settings (environment variables) are available:

Base application settings

• POSTS_DSN (default file:///etc/rklotz/posts) - posts root path in the format storage://<path>. Currently, the following storage types are supported:
  • file - local file system
• POSTS_PERPAGE (default 10) - number of posts per page
• STORAGE_DSN (default boltdb:///tmp/rklotz.db) - posts storage in runtime in the format storage://path. Currently, the following storage types are supported:
  • boltdb - storage on top of BoltDB and Storm
  • memory - store all posts in memory, perfect for hundreds or even thousands of posts

Logger settings

• LOG_LEVEL (default info) - logging level
• LOG_TYPE (default rklotz) - logging type (type field in the log message)

Web application settings

• WEB_PORT (default 8080) - port to run the http server
• WEB_STATIC_PATH (default /etc/rklotz/static) - static files root path
• WEB_TEMPLATES_PATH (default /etc/rklotz/templates) - templates root path

SSL settings

rKlotz supports SSL with Let's Encrypt.

• SSL_ENABLED (default false) - enables SSL/TLS
• SSL_PORT (default 8443) - SSL port
• SSL_HOST - host to validate for SSL
• SSL_EMAIL (default vgarvardt@gmail.com) - email to register for SSL
• SSL_CACHE_DIR (default /tmp) - directory to cache retrieved certificate

HTML and UI settings

• UI_THEME (default foundation6) - theme name. Themes list available in templates (except for plugins, that are plugins templates, see below)
• UI_AUTHOR (default Vladimir Garvardt) - blog author name (HTML head meta)
• UI_EMAIL (default vgarvardt@gmail.com) - blog author email
• UI_DESCRIPTION (default rKlotz - simple golang-driven blog engine) - blog description (HTML head meta)
• UI_LANGUAGE (default en) - blog language (HTML lang)
• UI_TITLE (default rKlotz) - blog title (HTML title)
• UI_HEADING (default rKlotz) - blog heading (index page header)
• UI_INTRO (default simple golang-driven blog engine) - blog intro (index page header)
• UI_DATEFORMAT (default 2 Jan 2006) - post publishing date display format. Must be compatible with time.Format(). See examples in predefined time formats.
• UI_ABOUT_PATH (default /etc/rklotz/about.tpl) - path to custom "about panel". If not found - <WEB_TEMPLATES_PATH>/<UI_THEME>/partial/about.tpl is used.

About panel

Template must have the following structure:

{{ define "partial/about.tpl" }}
    Content goes here. html/template is used for rendering.
{{ end }}

See about panel example in default theme.

Root URL settings

• ROOT_URL_SCHEME (default http) - blog absolute URL scheme. Currently https si not supported on rKlotz web application level (in plans), so use https only if you have SSL/TLS certificate termination on the level before rKlotz (e.g. nginx as reverse proxy before your blog).
• ROOT_URL_HOST (default ``) - blog absolute URL host. If empty - request host is used.
• ROOT_URL_PATH (default /) - blog absolute URL path prefix. In case your blog is hosted on the second (or deeper) path level, e.g. http://example.com/blog (ROOT_URL_PATH=/blog)

Plugins settings

Plugins

rKlots supports plugins. Currently, the following are implemented:

• Disqus (disqus) - posts comments
• Google Analytics (ga) - site visits analytics from Google
• Google Tag Manager (gtm) - tag management analytics from Google
• highlight.js (highlightjs) - posts code highlighting
• Yandex Metrika (yamka) - site visits analytics from Yandex
• Yandex Share (yasha) - share post buttons from Yandex

Plugins configuration available with the following settings:

• PLUGINS_ENABLED - comma-separated plugins list, e.g. disqus,ga,highlightjs to enable Disqus, Google Analytics and highlight.js plugins
• PLUGINS_DISQUS - Disqus plugin configuration in the format <config1>:<value1>,<config2>:<value2>,... The following configurations are available:
  • shortname (required) - account short name
• PLUGINS_GA - Google Analytics plugin configuration in the format <config1>:<value1>,<config2>:<value2>,... The following configurations are available:
  • tracking_id (required) - analytics tracking ID
• PLUGINS_GTM - Google Tag Manager plugin configuration in the format <config1>:<value1>,<config2>:<value2>,... The following configurations are available:
  • id (required) - tag manager ID
• PLUGINS_HIGHLIGHTJS - highlight.js plugin configuration in the format <config1>:<value1>,<config2>:<value2>,... The following configurations are available:
  • version (default 9.7.0) - library version
  • theme (default idea) - colour scheme/theme
• PLUGINS_YAMKA - Yandex Metrika plugin configuration in the format <config1>:<value1>,<config2>:<value2>,... The following configurations are available:
  • id (required) - metrika ID
• PLUGINS_YASHA - Yandex Share plugin configuration in the format <config1>:<value1>,<config2>:<value2>,... The following configurations are available (see fill list of values on plugin page):
  • services (default: facebook twitter gplus) - space-separated services list
  • size (default: m) - icons size: m - medium, s - small
  • lang (default en) - widget language, see docs page for complete list of available languages

TODO

• Dockerize deployment
• Get config values from os env
• Implement at least one more theme
• Write some tests
• Cover reindex logic with tests
• Migrate to another Web Framework (maybe echo)
• Get version from VERSION file (gb does not seem to inject ldflag into packages other than main)
• SemVer versioning
• SSL/TLS with Let's Encrypt
• Implement badger storage
• Implement memory storage
• Implement git loader