Documentation of new configuration.

resources/config.edn

@@ -28,6 +28,12 @@
 {
   :site-title           "Smeagol"       ;; overall title of the site, used in page headings
   :default-locale       "en-GB"         ;; default language used for messages
+;;  :content-dir          "/home/simon/tmp/test-content"
+                                        ;; where content is served from
+  :passwd               "/home/simon/tmp/passwd"
+                                        ;; where the password file is stored
+  :log-level            :info           ;; the minimum logging level; one of
+                                        ;; TRACE DEBUG INFO WARN ERROR FATAL
   :formatters           {"vega"         smeagol.formatting/process-vega
                          "vis"          smeagol.formatting/process-vega
                          "mermaid"      smeagol.formatting/process-mermaid

resources/public/content/Configuration.md

@@ -2,19 +2,32 @@ Smeagol reads a configuration file, whose content should be formatted as a cloju
 
 The default content is as follows:
 
-    {
+```
+{
   :site-title           "Smeagol"       ;; overall title of the site, used in page headings
   :default-locale       "en-GB"         ;; default language used for messages
+  :content-dir          "/usr/local/etc/content"
+                                        ;; where content is served from
+  :passwd               "/usr/local/etc/passwd"
+                                        ;; where the password file is stored
+  :log-level            :info           ;; the minimum logging level; one of
+                                        ;; :trace :debug :info :warn :error :fatal
   :formatters           {"vega"         smeagol.formatting/process-vega
                          "vis"          smeagol.formatting/process-vega
                          "mermaid"      smeagol.formatting/process-mermaid
                          "backticks"    smeagol.formatting/process-backticks}
-    }
+}
+```
 
-The three keys given above should be present. The values should be:
+The values should be:
 
-* **:site-title** The title for your wiki
+* `:content-dir` The directory in which your editable content is stored;
-* **:default-locale** A string comprising a lower-case [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code specifying a language, optionally followed by a hyphen and an upper-case [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166) specifying a country.
+* `:default-locale` A string comprising a lower-case [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code specifying a language, optionally followed by a hyphen and an upper-case [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166) specifying a country.
-* **:formatters** A map of formatters used in [[Extensible Markup]], q.v.
+* `:formatters` A map of formatters used in [[Extensible Markup]], q.v.
+* `:log-level` The minimum level of log messages to be logged; one of `:trace :debug :info :warn :error :fatal`
+* `:passwd` The path to your `passwd` file - see [[Security and authentication]];
+* `:site-title` The title for your wiki.
 
 The default file is at `resources/config.edn`; this default can be overridden by providing an environment variable, `SMEAGOL_CONFIG`, whose value is the full or relative pathname of a suitable file.
+
+Note that all the values in the configuration can be overridden with [[Environment Variables]].

resources/public/content/Deploying Smeagol.md

@@ -6,12 +6,18 @@ To deploy Smeagol as a stand-alone application, either download the jar file for
 
 This will create a jar file in the `target` directory, named `smeagol-`*VERSION*`-standalone.jar`.
 
-Smeagol cannot access either its configuration or its content from the jar file, as otherwise they would not be editable. Consequently you should set up three environment variables:
+Smeagol cannot access either its configuration or its content from the jar file, as otherwise they would not be editable. There are three solutions to this:
 
-1. `SMEAGOL_CONFIG` should be the full or relative pathname of a Smeagol [[Configuration]] file;
+### Custom configuration file
-2. `SMEAGOL_CONTENT_DIR` should be the full or relative pathname of the directory from which Smeagol should serve content (which may initially be empty, but must be writable by the process which runs Smeagol)'
+You can copy the standard [[Configuration]] file `resources/config.edn` to somewhere outside the jar file, edit it to suit your installation, and set up a single environment variable, `SMEAGOL_CONFIG`, whose value is the path to your new configuration file.
-3. `SMEAGOL_PASSWD` should be the full or relative pathname of a Smeagol Passwd file - see [[Security and authentication]]. This file must contain an entry for at least your initial user, and, if you want to administer users through the user interface, must be writable by the process which runs Smeagol.
 
+### Environment variables
+Alternatively, you can configure everything through [[Environment Variables]].
+
+### Hybrid strategy
+You can have both a configuration file and environment variables. If you do this, the environment variables override the values in the configuration file.
+
+### Necessary content
 **NOTE** that `SMEAGOL_CONTENT_DIR` must contain at least the following files:
 
 1. `_edit-side-bar.md` - the side-bar that should be displayed when editing pages;

resources/public/content/Docker Image.md

@@ -8,7 +8,7 @@ Where 127.0.0.1 is the IP address through which you want to forward port 80 (in
 
 You can then browse to Smeagol by pointing your browser at http://localhost/.
 
-As of version 0.99.10, the Docker image is now based on the Jetty, rather than the Tomcat, deployment of Smeagol (that is to say, it runs the executable jar file). This makes for a lighter weight Docker image, but there are still some problems which need to be addressed.
+As of version 0.99.10, the Docker image is now based on the Jetty, rather than the Tomcat, deployment of Smeagol (that is to say, it runs the executable jar file). This makes for a lighter weight Docker image. All configuration can be overridden with [[Environment Variables]], which can be passed into the Docker container when the image is invoked, or from a [[Configuration]] file.
 
 The `config.edn` and `passwd` files and the `content` directory are copied into `/usr/local/etc` in the Docker image, and the appropriate environment variables are set up to point to them:
 ```

resources/public/content/Environment Variables.md

@@ -0,0 +1,11 @@
+Smeagol can be configured entirely with environment variables. The variables are:
+
+1. `SMEAGOL_CONFIG` (optional but advised) should be the full or relative pathname of a Smeagol [[Configuration]] file;
+2. `SMEAGOL_CONTENT_DIR` should be the full or relative pathname of the directory from which Smeagol should serve content (which may initially be empty, but must be writable by the process which runs Smeagol);
+3. `SMEAGOL_DEFAULT_LOCALE` which should be a locale specification in the form "en-GB", "fr-FR", or whatever to suit your users;
+4. `SMEAGOL_FORMATTERS` should be an [edn](https://github.com/edn-format/edn)-formatted map of formatter directives (this would be pretty hard to do from an environment variable);
+5. `SMEAGOL_LOG_LEVEL` which should be one of `TRACE DEBUG INFO WARN ERROR FATAL`
+6. `SMEAGOL_PASSWD` should be the full or relative pathname of a Smeagol Passwd file - see [[Security and authentication]]. This file must contain an entry for at least your initial user, and, if you want to administer users through the user interface, must be writable by the process which runs Smeagol.
+7. `SMEAGOL_SITE_TITLE` which should be the title you want shown on the header of all pages.
+
+You can have both a configuration file and environment variables; if you do, the values of the environment variables take precedence over the values in the config file.

src/smeagol/authenticate.clj

@@ -4,6 +4,7 @@
   (:require [crypto.password.scrypt :as password]
             [environ.core :refer [env]]
             [noir.io :as io]
+            [smeagol.configuration :refer [config]]
             [taoensso.timbre :as timbre]))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -37,7 +38,7 @@
 ;; the relative path to the password file.
 (def password-file-path
   (or
-    (env :smeagol-passwd)
+    (:passwd config)
     (str (io/resource-path) "../passwd")))
 
 

src/smeagol/configuration.clj

@@ -80,7 +80,10 @@
   used internally"
   '( {:from :smeagol-site-title :to :site-title}
      {:from :smeagol-default-locale :to :default-locale}
-     {:from :smeagol-formatters :to :formatters :transform read-string}))
+     {:from :smeagol-formatters :to :formatters :transform read-string}
+     {:from :smeagol-content-dir :to :content-dir}
+     {:from :smeagol-passwd :to :passwd}
+     {:from :smeagol-log-level :to :log-level :transform (fn [s] (keyword (lower-case s)))}))
 
 
 (def config

src/smeagol/handler.clj

@@ -12,6 +12,7 @@
             [noir.util.middleware :refer [app-handler]]
             [ring.middleware.defaults :refer [site-defaults]]
             [selmer.parser :as parser]
+            [smeagol.configuration :refer [config]]
             [smeagol.routes.wiki :refer [wiki-routes]]
             [smeagol.middleware :refer [load-middleware]]
             [smeagol.session-manager :as session-manager]
@@ -73,9 +74,7 @@
                   :max-size (* 512 1024)
                   :backlog 10})}
        :level (or
-                (read-string (env :timbre-level))
+                (:log-level config)
-                (let [level (read-string (env :log-level))]
-                  (if (string? level) (lower-case (keyword level))))
                 (if (env :dev) :debug)
                 :info)})
     (cronj/start! session-manager/cleanup-job)

src/smeagol/util.clj

@@ -37,7 +37,7 @@
 
 (def content-dir
   (or
-    (env :smeagol-content-dir)
+    (:content-dir config)
     (cjio/file (io/resource-path) "content")))