simon/smeagol
1
0
Fork 0
mirror of https://github.com/journeyman-cc/smeagol.git synced 2026-04-12 18:05:06 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added information about Docker image to README and Introduction.

Browse source
This commit is contained in:
simon 2016-12-27 13:15:53 +00:00
parent 05db88dd97
commit 4a7781ef05
2 changed files with 92 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -28,7 +28,7 @@ Smeagol does not currently have any mechanism to upload images. You can, however
* Mechanism to add users through the user interface; * Mechanism to add users through the user interface;
## Advertisement ## 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/). If you like what you see here, I am available for work on open source Clojure projects. Contact me via [WEFT](http://www.weft.scot/).
### Phoning home ### 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 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

168
resources/public/content/Introduction.md
View file

@ -1,77 +1,91 @@
# Welcome to Smeagol! ![One wiki to rule them all](https://www.weft.scot/images/smeagol.png)
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.
# Welcome to Smeagol!
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. 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.
## Status 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.
Smeagol is now a fully working small Wiki engine, and meets my own immediate needs. There are some obvious
things which could be improved - see **TODO** list below - but it works now and doesn't seem to have any major problems. ## 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. Here's an example [[Internal Link]]. ## 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: ## 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"}} {: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.
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: ## Images
Smeagol does not currently have any mechanism to upload images. You can, however, link to images already available on the web, like this:
![Smeagol](http://vignette3.wikia.nocookie.net/lotr/images/e/e1/Gollum_Render.png/revision/latest?cb=20141218075509)
![Smeagol](http://vignette3.wikia.nocookie.net/lotr/images/e/e1/Gollum_Render.png/revision/latest?cb=20141218075509)
## Troubleshooting ## Todo
### History * Mechanism to add users through the user interface;
If the history mechanism does not seem to be working, or the git repository does not seem to be updating, login to your server box as the user under whose account the web app runs, go to the directory WEB-INF/classes/public/content and try
## Advertisement
git commit -a If you like what you see here, I am available for work on open source Clojure projects. Contact me via [WEFT](http://www.weft.scot/).
If you get error messages, fix them. The most likely thing is that the web app doesn't have sufficient authority to commit. ### 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
## 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/). resources/templates/base.html
### Phoning home and replace the line
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
<img height="16" width="16" alt="The Web Engineering Factory &amp; Toolworks" src="http://www.weft.scot/images/weft.logo.64.png"> Developed by <a href="http://www.weft.scot/">WEFT</a>
resources/templates/base.html
with the line
and replace the line
<img height="16" width="16" alt="The Web Engineering Factory &amp; Toolworks" src="img/weft.logo.64.png"> Developed by <a href="http://www.weft.scot/">WEFT</a>
<img height="16" width="16" alt="The Web Engineering Factory &amp; Toolworks" src="http://www.weft.scot/images/weft.logo.64.png"> Developed by <a href="http://www.weft.scot/">WEFT</a>
## License
with the line 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
<img height="16" width="16" alt="The Web Engineering Factory &amp; Toolworks" src="img/weft.logo.64.png"> Developed by <a href="http://www.weft.scot/">WEFT</a> parts of Smeagol into another open source project which uses a less restrictive
license, please contact me; I'm open to dual licensing it.
## License
Copyright © 2014-2015 Simon Brooke. Licensed under the GNU General Public License, ## Prerequisites
version 2.0 or (at your option) any later version. If you wish to incorporate You will need [Leiningen](https://github.com/technomancy/leiningen) 2.0 or above installed.
parts of Smeagol into another open source project which uses a less restrictive
license, please contact me; I'm open to dual licensing it. You will need [node](https://nodejs.org/en/) and [bower](https://bower.io/) installed.
## Prerequisites ## Running
You will need [Leiningen](https://github.com/technomancy/leiningen) 2.0 or above installed. To start a web server for the application, run:
You will need [node](https://nodejs.org/en/) and [bower](https://bower.io/) installed. lein bower install
lein ring server
## Running
To start a web server for the application, run: 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 bower install
lein ring server lein ring uberwar
Alternatively, if you want to deploy to a servlet container (which I would strongly recommend), the simplest thing is to run: (a command which I'm sure Smeagol would entirely appreciate) and deploy the resulting war file.
lein bower install ## Experimental Docker image
lein ring uberwar
You can now run Smeagol as a [Docker](http://www.docker.com) image. To run my Docker image, use
(a command which I'm sure Smeagol would entirely appreciate) and deploy the resulting war file.
docker run simonbrooke/smeagol
## Editing the framing content 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
You can edit the [stylesheet](/edit-css?page=stylesheet), the [[\_left-bar]], the [[\_edit-left-bar]], and the [[\_header]].
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.