From a7aca5fab21f92533036486fc96fb30ee2205dfa Mon Sep 17 00:00:00 2001 From: simon Date: Tue, 12 Sep 2017 12:26:34 +0100 Subject: [PATCH] Documentation of new configuration. --- resources/config.edn | 12 ++++-- resources/public/content/Configuration.md | 37 +++++++++++++------ resources/public/content/Deploying Smeagol.md | 14 +++++-- resources/public/content/Docker Image.md | 2 +- .../public/content/Environment Variables.md | 11 ++++++ src/smeagol/authenticate.clj | 3 +- src/smeagol/configuration.clj | 5 ++- src/smeagol/handler.clj | 5 +-- src/smeagol/util.clj | 2 +- 9 files changed, 65 insertions(+), 26 deletions(-) create mode 100644 resources/public/content/Environment Variables.md diff --git a/resources/config.edn b/resources/config.edn index 27c6a8b..0b86bc2 100644 --- a/resources/config.edn +++ b/resources/config.edn @@ -26,9 +26,15 @@ ;; ; ; ; ; ; ; ; ; ; { - :site-title "Smeagol" ;; overall title of the site, used in page headings - :default-locale "en-GB" ;; default language used for messages - :formatters {"vega" smeagol.formatting/process-vega + :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 "backticks" smeagol.formatting/process-backticks} diff --git a/resources/public/content/Configuration.md b/resources/public/content/Configuration.md index fd29caf..4e5d987 100644 --- a/resources/public/content/Configuration.md +++ b/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 - :formatters {"vega" smeagol.formatting/process-vega - "vis" smeagol.formatting/process-vega - "mermaid" smeagol.formatting/process-mermaid - "backticks" smeagol.formatting/process-backticks} - } +``` +{ + :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 -* **: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. +* `: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. +* `: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]]. diff --git a/resources/public/content/Deploying Smeagol.md b/resources/public/content/Deploying Smeagol.md index 009d610..65c8eae 100644 --- a/resources/public/content/Deploying Smeagol.md +++ b/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; -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_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. +### Custom configuration file +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. +### 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; diff --git a/resources/public/content/Docker Image.md b/resources/public/content/Docker Image.md index 4bfc58f..c4e4b9a 100644 --- a/resources/public/content/Docker Image.md +++ b/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: ``` diff --git a/resources/public/content/Environment Variables.md b/resources/public/content/Environment Variables.md new file mode 100644 index 0000000..cca8a0b --- /dev/null +++ b/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. diff --git a/src/smeagol/authenticate.clj b/src/smeagol/authenticate.clj index c65b5ad..e4219e9 100644 --- a/src/smeagol/authenticate.clj +++ b/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"))) diff --git a/src/smeagol/configuration.clj b/src/smeagol/configuration.clj index 7b14ed6..9c67d91 100644 --- a/src/smeagol/configuration.clj +++ b/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 diff --git a/src/smeagol/handler.clj b/src/smeagol/handler.clj index dfcf187..d25e415 100644 --- a/src/smeagol/handler.clj +++ b/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)) - (let [level (read-string (env :log-level))] - (if (string? level) (lower-case (keyword level)))) + (:log-level config) (if (env :dev) :debug) :info)}) (cronj/start! session-manager/cleanup-job) diff --git a/src/smeagol/util.clj b/src/smeagol/util.clj index 902e377..015a5db 100644 --- a/src/smeagol/util.clj +++ b/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")))