🍬 Gollum wiki with lots of sugar. 🍬
PlantUML, HTTPS/TLS, HTTP2, gzip, HTTP basic, JWT, etc.
Inspired by suttang/gollum, enriched with sugar provided by the caddy server.
If you're interested in git-based wikis, also have a look at smeagol-galore, which is much faster than gollum, has a modern WYSIWYG interface, including PlantUML and includes SCM-Manager to provide direct access to your Git repos.
docker run -p 8080:80 schnatterer/gollum-galore
- Serves gollum at
http://localhost:8080, - The wiki data is stored in an anonymous volume.
docker run -p80:80 -e GOLLUM_PARAMS="--allow-uploads --live-preview" -e CADDY_PARAMS="-conf /gollum/config/Caddyfile" -v ~/gollum:/gollum schnatterer/gollum-galore
Combined with the following file on your host at ~/gollum/Caddyfile
import /app/Caddyfile
basicauth / test test
- Serves gollum at
http://localhost, - some of gollum's command line options are set
- enables HTTP basic auth, allowing only user
testpasswordtest - The wiki data is stored in
~/gollum/wiki.
Make sure that UID/GID 1000 (used by the container) are allowed to write here.
You can set the git author using git config user.name 'John Doe' && git config user.email '[email protected]' in this folder.
If you prefer a login form and access tokens with longer expiry timeouts, this can be realized using Caddy's login (aka http.login) and jwt (aka http.jwt) plugins, that are included in gollum galore.
import /app/Caddyfile
jwt {
path /
redirect /login?backTo={rewrite_uri}
allow sub demo
allow sub bob
}
login {
htpasswd file=/gollum/config/passwords
simple bob=secret,alice=secret
}
This shows two possibilites: htpasswd (hashed with MD5, SHA1 or Bcrypt) and simple (not recommended, because plain and therefore less secure).
Mount your .htpasswd file at /gollum/config/passwords. This example bases on a .htpasswd file user demo. For example: demo:$2y$10$B/lwbuYGkYDe6wYE4LpuE.DlFFEnM7mK4V7jXDTGJUVEtGZ2P63DK (user demo, password demo).
Create your own .htpasswd (using Bcrypt): htpasswd -n -B -C15 <username>.
Note: If you're running in HTTP mode (no HTTPS/TLS) you will have to set cookie_secure false in login!
The other option is to use a self-signed certificate, see bellow.
See BTBurke/caddy-jwt#42
The following makes Caddy challenge a certificate at letsencrypt.
docker run -p80:80 -e 443:443 -e HOST=yourdomain.com -e CADDY_PARAMS=" -agree [email protected]" -v ~/gollum:/gollum gollum-galore
This will of course only work if this is bound to yourdomain.com:80 and yourdomain:443.
See also Automatic HTTPS - Caddy.
On Openshift we have some other challenges to take. See bellow.
For local testing you might want to use a self-signed certificate. This can be done as follows:
docker run -p8443:443 -e GOLLUM_PARAMS="--allow-uploads --live-preview" -e CADDY_PARAMS="-conf /gollum/config/Caddyfile" -e HOST="*:443" " -v ~/gollum:/gollum gollum
Combined with the following file on your host at ~/gollum/Caddyfile:
import /app/Caddyfile
tls self_signed
See examples/behind-http-proxy.
Also contains a docker-compose.yaml showcase.
You can set the GOLLUM_PARAMS or CADDY_PARAMS env vars.
Note that by default the GOLLUM_PARAMS --config /app/config.rb (see config.rb) is set to enable default
PlantUML rendering. If you want to keep this behavior but set customs GOLLUM_PARAMS, make sure to add the default.
By default, PlantUML Syntax (in between @startuml and @enduml) is rendered via the
http://www.plantuml.com/ renderer. If you want to customize this behavior, insert your own /app/config.rb.
If you want to disable this completely, just set env var GOLLUM_PARAMS without --config /app/config.rb (for example
to an empty value).
You can run gollum-gallore easily on any Kubernetes cluster. It even runs on the free starter plan of openshift v3.
You can find all necessary descriptors in openshift-descriptors-http.yaml. Most of them are standard kubernetes except for the route, which will work only on openshift.
It also shows how to specify gollum params and activates basic auth for user harry and the passwordsally via a base64-encoded secret.
If you want to deploy it, all you got to do is
oc new-project gollum-galore
kubectl apply -f openshift-descriptors-http.yaml
You can query the URL of your route like so: oc get route gollum-galore-generated.
As soon as your pod is ready your gollum wiki will be served at this location.
Note: This is HTTP only! If you're happy with the generated to domain, you can change the route to be edge. If you would like to use a custom domain, see bellow.
Sidenote: There also is a (discontinued) first version of an openshift template.
Unfortunately, no luck getting Letsencrypt running on openshift. There justed to be workarounds (see git history of this file) but Openshift seems to have ended their "grace period during the initial launch of Starter" (see here) plan, where they did not enforce that you cannot specify domain names with the starter plan.
- For Basic Auth see
openshift-descriptors-http.yaml - For JWT see
openshift-descriptors-https-self-signed.yaml
- Almost no configuration necessary
- Works as transparent proxy
- Provides HTTS/Letsencrypt out of the box
Evaluated Alternatives
- Traefik: Easy config, also for Letsencrypt, but didn't work as transparent proxy. Gollums 302 redirects lead to forward to port 4567 in browser, which is not exposed by container (by design!) See Traefik proof of concept
- NGINX: Worked as transparent proxy but letsencrypt required installing a seperate cron proxy. Lots of effort and larger docker image. See NGINX proof of concept
- Gollum wiki is not indended to handle features such as HTTPS and auth -> We need a reverse proxy for that.
- It's just easier to ship this as one artifact.
- Gollum is not really scaleable like this anyway.
- You can run it on the free starter plan of openshift v3 :-)
Build local image and run container. Mount local folder gollum into the container. There, create a Caddyfile as shown in the examples above.
docker build -f Dockerfile -t gollum-galore:latest .docker run -p80:80 --name gg --rm -e CADDY_PARAMS="-conf /gollum/config/Caddyfile" -v gollum:/gollum gollum-galore