Install and Configure gollum on Ubuntu 16.04

Posted on Sunday, April 2, 2017


I am going to do a simple install and set up of Gollum on an Ubuntu 16.04 Server.

What is Gollum?  It's a git based wiki engine used by github.   https://github.com/blog/774-git-powered-wikis-improved [1]

I have gotten used to using markdown and using the git wiki interface for making quick notes that I have decided it's time I figured out how to set up a Gollum wiki at home to use for my personal server documentation.






Install Ruby


The github repo for Gollum can be found at https://github.com/gollum/gollum [2] according to the documentation here the easiest way to install gollum is via RubyGems.

So with that in mind I am going to install ruby via RVM on my Ubuntu 16.04 server.  I am following an rvm install guide I found at https://www.digitalocean.com/community/tutorials/how-to-install-ruby-on-rails-with-rvm-on-ubuntu-16-04 [3]


Grab the key


  > gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3


Use curl to pull down the rvm.sh script


  > curl -sSL https://get.rvm.io -o rvm.sh




Cat its output to bash


  > cat rvm.sh | bash -s stable --rails


At some point it will ask for your user password.



Now source the script that should be installed in your home directory


  > source /home/patman/.rvm/scripts/rvm




Now test it by listing them


  > rvm list known





Now install a ruby version


  > rvm install 2.4


Then list which ruby installations you have


  > rvm list







Install Gollum Gem



  > gem install gollum


Which gave me an error…


ERROR:  Error installing gollum:
        ERROR: Failed to build gem native extension.




Let me see if I can fix it by install libicu-dev


  > sudo apt-get install libicu-dev




Try to install it again


  > gem install gollum


Now there should be a gollum command available


  > which gollum










Running Gollum


Test it out

Make a new repo



  > mkdir wiki-test
  > cd wiki-test
  > git init --bare
  > gollum




Gollum runs a simple web server at port 4567.  Open up the wiki http://192.168.0.77:4567/   (Change the address to match your server)




I get this error  Gollum::InvalidGitRepositoryError



OK that was just me being stupid I should not have used git init --bare.

Let me clean it up and start over again


  > rm -r *
  > git init .
  > gollum


Open the gollum web server again




Hey look I have something.

Let me try and create a few pages and see what I get.







Preview looks fine.


If I look at the log I can see that it was commited to the local git repo.


  > git log




I believe I just made the home page.
Let me make another page.




Click on New






Give it a name and hit OK.


I put the following in it and saved it


#Test Page

Testing an empty link
[[ Test | new-page ]]






Looks like it made a red link to the non-existing page I referenced.






If I click on it I do get a new page.


OK so I got it basically working.  What I really want to do now is work on the interface. I would like to get it to look a lot more like a guthub wiki interface.  Let me see how far I can get.





Sidebar?


First Can I make a sidebar.  Looking around I found this page https://github.com/gollum/gollum/wiki#subpages [4]

Let me see if I can create a sidebar from the interface.   Create a new page and call it _Sidebar.md





Place the following it as a test


#10x13 Docs

###Servers
[[ Gollum | gollum-server ]]





I do not think that worked out so well _Sidebar.md turned into Sidebar-dot-md.


I think I have to add this by hand.

Stop the Gollum server and create the _Sidebar.md file


  > vi _Sidebar.md


And place the following in it


#10x13 Docs

###Servers
[[ Gollum | gollum-server ]]


Then add it to the git repo and commit it


  > git add --all
  > git commit -m "Added sidebar"





Oops looks like I need to add my user.email and user.name



  > git config user.email "me@example.com"
  > git confit user.name "Your name"


Now commit it again


  > git commit -m "Added sidebar"


Start Gollum again and see what we get.

  > gollum








OK that is a start.

But how do I edit it now?  Let me first see if I can customize the header on each page.



If I look at the header used by github





I can see it's much simpler just a page name and then an edit and New page button.   I like and I am going to try and see if I can repeat it.


I tried to add a _Header.md file which creates a result like this.




Which adds a new header… not what I want in this case.






Custom Templates


It looks like you can override the default template using

--template-dir [PATH]
with a custom mustache template



Make a new directory


  > mkdir -p ~/gollum-custom/templates


Now download the gollum repo and copy the templates folder to this folder.


  > cd
  > git clone https://github.com/gollum/gollum.git
  > cp -r gollum/lib/gollum/templates/* \
      ~/gollum-custom/templates/





Start gollum with the --template-dir [PATH]


  > cd ~/wiki-test
  > gollum --template-dir \
    /home/patman/gollum-custom/templates


Open the wiki


It should be the same since the template files are the same.

Now edit the page.mustache file  (leave gollum running)


  > cd ~/gollum-custom/templates/
  > vi page.mustache


Do a search for "Latest Changes" and alter it







Save the file and reload the page.




And it has been altered!








Fix vim syntax


Before I go too far I want to fix the syntax highlighting in vim for mustache files.



  > cd
  > git clone git://github.com/mustache/vim-mustache-handlebars.git mustache.vim
  > mkdir -p .vim/syntax .vim/ftdetect .vim/ftplugin
  > cp -R mustache.vim/syntax/* ~/.vim/syntax/
  > cp -R mustache.vim/ftdetect/* ~/.vim/ftdetect/
  > cp -R mustache.vim/ftplugin/* ~/.vim/ftplugin/


Re-open the page.mustache file



  > cd ~/gollum-custom/templates/
  > vi page.mustache




 

Yeah highlighting!





Edit page.mustache

 

  > vi page.mustache


Here is how I edited mine


<script>
Mousetrap.bind(['e'], function( e ) {
  e.preventDefault();
  window.location = "/edit" + window.location.pathname;
  return false;
});
</script>
<div id="wiki-wrapper" class="page">
<div id="head">
  <h1>{{page_header}}</h1>
  <ul class="actions">
    {{#allow_editing}}
      {{#editable}}
        <li class="minibutton"><a href="{{base_url}}/edit/{{escaped_url_path}}"
           class="action-edit-page" id="minibutton-edit-page"> >Edit</a></li>
      {{/editable}}
    {{/allow_editing}}
    {{#allow_editing}}
      <li class="minibutton jaws">
        <a href="#" id="minibutton-new-page">New Page</a></li>
    {{/allow_editing}}
  </ul>
</div>
<div id="wiki-content">
<div class="{{#has_header}}has-header{{/has_header}}{{#has_footer}} has-footer{{/has_footer}}{{#has_sidebar}} has-sidebar has-{{bar_side}}bar{{/has_sidebar}}{{#has_toc}} has-toc{{/has_toc}}">
  {{#has_toc}}
  <div id="wiki-toc-main">
    {{{toc_content}}}
  </div>
  {{/has_toc}}
  {{#has_sidebar}}
  <div id="wiki-sidebar" class="gollum-{{sidebar_format}}-content">
    <div id="sidebar-content" class="markdown-body">
      {{{sidebar_content}}}
    </div>
  </div>
  {{/has_sidebar}}
  <div id="wiki-body" class="gollum-{{format}}-content">
    {{#has_header}}
    <div id="wiki-header" class="gollum-{{header_format}}-content">
      <div id="header-content" class="markdown-body">
        {{{header_content}}}
      </div>
    </div>
    {{/has_header}}
    <div class="markdown-body">
      {{{content}}}
    </div>
  </div>
  {{#has_footer}}
  <div id="wiki-footer" class="gollum-{{footer_format}}-content">
    <div id="footer-content" class="markdown-body">
      {{{footer_content}}}
    </div>
  </div>
  {{/has_footer}}
  </div>

</div>
<div id="footer">
<br/>
&copy; 2017 Whiteboardcoder
</div>
</div>




And here is the results



For now I will not fiddle with the last edited part (since I am going to be the only one editing these pages.    The last thing I am going to do to this page is to get the New Page button to be green.  To do that I think I need some custom css. 


Use the mini-button-new-page ide


    {{#allow_editing}}
      <li class="minibutton jaws">
        <a href="#" id="minibutton-new-page">New Page</a></li>
    {{/allow_editing}}



How do I get custom css in Gollum?





Custom css


Stop gollum and create a custom.css file in the git repo.


  > vi custom.css


Place the following in it


#minibutton-new-page
{
   color: #fff;
   text-shadow: 0 -1px 0 rgba(0,0,0,0.15);
   background-color: #6cc644 ;
   background-image: -webkit-linear-gradient(#91dd70 , #55ae2e );
   background-image: linear-gradient(#91dd70 , #55ae2e );
   border: 1px solid #5aad35 ;
}
#minibutton-new-page:hover
{
   background-color: #55a532 ;
   background-image: -webkit-linear-gradient(#85d063 , #4f992f );
   background-image: linear-gradient(#85d063 , #4f992f );
   border-color: #519d30 ;
}

#minibutton-edit-page
{
   color:#333;
}
#minibutton-edit-page:hover
{
   text-decoration: none;
   background-color: #ddd;
   background-image: -webkit-linear-gradient(#eee, #ddd);
   background-image: linear-gradient(#eee, #ddd);
   border-color: #ccc;
   color:#333;
}



Add it and commit it


  > git add --all
  > git commit -m "Updated custom css"




Run gollum with this command.


  > gollum --css --template-dir \
    /home/patman/gollum-custom/templates



Now it does look like you do not need to add the custom.css to the repo to get it to work.  So you are free to tweak it and reload the page.

 



Wahoo green is working.  





More tweaks


It looks like I can tweak the _Sidebar.md file if I go to http://192.168.0.77:4567/edit/_Sidebar directly.

With that in mind I think I can tweak the page.mustache file and create a link to it within the sidebar.

First I need an icon.  I use https://www.iconfinder.com/ a lot for getting free icons and on occasion buying one or two for a buck each.

Here is one that looks good enough





I am going to download this file and put it in an images folder in my git wiki



  > mkdir images
  > cd images
  > wget https://www.iconfinder.com/icons/353430/download/png/32
   > mv 32 edit_Pencil.png


Add it to my git repo


  > git add --all
  > git commit -m "Added pencil edit image"





Edit custom.css again



  > vi custom.css


Here is my updated custom.css file


#wiki-wrapper
{
  min-width: 1200px;
}

#wiki-body
{
  min-width: 910px;
}

#minibutton-new-page
{
   color: #fff;
   text-shadow: 0 -1px 0 rgba(0,0,0,0.15);
   background-color: #6cc644 ;
   background-image: -webkit-linear-gradient(#91dd70 , #55ae2e );
   background-image: linear-gradient(#91dd70 , #55ae2e );
   border: 1px solid #5aad35 ;
}
#minibutton-new-page:hover
{
   background-color: #55a532 ;
   background-image: -webkit-linear-gradient(#85d063 , #4f992f );
   background-image: linear-gradient(#85d063 , #4f992f );
   border-color: #519d30 ;
}

#minibutton-edit-page
{
   color:#333;
}
#minibutton-edit-page:hover
{
   text-decoration: none;
   background-color: #ddd;
   background-image: -webkit-linear-gradient(#eee, #ddd);
   background-image: linear-gradient(#eee, #ddd);
   border-color: #ccc;
   color:#333;
}

#wiki-sidebar
{
   width: 230px;
   color: #333;
   background-color: #fff;
}

#sidebar-content
{
   padding: 5px;
   position: relative;
}

#head
{
   margin-top: 5px;
   min-width: 1200px;
   position: relative;
}

#icon-img
{
   margin-left: 40px;
   margin-top: 15px;
}

.actions
{
   position: absolute;
   bottom: 0;
   right: 0;
}

#edit-sidebar
{
   position: absolute;
   top: 0;
   right: 0;
}


#sidebar-content:first-child
{
  margin-top:0px;
}






Now edit page.mustache in the custom templates


  > vi page.mustache


Here is my file contents.



<script>
Mousetrap.bind(['e'], function( e ) {
  e.preventDefault();
  window.location = "/edit" + window.location.pathname;
  return false;
});
</script>
<img id="icon-img" src="images/10x13_80.png"/><br/>
<div id="wiki-wrapper" class="page">
<div id="head">
  <h1>{{page_header}}</h1>
  <ul class="actions">
    {{#allow_editing}}
      {{#editable}}
        <li class="minibutton"><a href="{{base_url}}/edit/{{escaped_url_path}}"
           class="action-edit-page" id="minibutton-edit-page">Edit</a></li>
      {{/editable}}
    {{/allow_editing}}
    {{#allow_editing}}
      <li class="minibutton jaws">
        <a href="#" id="minibutton-new-page">New Page</a></li>
    {{/allow_editing}}
  </ul>
</div>
<div id="wiki-content">
<div class="{{#has_header}}has-header{{/has_header}}{{#has_footer}} has-footer{{/has_footer}}{{#has_sidebar}} has-sidebar has-{{bar_side}}bar{{/has_sidebar}}{{#has_toc}} has-toc{{/has_toc}}">
  {{#has_toc}}
  <div id="wiki-toc-main">
    {{{toc_content}}}
  </div>
  {{/has_toc}}
  {{#has_sidebar}}
  <div id="wiki-sidebar" class="gollum-{{sidebar_format}}-content">
    <div id="sidebar-content" class="markdown-body">
      {{{sidebar_content}}}
      <a id="edit-sidebar" href="edit/_Sidebar"><img src="images/edit_Pencil.png"/></a>
    </div>
  </div>
  {{/has_sidebar}}
  <div id="wiki-body" class="gollum-{{format}}-content">
    {{#has_header}}
    <div id="wiki-header" class="gollum-{{header_format}}-content">
      <div id="header-content" class="markdown-body">
        {{{header_content}}}
      </div>
    </div>
    {{/has_header}}
    <div class="markdown-body">
      {{{content}}}
    </div>
  </div>
  {{#has_footer}}
  <div id="wiki-footer" class="gollum-{{footer_format}}-content">
    <div id="footer-content" class="markdown-body">
      {{{footer_content}}}
    </div>
  </div>
  {{/has_footer}}
  </div>

</div>
<div id="footer">
<br/>
&copy; 2017 Whiteboardcoder
</div>
</div>








Now I have a little edit icon there.  Click it and edit the sidebar






Emojis


I am not getting emojis like I want :smile: is not working.


  > gollum --emoji --css --template-dir  \
   /home/patman/gollum-custom/templates


Just need to start it with the --emoji tag

Here is a good page for a cheat sheet on emojis


Then I edited a file to prove it works



:smile:
:small_airplane:
:small_blue_diamond:
:heart:
:ghost:
:us:
:one:
:two:
:arrow_right_hook:
:white_check_mark:
:x:
:bangbang:
:interrobang:





Worked


But not the same icons on the emoji-cheat-sheet
I wonder if I can update them?





Tables


I am having issues with Markdown tables in gollumm



|ONe | two | three |
|:--- |:--- |:--- |
|there | 192.168.0.199/32 | here is info |
| here | 0.0.0.0/0 | more stuff |


This simple MarkDown table is not working







This is my first time installing gollum, does it have a problem with MarkDown Tables?


Poking around ….

In the gollum githup wiki I see this note …

Since all markups are rendered by the github-markup gem, you can easily add support for other markups by additional installation:



Looking a litter further I see

By default, Gollum ships with the kramdown gem to render Markdown. However, you can use any Markdown renderer supported by github-markup. The thing to remember is that the first installed renderer from the list will be used. So, for example, redcarpet will NOT be used if github/markdown is installed.


If I go over and look at https://github.com/github/markup/blob/master/lib/github/markup/markdown.rb  I think this is  the order they are talking about.






Let me try and install the redcarpet gem and see if it changes anything.


  > gem install redcarpet


Restart gollum


  > gollum --emoji --css --template-dir  \
   /home/patman/gollum-custom/templates






OK that did not help.  In fact in this case some of the emojis that were working are no longer working.

I am going to remove this gem.


  > gem uninstall redcarpet




Something odd is up I am just going to reinstall everything and see where I can get







Gollum install version 2


Going to do this without rvm this time



  > sudo apt-get install ruby ruby-dev make \
  zlib1g-dev libicu-dev build-essential git cmake
  > sudo gem install gollum


Create a new repo and run gollum


  > mkdir wiki-test
  > cde wiki-test
  > git init .
  > gollum


Now for a test



| One | Two |
|:---|:---|
| one | two |







And save it.







Sigh…. No table

That is odd because if I send the file directly to kramdown


  > kramdown Home.md


I get a table







One last try to install github-markdown


  > sudo gem install github-markdown


Then restart gollum


  > gollum





Wahoo that worked


Ok I think that is enough gollum for now.

I have a lot more to tweak on it.  Like getting

·         Emojis to look like githubs emojis
·         Get auto sync of git repo to remote repo
·         Set up nginx as a front with systemd starting gollum?
·         Better preview tool

And many more….



References


[1]        Git-powered wikis improved
[2]        Gollum github repo
[3]        How To Install Ruby on Rails with RVM on Ubuntu 16.04
[4]        Gollum wiki page subpages
[5]        Vim Mustach handlebars github


No comments:

Post a Comment