-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
55 changed files
with
2,690 additions
and
644 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| FROM tomcat:alpine | ||
| COPY target/smeagol-*-standalone.war $CATALINA_HOME/webapps/smeagol.war | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,69 +1,162 @@ | ||
|  | ||
|
|
||
| # Welcome to Smeagol! | ||
| Smeagol is a simple Wiki engine inspired by [Gollum](https://github.com/gollum/gollum/wiki). Gollum is a Wiki engine written in Ruby, which uses a number of simple text formats including [Markdown](http://daringfireball.net/projects/markdown/), and which uses [Git](http://git-scm.com/) to provide versioning and backup. I needed a new Wiki for a project and thought Gollum would be ideal - but unfortunately it doesn't provide user authentication, which I needed, and it was simpler for me to reimplement the bits I did need in Clojure than to modify Gollum. | ||
|
|
||
| So at this stage Smeagol is a Wiki engine written in Clojure which uses Markdown as its text format, which does have user authentication, and which uses Git as its versioning and backup system. | ||
|
|
||
| ## Status | ||
| Smeagol is now a fully working small Wiki engine, and meets my own immediate needs. | ||
|
|
||
| ## Markup syntax | ||
| Smeagol uses the Markdown format as provided by [markdown-clj](https://github.com/yogthos/markdown-clj), with the addition that anything enclosed in double square brackets, \[\[like this\]\], will be treated as a link into the wiki itself. | ||
|
|
||
| ## Security and authentication | ||
| Security is now greatly improved. There is a file called *passwd* in the *resources* directory, which contains a clojure map which maps usernames to maps with plain-text passwords and emails thus: | ||
|
|
||
| {:admin {:password "admin" :email "admin@localhost" :admin true} | ||
| :adam {:password "secret" :email "adam@localhost"}} | ||
|
|
||
| that is to say, the username is a keyword and the corresponding password is a string. However, since version 0.5.0, users can now change their own passwords, and when the user changes their password their new password is encrypted using the [scrypt](http://www.tarsnap.com/scrypt.html) one-way encryption scheme. The password file is now no longer either in the *resources/public* directory so cannot be downloaded through the browser, nor in the git archive to which the Wiki content is stored, so that even if that git archive is remotely clonable an attacker cannot get the password file that way. | ||
|
|
||
| ## Images | ||
| Smeagol does not currently have any mechanism to upload images. You can, however, link to images already available on the web, like this: | ||
|
|
||
|  | ||
|
|
||
| ## Todo | ||
| * Mechanism to add users through the user interface; | ||
|
|
||
| ## Advertisement | ||
| If you like what you see here, I am available for work on open source Clojure projects. Contact me vis [WEFT](http://www.weft.scot/). | ||
|
|
||
| ### Phoning home | ||
| Smeagol currently requests the WEFT logo in the page footer from my home site. This is mainly so I can get a feel for how many people are using the product. If you object to this, edit the file | ||
|
|
||
| resources/templates/base.html | ||
|
|
||
| and replace the line | ||
|
|
||
| <img height="16" width="16" alt="The Web Engineering Factory & Toolworks" src="http://www.weft.scot/images/weft.logo.64.png"> Developed by <a href="http://www.weft.scot/">WEFT</a> | ||
|
|
||
| with the line | ||
|
|
||
| <img height="16" width="16" alt="The Web Engineering Factory & Toolworks" src="img/weft.logo.64.png"> Developed by <a href="http://www.weft.scot/">WEFT</a> | ||
|
|
||
| ## License | ||
| Copyright © 2014-2015 Simon Brooke. Licensed under the GNU General Public License, | ||
| version 2.0 or (at your option) any later version. If you wish to incorporate | ||
| parts of Smeagol into another open source project which uses a less restrictive | ||
| license, please contact me; I'm open to dual licensing it. | ||
|
|
||
| ## 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, run: | ||
|
|
||
| lein bower install | ||
| lein ring server | ||
|
|
||
| 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. | ||
|
|
||
|  | ||
|
|
||
| # Welcome to Smeagol! | ||
| Smeagol is a simple Wiki engine inspired by [Gollum](https://github.com/gollum/gollum/wiki). Gollum is a Wiki engine written in Ruby, which uses a number of simple text formats including [Markdown](http://daringfireball.net/projects/markdown/), and which uses [Git](http://git-scm.com/) to provide versioning and backup. I needed a new Wiki for a project and thought Gollum would be ideal - but unfortunately it doesn't provide user authentication, which I needed, and it was simpler for me to reimplement the bits I did need in Clojure than to modify Gollum. | ||
|
|
||
| So at this stage Smeagol is a Wiki engine written in Clojure which uses Markdown as its text format, which does have user authentication, and which uses Git as its versioning and backup system. | ||
|
|
||
| <a href="https://zenhub.com"><img src="https://raw.githubusercontent.com/ZenHubIO/support/master/zenhub-badge.png"></a> | ||
|
|
||
| ## Status | ||
| Smeagol is now a fully working small Wiki engine, and meets my own immediate needs. | ||
|
|
||
| ## Markup syntax | ||
| Smeagol uses the Markdown format as provided by [markdown-clj](https://github.com/yogthos/markdown-clj), with the addition that anything enclosed in double square brackets, \[\[like this\]\], will be treated as a link into the wiki itself. | ||
|
|
||
| ### Pluggable extensible markup | ||
|
|
||
| A system of pluggable, extensible formatters is supported. In normal markdown, code blocks may be delimited by three backticks at start and end, and often the syntax of the code can be indicated by a token immediately following the opening three backticks. This has been extended to allow custom formatters to be provided for such code blocks. Two example formatters are provided: | ||
|
|
||
| #### The Vega formatter | ||
|
|
||
| Inspired by [visdown](http://visdown.amitkaps.com/) and [vega-lite](https://vega.github.io/vega-lite/docs/), the Vega formatter allows you to embed vega data visualisations into Smeagol pages. The graph description should start with a line comprising three back-ticks and then the word '`vega`', and end with a line comprising just three backticks. | ||
|
|
||
| Here's an example cribbed in its entirety from [here](http://visdown.amitkaps.com/london): | ||
|
|
||
| ##### Flight punctuality at London airports | ||
|
|
||
| ```vega | ||
| data: | ||
| url: "data/london.csv" | ||
| transform: | ||
| - | ||
| filter: datum.year == 2016 | ||
| mark: rect | ||
| encoding: | ||
| x: | ||
| type: nominal | ||
| field: source | ||
| y: | ||
| type: nominal | ||
| field: dest | ||
| color: | ||
| type: quantitative | ||
| field: flights | ||
| aggregate: sum | ||
| ``` | ||
|
|
||
| Data files can be uploaded in the same way as images, by using the **upload a file** link. | ||
|
|
||
| Note that this visualisation will not be rendered in the GitHub wiki, as it doesn't have Smeagol's data visualisation magic. This is what it should look like: | ||
|
|
||
|  | ||
|
|
||
| #### The Mermaid formatter | ||
|
|
||
| Graphs can now be embedded in a page using the [Mermaid](http://knsv.github.io/mermaid/index.html) graph description language. The graph description should start with a line comprising three back-ticks and then the word `mermaid`, and end with a line comprising just three backticks. | ||
|
|
||
| Here's an example culled from the Mermaid documentation. | ||
|
|
||
| ##### GANTT Chart | ||
|
|
||
| ```mermaid | ||
| gantt | ||
| dateFormat YYYY-MM-DD | ||
| title Adding GANTT diagram functionality to mermaid | ||
| section A section | ||
| Completed task :done, des1, 2014-01-06,2014-01-08 | ||
| Active task :active, des2, 2014-01-09, 3d | ||
| Future task : des3, after des2, 5d | ||
| Future task2 : des4, after des3, 5d | ||
| section Critical tasks | ||
| Completed task in the critical line :crit, done, 2014-01-06,24h | ||
| Implement parser and jison :crit, done, after des1, 2d | ||
| Create tests for parser :crit, active, 3d | ||
| Future task in critical line :crit, 5d | ||
| Create tests for renderer :2d | ||
| Add to mermaid :1d | ||
| ``` | ||
|
|
||
| To add your own formatter, compile it into a jar file which is on the classpath - it does *not* have to be part of the Smeagol project directly, and then edit the value of the key `:formatters` in the file `config.edn`; whose standard definition is: | ||
|
|
||
| :formatters {"vega" smeagol.formatting/process-vega | ||
| "vis" smeagol.formatting/process-vega | ||
| "mermaid" smeagol.formatting/process-mermaid} | ||
|
|
||
| The added key should be the word which will follow the opening three backticks of your code block, and the value of that key should be a symbol which evaluates to a function which can format the code block as required. | ||
|
|
||
| ## Security and authentication | ||
| Security is now greatly improved. There is a file called *passwd* in the *resources* directory, which contains a clojure map which maps usernames to maps with plain-text passwords and emails thus: | ||
|
|
||
| {:admin {:password "admin" :email "admin@localhost" :admin true} | ||
| :adam {:password "secret" :email "adam@localhost"}} | ||
|
|
||
| that is to say, the username is a keyword and the corresponding password is a string. However, since version 0.5.0, users can now change their own passwords, and when the user changes their password their new password is encrypted using the [scrypt](http://www.tarsnap.com/scrypt.html) one-way encryption scheme. The password file is now no longer either in the *resources/public* directory so cannot be downloaded through the browser, nor in the git archive to which the Wiki content is stored, so that even if that git archive is remotely clonable an attacker cannot get the password file that way. | ||
|
|
||
| ## Images | ||
| You can (if you're logged in) upload files, including images, using the **Upload a file** link on the top menu bar. You can link to an uploaded image, or other images already available on the web, like this: | ||
|
|
||
|  | ||
|
|
||
| ## Advertisement | ||
| If you like what you see here, I am available for work on open source Clojure projects. | ||
|
|
||
| ### Phoning home | ||
| Smeagol currently requests the WEFT logo in the page footer from my home site. This is mainly so I can get a feel for how many people are using the product. If you object to this, edit the file | ||
|
|
||
| resources/templates/base.html | ||
|
|
||
| and replace the line | ||
|
|
||
| <img height="16" width="16" alt="The Web Engineering Factory & Toolworks" src="http://www.weft.scot/images/weft.logo.64.png"> Developed by <a href="http://www.weft.scot/">WEFT</a> | ||
|
|
||
| with the line | ||
|
|
||
| <img height="16" width="16" alt="The Web Engineering Factory & Toolworks" src="img/weft.logo.64.png"> Developed by <a href="http://www.weft.scot/">WEFT</a> | ||
|
|
||
| ## License | ||
| Copyright © 2014-2015 Simon Brooke. Licensed under the GNU General Public License, | ||
| version 2.0 or (at your option) any later version. If you wish to incorporate | ||
| parts of Smeagol into another open source project which uses a less restrictive | ||
| license, please contact me; I'm open to dual licensing it. | ||
|
|
||
| ## 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, run: | ||
|
|
||
| lein bower install | ||
| lein ring server | ||
|
|
||
| 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. 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,54 +1,86 @@ | ||
| (defproject smeagol "0.5.0-rc3" | ||
| (defproject smeagol "1.0.0-rc3" | ||
| :description "A simple Git-backed Wiki inspired by Gollum" | ||
| :url "https://github.com/simon-brooke/smeagol" | ||
| :dependencies [[org.clojure/clojure "1.7.0"] | ||
| [org.clojure/core.memoize "0.5.9"] | ||
| [com.taoensso/encore "2.91.1"] | ||
| [lib-noir "0.9.9" :exclusions [org.clojure/tools.reader]] | ||
| :license {:name "GNU General Public License,version 2.0 or (at your option) any later version" | ||
| :url "https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html"} | ||
| :dependencies [[clj-jgit "0.8.10"] | ||
| [clj-yaml "0.4.0"] | ||
| [com.cemerick/url "0.1.1"] | ||
| [com.fzakaria/slf4j-timbre "0.3.7"] | ||
| [com.taoensso/encore "2.92.0"] | ||
| [com.cemerick/url "0.1.1"] | ||
| [ring-server "0.4.0"] | ||
| [selmer "1.10.9"] | ||
|
|
||
| [org.clojure/tools.logging "0.4.0"] | ||
| [com.taoensso/timbre "4.10.0"] | ||
| [com.fzakaria/slf4j-timbre "0.3.7"] | ||
| [org.slf4j/slf4j-api "1.7.25"] | ||
| [org.slf4j/log4j-over-slf4j "1.7.25"] | ||
| [org.slf4j/jul-to-slf4j "1.7.25"] | ||
| [org.slf4j/jcl-over-slf4j "1.7.25"] | ||
|
|
||
| [com.taoensso/tower "3.0.2" :exclusions [com.taoensso/encore]] | ||
| [markdown-clj "0.9.99" :exclusions [com.keminglabs/cljx]] | ||
| [crypto-password "0.2.0"] | ||
| [clj-jgit "0.8.9"] | ||
| [environ "1.1.0"] | ||
| [hiccup "1.0.5"] | ||
| [im.chit/cronj "1.4.4"] | ||
| [lib-noir "0.9.9" :exclusions [org.clojure/tools.reader]] | ||
| [markdown-clj "0.9.99" :exclusions [com.keminglabs/cljx]] | ||
| [noir-exception "0.2.5"] | ||
| [prone "1.1.4"]] | ||
| [org.clojars.simon_brooke/internationalisation "1.0.3"] | ||
| [org.clojure/clojure "1.8.0"] | ||
| [org.clojure/core.memoize "0.5.9"] | ||
| [org.clojure/data.json "0.2.6"] | ||
| [org.clojure/tools.logging "0.4.0"] | ||
| [org.slf4j/slf4j-api "1.7.25"] | ||
| [org.slf4j/log4j-over-slf4j "1.7.25"] | ||
| [org.slf4j/jul-to-slf4j "1.7.25"] | ||
| [org.slf4j/jcl-over-slf4j "1.7.25"] | ||
| [prone "1.1.4"] | ||
| [ring/ring-anti-forgery "1.1.0"] | ||
| [ring-server "0.4.0"] | ||
| [selmer "1.11.0"]] | ||
|
|
||
| :repl-options {:init-ns smeagol.repl} | ||
|
|
||
| :jvm-opts ["-server"] | ||
| :plugins [[lein-ring "0.8.13" :exclusions [org.clojure/clojure]] | ||
| [lein-environ "1.0.0"] | ||
|
|
||
| :plugins [[lein-ancient "0.5.5" :exclusions [org.clojure/clojure org.clojure/data.xml]] | ||
| [lein-bower "0.5.1"] | ||
| [lein-ancient "0.5.5" :exclusions [org.clojure/clojure org.clojure/data.xml]] | ||
| [lein-marginalia "0.7.1" :exclusions [org.clojure/clojure]]] | ||
| :bower-dependencies [[simplemde "1.11.2"]] | ||
| [lein-codox "0.10.3"] | ||
| [io.sarnowski/lein-docker "1.0.0"] | ||
| [lein-environ "1.0.0"] | ||
| [lein-marginalia "0.7.1" :exclusions [org.clojure/clojure]] | ||
| [lein-ring "0.8.13" :exclusions [org.clojure/clojure]]] | ||
|
|
||
| :bower-dependencies [[simplemde "1.11.2"] | ||
| ;; [vega-embed "3.0.0-beta.20"] ;; vega-embed currently not loaded from Bower because of | ||
| ;; dependency conflict which will hopefully be resolved soon. | ||
| [vega-lite "2.0.0-beta.11"] | ||
| [mermaid "6.0.0"]] | ||
|
|
||
| :docker {:image-name "simonbrooke/smeagol" | ||
| :dockerfile "Dockerfile"} | ||
|
|
||
| :ring {:handler smeagol.handler/app | ||
| :init smeagol.handler/init | ||
| :destroy smeagol.handler/destroy} | ||
| :lein-release {:scm :git :deploy-via :lein-install} | ||
| :profiles | ||
| {:uberjar {:omit-source true | ||
| :env {:production true} | ||
| :aot :all} | ||
| :production {:ring {:open-browser? false | ||
| :stacktraces? false | ||
| :auto-reload? false}} | ||
| :dev {:dependencies [[ring-mock "0.1.5"] | ||
| [ring/ring-devel "1.6.2"] | ||
| [pjstadig/humane-test-output "0.8.2"]] | ||
| :injections [(require 'pjstadig.humane-test-output) | ||
| (pjstadig.humane-test-output/activate!)] | ||
| :env {:dev true}}} | ||
|
|
||
| :release-tasks [["vcs" "assert-committed"] | ||
| ["change" "version" "leiningen.release/bump-version" "release"] | ||
| ["vcs" "commit"] | ||
| ;; ["vcs" "tag"] -- not working, problems with secret key | ||
| ["clean"] | ||
| ["bower" "install"] | ||
| ["ring" "uberwar"] | ||
| ["docker" "build"] | ||
| ["docker" "push"] | ||
| ["change" "version" "leiningen.release/bump-version"] | ||
| ["vcs" "commit"]] | ||
|
|
||
| :profiles {:uberjar {:omit-source true | ||
| :env {:production true} | ||
| :aot :all} | ||
| :production {:ring {:open-browser? false | ||
| :stacktraces? false | ||
| :auto-reload? false}} | ||
| :dev {:dependencies [[ring-mock "0.1.5"] | ||
| [ring/ring-devel "1.6.2"] | ||
| [pjstadig/humane-test-output "0.8.2"]] | ||
| :injections [(require 'pjstadig.humane-test-output) | ||
| (pjstadig.humane-test-output/activate!)] | ||
| :env {:dev true}}} | ||
|
|
||
| :min-lein-version "2.0.0") |
Oops, something went wrong.