Gollum docs not hosted by Gollum

[mvdkleijn]

Hi there!

I just found Gollum and I have to say it's a little weird that it isn't hosting its own documentation. :smile:

Might I respectfully suggest that it'd be a good idea to host the Gollum docs in a read-only instance which syncs with a remote repo?

I did see issue #1444 by the way... I just think that a demo should be separate of the docs, if only for security purposes.

Thanks! Martijn

[mvdkleijn]

By the way, I would be open to help by hosting a Gollum instance.

[dometto]

Hi! Totally agree we should do this, somehow. But the dilemma we have is the following.

At present, any logged in github user can edit the wiki. This means many people chip in occasionally, for instance by updating the installation instructions. And for example, we can ask people in the issue tracker to make edits to the wiki, if we figure out a workaround. In short, the fact that the wiki is editable by any github user saves us a bunch of time and energy. If we move the docs to a read-only gollum instance, we lose that advantage. If we make the gollum instance editable, though, we face the problem that anyone can edit it -- there's no "sanity" check of having a functioning github account.

Not sure what the best way forwards is, which is why we haven't made any progress on this. Very open to suggestions! Maybe the best way would be to run an instance with omnigollum and make people authenticate via GitHub OAuth?

I would be open to help by hosting a Gollum instance.

That's great! That was another show stopper up til now. :) Happy to hear what you, @bartkamphorst, and @heavywatal think is a good way forward.

[mvdkleijn]

If we move the docs to a read-only gollum instance, we lose that advantage.

Fair point.

If we make the gollum instance editable, though, we face the problem that anyone can edit it -- there's no "sanity" check of having a functioning github account.

If my assumption is correct and Gollum itself has no concept of a "user", it'd be damn difficult to block or ban users that abuse the system. Is my assumption correct?

run an instance with omnigollum and make people authenticate via GitHub OAuth?

That's one way. I could stick Caddy in front or some other mechanism. Depends on my above assumption being correct or not though.

[mvdkleijn]

First of all... am I correct in saying that Gollum currently has no concept of a user other than setting the author info in the Git repo that serves the docs?

[dometto]

@mvdkleijn that's mostly correct, yes. There is, however, already support for setting the author info in the HTTP session under the gollum.author key (see e.g. here). So that would be a way to map particular changes to a wiki to particular users.

[mvdkleijn]

So in summary, the requirements for having the Gollum docs hosted by Gollum itself would be:

• [ ] Allow users to login using Github (at least)
• [ ] Have SSO with Github
• [ ] Have the author info set to the logged in user's info
• [ ] Have a block list of some sort that allows abusive users to be blocked
• [ ] A nice DNS CNAME entry like docs.gollum.net or something would be nice of course

Since the docs are in git, cleaning up after an abusive user would be as simple as to remove their commits.

I can take a look sometime today or tomorrow to see if we have all the components available somewhere and maybe whip up a demo setup on one of my machines.

[dometto]

@mvdkleijn https://github.com/arr2036/omnigollum might be useful for providing authentication. It uses OmniAuth, so I think should also be able to do GitHub OAuth.

Many thanks for helping out with this! Much appreciated

[mvdkleijn]

So I took a look at omnigollum and that project has basically been dead in the water since 2015/2016. No real updates to speak of. Having said that, I did try to install it but encountered several issues including at least two security flaws that have gone unattended by the author.

As such, I do not really consider omniauth a valid option.

I'm not really a fan of Ruby to be honest, but I could see if can write some code to build this into Gollum itself using omniauth (not omnigollum). That project seems a lot more responsive.

If I'm very honest, I like the idea of Gollum a lot but I'm very tempted to rewrite it into Go. :rofl:

[ryuwd]

Omnigollum + the GitHub OAuth provider worked for me without any problems. I just set it up today on my own instance.

You can create an OAuth App on GitHub by following the API docs: https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/

Omnigollum and the github omniauth strategy can be installed via rubygems, so all that's left is to configure rack to use it.

Here is a snippet from my config.ru file:

#!/usr/bin/env ruby
require 'rubygems'
require 'gollum/app'
require 'omnigollum'
require 'omniauth/strategies/github'

# ... the usual gollum wiki config stuff ...

options = {
  # OmniAuth::Builder block is passed as a proc
  :providers => Proc.new do
    provider :github, ENV['GH_CLIENT_ID'], ENV['GH_SECRET']
  end,
  :dummy_auth => false,
  # If you want to make pages private:
  :protected_routes => [ ], #
  # Specify committer name as just the user name
  :author_format => Proc.new { |user| user.name },
  # Specify committer e-mail as just the user e-mail
  :author_email => Proc.new { |user| user.email },

  # Authorized users
  :authorized_users => [ ],
}

## :omnigollum options *must* be set before the Omnigollum extension is registered
Precious::App.set(:omnigollum, options)
Precious::App.register Omnigollum::Sinatra

run Precious::App

It should be trivial to tweak the above to your needs. If anything isn't clear, I found most of this via Google search - I'm sure there is an answer out there.

You should set GH_CLIENT_ID and GH_SECRET in your environment to their respective values before running the rack gollum instance.

The callback URL to set on the GitHub end is: https://<the gollum instance>/__omnigollum__/auth/github/callback

[dometto]

@ryuwd thanks for the setup guidelines! However, @mvdkleijn reported:

issues including at least two security flaws that have gone unattended by the author.

If this refers to actual exploits in the codebase (rather than insecurities arising from incorrect configuration), that's obviously a major concern. I think omnigollum is still quite widely used, though, so I would urge @mvdkleijn to report the vulnerabilities and see if the maintainer is still responsive.

[ryuwd]

Hello @dometto!

I'd also very much like to know about the security issues in case they affect my instance.

I had a quick look at the Issues list on the omnigollum repo to check. I noticed one here at arr2036/omnigollum#44 that @mvdkleijn commented on, but from the discussion it seems inconclusive as to whether it's a security issue or an intended behaviour of Sinatra.

If the protected route /* is set and authorized_users is set tonil (which means users must be authenticated by GitHub, and only authenticated users can view edit, add, delete etc...). I don't think this particular issue would cause problems since wildcards are case insensitive.

[mvdkleijn]

hi @ryuwd and @dometto the main issue I saw is that routes are treated as case sensitive.

Apparently that is by design but I feel that it is a security issue. How big of an issue, that's up to you I guess. In any case, it makes it very easy for someone to misconfigure the system.

You could, as suggested, protect /* but that takes away options.

Anyway, I'm not heavily involved in Gollum, omniauth or even the Ruby scene. I use and write Ruby software on occasion but my use of Gollum is low. (mostly due to time constraints) :smile:

Please keep in mind that I'm not saying omniauth or gollum are inherently bad products or anything.

[dometto]

I think the case-sensitivity issue is no longer a live one since gollum 5.x, since we're now matching all routes (not just 'special' routes such as /edit, but also the paths to documents) case sensitively. If I understand correctly, that's best practice when defining an API, and certainly in our case, as git is case sensitive. I'll report this at omnigollum.

To me personally, omnigollum looks like an acceptable solution for the purposes at hand. The documentation is obviously not super sensitive information, we just want to have some form of authentication in place to stop people from treating the docs like a sandbox, or intentionally defacing. If you're still willing to help out with this setup, much obliged @mvdkleijn! If you're too busy please just let us know :)

[mvdkleijn]

Hmmm... I'm currently working on a PR for Gitea but I'll revisit this once I'm done. My gut feeling is that it'll be more work than "simply" sticking omniauth in front of Gollum. :smile:

[dometto]

Let me know if I can lend a hand, I've acquired some experience with rack and sinatra ;)

[dometto]

For anyone reading this: we're still looking for someone to help out with free hosting. The current idea is to use omnigollum with Github OAuth for auth.

[computamike]

hi @dometto - This might be a bit "left field here" - but could you publish the Gollum Docs - using Gollum - to GitHub Pages?

The site would potentially be hosted free (under Gitub), you can get a fancy gollum.io domain (or whatever) and point to it, and you could use actions to automatically publish docs when merged into branch.

[sn0n]

Updates?

[Alxira5]

I guess it can only be an idea, but it would be a better option to export a Gollum wiki statically and host it on GitHub Pages, since as seen in the previous entries, it is not really necessary that there be the ability to authenticate or make edits from the wiki, but only demonstrate in real time the functions of Gollum seen in the screenshots.

[MarlonJMejia]

Hi! Totally agree we should do this, somehow. But the dilemma we have is the following.

At present, any logged in github user can edit the wiki. This means many people chip in occasionally, for instance by updating the installation instructions. And for example, we can ask people in the issue tracker to make edits to the wiki, if we figure out a workaround. In short, the fact that the wiki is editable by any github user saves us a bunch of time and energy. If we move the docs to a read-only gollum instance, we lose that advantage. If we make the gollum instance editable, though, we face the problem that anyone can edit it -- there's no "sanity" check of having a functioning github account.

Not sure what the best way forwards is, which is why we haven't made any progress on this. Very open to suggestions! Maybe the best way would be to run an instance with omnigollum and make people authenticate via GitHub OAuth?

I would be open to help by hosting a Gollum instance.

That's great! That was another show stopper up til now. :) Happy to hear what you, @bartkamphorst, and @heavywatal think is a good way forward.

Would you just be able to put a PR to update the documentation?