From f83b0cdb757a547730a2f06f086c9b9c6cb4d08d Mon Sep 17 00:00:00 2001 From: simon Date: Fri, 18 Aug 2017 13:08:23 +0100 Subject: [PATCH] Working towards serving content from outside the jar --- .../public/content/Developing Smeagol.md | 23 ++++++- resources/public/contentDeveloping Smeagol.md | 55 ++++++++++++++++ src/smeagol/configuration.clj | 7 +- src/smeagol/formatting.clj | 4 +- src/smeagol/history.clj | 21 +++++- src/smeagol/routes/wiki.clj | 66 ++++++++++--------- src/smeagol/util.clj | 6 +- 7 files changed, 139 insertions(+), 43 deletions(-) create mode 100644 resources/public/contentDeveloping Smeagol.md diff --git a/resources/public/content/Developing Smeagol.md b/resources/public/content/Developing Smeagol.md index 665383c..4da9875 100644 --- a/resources/public/content/Developing Smeagol.md +++ b/resources/public/content/Developing Smeagol.md @@ -5,18 +5,35 @@ You will need [Leiningen](https://github.com/technomancy/leiningen) 2.0 or above You will need [node](https://nodejs.org/en/) and [bower](https://bower.io/) installed. ## Running - -To start a web server for the application, run: +### In development +To start a web server for the application during development, run: lein bower install lein ring server + +### In production +To deploy Smeagol as a stand-alone application, compile it with: + + lein bower install + lein uberjar + +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. Consequently you should set up two environment variables: + +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)' + +You can run the jar file with: + + java -jar smeagol-VERSION-standalone.jar Alternatively, if you want to deploy to a servlet container (which I would strongly recommend), the simplest thing is to run: lein bower install lein ring uberwar -(a command which I'm sure Smeagol would entirely appreciate) and deploy the resulting war file. +(a command which I'm sure Smeagol would entirely appreciate) and deploy the resulting war file. **NOTE** that if your Servlet container is configured to unpack war files you do not need to supply the environment variables specified above, but if it does not you must do so. ## Experimental Docker image diff --git a/resources/public/contentDeveloping Smeagol.md b/resources/public/contentDeveloping Smeagol.md new file mode 100644 index 0000000..52b3c58 --- /dev/null +++ b/resources/public/contentDeveloping Smeagol.md @@ -0,0 +1,55 @@ +## Prerequisites + +You will need [Leiningen](https://github.com/technomancy/leiningen) 2.0 or above installed. + +You will need [node](https://nodejs.org/en/) and [bower](https://bower.io/) installed. + +## Running + +To start a web server for the application during development, run: + + lein bower install + lein ring server + +To deploy Smeagol as a stand-alone application, compile it with: + + lein bower install + lein uberjar + +This will create a jar file in the `target` directory, named `smeagol-`*VERSION*`-standalone.jar`. You can run this file with: + + java -jar smeagol-VERSION-standalone.jar + +Test modification? + +Alternatively, if you want to deploy to a servlet container (which I would strongly recommend), the simplest thing is to run: + + lein bower install + lein ring uberwar + +(a command which I'm sure Smeagol would entirely appreciate) and deploy the resulting war file. + +## Experimental Docker image + +You can now run Smeagol as a [Docker](http://www.docker.com) image. Read more about [[Using the Docker Image]]. + +To run my Docker image, use + + docker run simonbrooke/smeagol + +Smeagol will run, obviously, on the IP address of your Docker image, on port 8080. To find the IP address, start the image using the command above and then use + + docker inspect --format '{{ .NetworkSettings.IPAddress }}' $(docker ps -q) + +Suppose this prints '10.10.10.10', then the URL to browse to will be http://10.10.10.10:8080/smeagol/ + +This image is _experimental_, but it does seem to work fairly well. What it does **not** yet do, however, is push the git repository to a remote location, so when you tear the Docker image down your edits will be lost. My next objective for this image is for it to have a cammand line parameter being the git address of a repository from which it can initialise the Wiki content, and to which it will periodically push local changes to the Wiki content. + +To build your own Docker image, run: + + lein clean + lein bower install + lein ring uberwar + lein docker build + +This will build a new Docker image locally; you can, obviously, push it to your own Docker repository if you wish. diff --git a/src/smeagol/configuration.clj b/src/smeagol/configuration.clj index 1a17edc..32be1b4 100644 --- a/src/smeagol/configuration.clj +++ b/src/smeagol/configuration.clj @@ -1,7 +1,8 @@ (ns ^{:doc "Read and make available configuration." :author "Simon Brooke"} smeagol.configuration - (:require [noir.io :as io])) + (:require [environ.core :refer [env]] + [noir.io :as io])) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;;; @@ -38,7 +39,9 @@ (def config-file-path "The relative path to the config file." - (str (io/resource-path) "../config.edn")) + (or + (env :smeagol-config) + (str (io/resource-path) "../config.edn"))) (def config diff --git a/src/smeagol/formatting.clj b/src/smeagol/formatting.clj index f15e681..8ddd6da 100644 --- a/src/smeagol/formatting.clj +++ b/src/smeagol/formatting.clj @@ -157,8 +157,8 @@ The map has two top-level keys: `:inclusions`, a map of constructed keywords to inclusion specifications, and `:text`, an HTML text string with the keywords present where the corresponding inclusion should be inserted." - ([text] - (process-text 0 {:inclusions {}} (cs/split text #"```") '())) + ([^String text] + (process-text 0 {:inclusions {}} (cs/split (or text "") #"```") '())) ([index result fragments processed] (let [fragment (first fragments) ;; if I didn't find a formatter for a back-tick marked fragment, diff --git a/src/smeagol/history.clj b/src/smeagol/history.clj index 66bad09..ae81fa8 100644 --- a/src/smeagol/history.clj +++ b/src/smeagol/history.clj @@ -49,11 +49,26 @@ log-entry)) +(defn load-or-init-repo + "There's a bootstrapping problem: when Smeagol first starts the repository + hasn't been initialised. Try to open the repository at this `git-directory-path`; + if an exception is thrown, try to init a repository at this `git-directory-path`, + and then open it and populate it." + [^String git-directory-path] + (try + (git/load-repo git-directory-path) + (catch java.io.FileNotFoundException fnf + (git/git-init git-directory-path) + (let [repo (git/load-repo git-directory-path)] + (git/git-add-and-commit repo "Initial commit") + repo)))) + + (defn find-history "Return the log entries in the repository at this `git-directory-path` which refer to changes to the file at this `file-path`." [^String git-directory-path ^String file-path] - (let [repository (git/load-repo git-directory-path)] + (let [repository (load-or-init-repo git-directory-path)] (filter #(entry-contains % file-path) (map #(q/commit-info repository %) @@ -88,7 +103,7 @@ (diff git-directory-path file-path version (:id (first (find-history git-directory-path file-path))))) ([^String git-directory-path ^String file-path ^String older ^String newer] - (let [git-r (git/load-repo git-directory-path) + (let [git-r (load-or-init-repo git-directory-path) old-parse (prepare-tree-parser git-r older) new-parse (prepare-tree-parser git-r newer) out (java.io.ByteArrayOutputStream.)] @@ -115,7 +130,7 @@ Based on JGit Cookbook ReadFileFromCommit." [^String git-directory-path ^String file-path ^String version] - (let [git-r (git/load-repo git-directory-path) + (let [git-r (load-or-init-repo git-directory-path) repo (.getRepository git-r) walk (i/new-rev-walk git-r) commit (i/bound-commit git-r walk (ObjectId/fromString version)) diff --git a/src/smeagol/routes/wiki.clj b/src/smeagol/routes/wiki.clj index e0859c5..614f515 100644 --- a/src/smeagol/routes/wiki.clj +++ b/src/smeagol/routes/wiki.clj @@ -7,6 +7,7 @@ [cemerick.url :refer (url url-encode url-decode)] [compojure.core :refer :all] [clj-jgit.porcelain :as git] + [environ.core :refer [env]] [noir.io :as io] [noir.response :as response] [noir.util.route :as route] @@ -44,13 +45,19 @@ ;;;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; + + +(def content-dir + (or + (env :smeagol-content-dir) + (cjio/file (io/resource-path) "content"))) + + + (defn get-git-repo "Get the git repository for my content, creating it if necessary" [] - (let [path (str (io/resource-path) "/content/") - repo (cjio/as-file (str path ".git"))] - (if (.exists repo) (git/load-repo repo) - (git/git-init path)))) + (hist/load-or-init-repo content-dir)) (defn process-source @@ -60,13 +67,13 @@ (let [source-text (:src params) page (:page params) file-name (str page suffix) - file-path (str (io/resource-path) "/content/" file-name) - exists? (.exists (clojure.java.io/as-file file-path)) + file-path (cjio/file content-dir file-name) + exists? (.exists (cjio/as-file file-path)) git-repo (get-git-repo) user (session/get :user) email (auth/get-email user) summary (format "%s: %s" user (or (:summary params) "no summary"))] - (timbre/info (format "Saving %s's changes ('%s') to %s" user summary page)) + (timbre/info (format "Saving %s's changes ('%s') to %s in file '%s'" user summary page file-path)) (spit file-path source-text) (git/git-add git-repo file-name) (git/git-commit git-repo summary {:name user :email email}) @@ -83,12 +90,13 @@ "Render a page in a text-area for editing. This could have been done in the same function as wiki-page, and that would have been neat, but I couldn't see how to establish security if that were done." ([request] - (edit-page request (util/get-message :default-page-title request) ".md" "edit.html" "/content/_edit-side-bar.md")) + (edit-page request (util/get-message :default-page-title request) ".md" "edit.html" "_edit-side-bar.md")) ([request default suffix template side-bar] (let [params (keywordize-keys (:params request)) src-text (:src params) page (or (:page params) default) - file-path (str (io/resource-path) "content/" page suffix) + file-name (str page suffix) + file-path (cjio/file content-dir file-name) exists? (.exists (cjio/as-file file-path)) user (session/get :user)] (if (not exists?) @@ -97,18 +105,18 @@ (cond src-text (process-source params suffix request) true (layout/render template - (merge (util/standard-params request) + (merge (util/standard-params request content-dir) {:title (str (util/get-message :edit-title-prefix request) " " page) :page page - :side-bar (md->html (io/slurp-resource side-bar)) - :content (if exists? (io/slurp-resource (str "/content/" page suffix)) "") + :side-bar (md->html (slurp (cjio/file content-dir side-bar))) + :content (if exists? (slurp file-path) "") :exists exists?})))))) (defn edit-css-page "Render a stylesheet in a text-area for editing.." [request] - (edit-page request "stylesheet" ".css" "edit-css.html" "/content/_edit-side-bar.md")) + (edit-page request "stylesheet" ".css" "edit-css.html" "_edit-side-bar.md")) (defn wiki-page @@ -116,17 +124,17 @@ [request] (let [params (keywordize-keys (:params request)) page (or (:page params) (util/get-message :default-page-title request)) - file-name (str "/content/" page ".md") - file-path (str (io/resource-path) file-name) + file-name (str page ".md") + file-path (cjio/file content-dir file-name) exists? (.exists (clojure.java.io/as-file file-path))] (cond exists? (do - (timbre/info (format "Showing page '%s'" page)) + (timbre/info (format "Showing page '%s' from file '%s'" page file-path)) (layout/render "wiki.html" - (merge (util/standard-params request) + (merge (util/standard-params request content-dir) {:title page :page page - :content (md->html (io/slurp-resource file-name)) + :content (md->html (slurp file-path)) :editable true}))) true (response/redirect (str "/edit?page=" page))))) @@ -138,10 +146,10 @@ (let [params (keywordize-keys (:params request)) page (url-decode (or (:page params) (util/get-message :default-page-title request))) file-name (str page ".md") - repo-path (str (io/resource-path) "/content/")] + repo-path content-dir] (timbre/info (format "Showing history of page '%s'" page)) (layout/render "history.html" - (merge (util/standard-params request) + (merge (util/standard-params request content-dir) {:title (str "History of " page) :page page :history (hist/find-history repo-path file-name)})))) @@ -154,7 +162,7 @@ upload (:upload params) uploaded (if upload (ul/store-upload params))] (layout/render "upload.html" - (merge (util/standard-params request) + (merge (util/standard-params request content-dir) {:title (util/get-message :file-upload-title request) :uploaded uploaded :is-image (and @@ -176,11 +184,10 @@ page (url-decode (or (:page params) (util/get-message :default-page-title request))) version (:version params) file-name (str page ".md") - repo-path (str (io/resource-path) "/content/") - content (hist/fetch-version repo-path file-name version)] + content (hist/fetch-version content-dir file-name version)] (timbre/info (format "Showing version '%s' of page '%s'" version page)) (layout/render "wiki.html" - (merge (util/standard-params request) + (merge (util/standard-params request content-dir) {:title (str (util/get-message :vers-col-hdr request) " " version " of " page) :page page :content (md->html content)})))) @@ -192,14 +199,13 @@ (let [params (keywordize-keys (:params request)) page (url-decode (or (:page params) (util/get-message :default-page-title request))) version (:version params) - file-name (str page ".md") - repo-path (str (io/resource-path) "/content/")] + file-name (str page ".md")] (timbre/info (format "Showing diff between version '%s' of page '%s' and current" version page)) (layout/render "wiki.html" - (merge (util/standard-params request) + (merge (util/standard-params request content-dir) {:title (str (util/get-message :diff-title-prefix request)" " version " of " page) :page page - :content (d2h/diff2html (hist/diff repo-path file-name version))})))) + :content (d2h/diff2html (hist/diff content-dir file-name version))})))) (defn auth-page @@ -223,7 +229,7 @@ (response/redirect redirect-to)) true (layout/render "auth.html" - (merge (util/standard-params request) + (merge (util/standard-params request content-dir) {:title (if user (str (util/get-message :logout-link request) " " user) (util/get-message :login-link request)) :redirect-to ((:headers request) "referer")}))))) @@ -240,7 +246,7 @@ (auth/evaluate-password pass1 pass2) (auth/change-pass user oldpass pass2))] (layout/render "passwd.html" - (merge (util/standard-params request) + (merge (util/standard-params request content-dir) {:title (str (util/get-message :chpass-title-prefix request) " " user) :message (if changed? (util/get-message :chpass-success request)) :error (cond diff --git a/src/smeagol/util.clj b/src/smeagol/util.clj index ceccf34..5fb0092 100644 --- a/src/smeagol/util.clj +++ b/src/smeagol/util.clj @@ -35,12 +35,12 @@ (defn standard-params "Return a map of standard parameters to pass to the template renderer." - [request] + [request content-dir] (let [user (session/get :user)] {:user user :admin (auth/get-admin user) - :side-bar (md->html (io/slurp-resource "/content/_side-bar.md")) - :header (md->html (io/slurp-resource "/content/_header.md")) + :side-bar (md->html (slurp (cljio/file content-dir "_side-bar.md"))) + :header (md->html (slurp (cljio/file content-dir "_header.md"))) :version (System/getProperty "smeagol.version")}))