Self Host a Wiki or Knowledge Base for Your Team | Hacker News Reader

Self Host a Wiki or Knowledge Base for Your Team

chsasank.github.io

115 pointschsasank72 comments

Unless I am remembering wrong (and the copy stored at the Internet Archive seems to agree with me[0]), you're not allowed to use the Outline source code for production use and you're definitely not allowed to use it in a way that lets third parties contribute to it.

A non-free blob of software that requires integration with a definitely non-free separate service (Slack) that I can't also self-host doesn't sound all that attractive to someone (like me) who is interested in self-hosting.

The software is pretty but those sparkly binds are a bit too tight.

0 - Had to check here since, as of writing, Github is under the weather: http://web.archive.org/web/20200614175138/https://github.com...

The BSL is meant to be open source "in spirit", with the sole restriction being that you can't run a competitive hosted service because that's the only way the project sustains itself.

Internally hosting a copy for your own company is purposefully within the bounds of the license.

Not a lawyer, but that sounds a bit wishy-washy, which corporate lawyers are really not fond of. It's part of the reason why the JSON standard was problematic for a while, because it had a clause stating that it "should be used for Good, not Evil", which is a legal nightmare.

Ditto on the not a lawyer aspect, but this seems pretty straightforward:

   You may make use of the Licensed Work, provided that
                      you may not use the Licensed Work for a Document
                      Service.

                      A “Document Service” is a commercial offering that
                      allows third parties (other than your employees and
                      contractors) to access the functionality of the
                      Licensed Work by creating teams and documents
                      controlled by such third parties.

It isn't really all that straightforward. The key distinction is in that phrase, "your employees and contractors". What happens if I go through a recruiting agency to hire a contractor, and the contractor is actually an employee of the recruiting agency? Does that contractor get access to my wiki? What happens if I contract with an external design firm? Do their employees get access to my wiki? What happens if I try to cheat this language by providing a wiki service as a B2B enterprise, where I get hired as a contractor (a wiki-provider contractor) to all of these corporation to set up wikis for them?

That language is the sort of seemingly straightforward sounding language that can and does get litigated to death, and I wouldn't blame a corporate lawyer for advising his or her client to steer clear.

Every single example you give either falls under contractor or employee. Simply because you don‘t know legal language, doesn‘t mean lawyers don’t have simple, binary ways to deal with this that fully captures all of your examples. Law is not at all wishy washy in this case. If both employees and contractors are captured, then you‘re literally covered.

What I do agree with, is that any careful corporate lawyer would have a good look at this license and check whether there are any courts that have ever looked at this license to see how battle tested it is. Speaking as a lawyer, what I would see as an edge case that might be problematic is if a competitor of Outline that uses its completely self-built tech stack to provide a competing service as outlined in that clause would use Outline internally as a knowledge base. But I mean that‘d be absurd.

// addendum Personally, I think it would be cool if Outline at some point removed that clause, once it has built sufficient moat around its commodity services.

OTOH:

I can't tell you how many telemedicine (aka, video conferencing) services use Zoom, Google, or GTM as their teleconferencing solution when speaking with prospective clients.

I've literally only had one that was actually using the televideo software they were pitching me as the televideo platform for our demo call. One out of many.

There's no such thing as "open source in spirit". Either something is open source, and I can use and redistribute the software per the requirements of the Open Source Initiative, or I cannot. "Open source in spirit" means, in practice, "closed source, but we probably won't sue you if we like you". While that's certainly fine for a personal wiki, I would have strong qualms about using this for a business.

Open source isn't a term exclusively owned and defined by the OSI.

You can define it however you like, but that term has long been used to describe projects that don't quite fit in OSI's box.

To be clear- I think OSI has the best definition that I would like to see- but 'somewhat open source' is certainly better than nothing.

I very strongly disagree. Historically, the whole point of open source is that you get a license that specifies your rights. You want software that you know you can use and modify even if the original author later doesn't approve. "Somewhat open source" is simply not open source in the way that term is used. (Naturally, you're free to redefine the term for your own usage, but that doesn't change anything.)

Edit: Past terms used for this type of license are freeware and source available, but that doesn't make them open source.

I think those of us who like the OSI definition of "Open Source" should actively push back on use of the term to mean something other than the OSI definition. I'd rather see licenses like the BSL called "source available" or some such.

Yea, at this point we're careful to only use the language of open source where it applies, for example our editor _is_ OSI compatible

> There's no such thing as "open source in spirit"

I guess that's down to personal opinion. I and others say there is, take a look at this article regarding the license: https://itsfoss.com/making-the-business-source-license-open-...

In the end I'm not interested in having an argument with Open Source zealots – it seems that once you make the source code of a project public there is a category of person on the internet that isn't happy until it's completely free.

By that logic, Microsoft Windows is open-source, because I can view its source under the MS Reference Source License.

This is the key distinction between "Source Available" and "Open Source". Open Source is open. That means I can modify the source and redistribute my changes. If I can't do that, the software is closed source, no matter how much marketing you apply to it.

I guess we'll agree to disagree! In the meantime I'll keep building the project and the business.

That's not open source in spirit... that's the opposite of everything open source stands for.

It garnered Bruce Peren's endorsement ;)

https://itsfoss.com/making-the-business-source-license-open-...

What happens if the company starts selling on-premises products in the future?

> integration with a definitely non-free separate service (Slack) that I can't also self-host doesn't

Email login is part of the latest outline release, I think. Can't confirm because github is down.

Outline is proprietary software. https://github.com/outline/outline/blob/develop/LICENSE

Also, are you saying it requires you to run Slack alongside?

There are many good and free software wiki engines, I don't see why one would choose such a headache. https://en.wikipedia.org/wiki/Comparison_of_wiki_software

I looked at BookStack, dokuwiki, mediawiki and multiple other open source wikis. None of them are as intuitive and easy to use as outline.

I was just wondering how Outline made money / was intending to make money. This seems like an ok way to do things.

Did you look at wiki.js ( https://wiki.js.org/ )?

I've been evaluating wikis too, and that's at the top of my list because it checks the boxes of having a git backend, markdown, and third-party auth providers.

Only downside is that it's NodeJS, which I'd rather not deal with given our existing tech stack, but as an internal app it should be fine.

I did. It's interface is not as intuitive and streamlined as Outline. Our team found outline super intuitive because Outline's collections and Slack's channels are equivalent.

I've installed wikijs for a small team of developers at their request.

The biggest selling point for this piece of software, compared to showing them 5 other alternatives, is that it looks good, it's eye candy. And that is exactly what I've seen people want from software like these. They want to feel good when they open it and browse, they want to see a modern look, it makes the experience of using and maintaining a knowledge base more appealing so they engage more. Feature wise it's no confluence, nor xwiki, it's just a page editor with user management, but it's quick to set up, uses extreemely little memory by default, feels fast and looks good, so they don't mind if they see some functionality missing.

Among more and more tools that I install for people I see this pattern where they are judged by their looks above features, and it's not easy for me to fully understand it... But then again I started learning and programming ruby for the same reason, it looked and felt good, so I stuck with it.

So I guess the big takeaway here is not a large pepperoni pizza from domino's, but the fact that software looks matter, a lot, and it's probably going to matter more and more in the future.

What's not so easy to understand that the looks matter?

I've gone through a list of wiki apps a few months ago as DokuWiki was showing its age, every time the demo page looked like some web from the 90's, I don't care what features it has but closed it instantly.

I do full stack web but I make sure it's also visually pleasing for anything I build because there's no reason to give users eye pain.

I'd rather think that anything that doesn't look good means the author had no time for visual adjustment as the internals still has a lot to be desired.

ah, interesting. I guess the implication in your comment is that there are other, more capable alternatives (but not as "pretty"). What are some of the criteria where wikijs is lacking? For me, wikijs was leading in all the criteria I mentioned in my original post.

Second wiki.js.

I've used DokuWiki for over a decade but it's showing its age. It's just a collection of hacks to add features and sometimes third party plugins are too buggy but wiki.js has most of what I wanted built-in.

It had WYSIWYG editor. Frankly a bare markdown editor is out of the question as it is never intuitive for anyone but some techie who likes remembering all the tags and I'm s programmer for a long time but I'd take WYSIWYG any day for managing structured documents.

It has plenty of auth targets from LDAP to oauth and many others.

It doesn't force you with some weird rule such as "link first and create page" but just hit the "New page" button and since it has list of pages for both front side and the admin panel, you'll never have some page left in limbo.

Admin panel is good. It lets you put custom CSS, so you can control the look pretty well including removing the parts you don't want.

Custom navigation let's you add any links in the menu and access control is good, so it's easy to allow a group of people access certain pages.

And it looks good.

I'm just a user.

Yeah, I did similar research as you and found that none of them were sticky enough for my uses. WikiJS came the closest, but it didn't feel 100% baked yet.

I'm currently using Dropbox Paper as my pseudo-wiki, which is... OK until I find something better.

For me, I like that Paper supports Markdown shortcuts (which for me personally, is the most important editor feature) and is minimalist.

I use Kiwi wiki on my phone, host the files on my dropbox, and access it via Sublime (with markdown add-ons) on my pc.

I've also been experimenting with Obsidian, which so far looks like it might be better.

Slack or Google can be used as sign-in options, email can also be used once a team is created but not for the initial registration.

There is a community PR that's being worked on to make the auth system a bit more pluggable, I'd link if GitHub was online.

2003-2006 my team used Lotus Notes as our team wiki. It was so much nicer than an actual wiki if only because there was a tree view on the left and it would highlight in bold anything that had been updated since you last read it.

The tree view also let you see the entire content rather than just a random bunch of pages you might have to spider through to find things.

Any wikis do that? Track individual reading? and which ones have the best non-techie UX where I can easily add images, diagrams, video, without having to jump through hoops?

I'd say Outline, almost fits the bill – individual read tracking is happening in the background but we don't yet surface that to the user – there's an open issue for this and it should get tackled soon, I'd link to GitHub if it wasn't down :)

> Any wikis do that? Track individual reading? and which ones have the best non-techie UX where I can easily add images, diagrams, video, without having to jump through hoops?

OneNote - while not a real wiki in my opinion - was close enough and could do this and I sometimes recommended it to Microsoft centric clients of mine.

Now they are leaving the version I liked behind but some people might enjoy the new version.

I wish One Note allowed markdown blocks, I like how easy you can paste things like pictures and drawings, but it does not work well for stuff like code blocks.

Off the top of my mind tagging is also a weak spot (it insists on users using one of a number of defined tags, and while tags can be added it takes time and you also cannot type them out but have to rely on clumsy nested dropdows for all but the top 10 that can be reached via keyboard shortcuts.)

I'm fairly certain there was more problems but all in all OneNote still used to be a good solutions for smaller companies that was stuck in Microsoft land anyway.

Zim desktop wiki seems to fit you requirements. It's local and designed for a single user, but if coupled with Syncthing works across devices nicely.

Drupal had "books" out of the box, that checks the tree view structure. Not sure about the tracking but it seems it wouldn't be difficult to set up. Disclaimer: it's been a decade since the last time I installed Drupal.

Oh, and "books" were a kind of wiki, in case it wasn't clear.

I started using mediawiki as a personal knowledge base and it's working very well for me.

Working with categories is still on the todo list for me, as I would like something similar to a tree-view, but I'm in no hurry.

Also, I plan to play with mediawiki's API to see how far I can go.

The API stuff is nice. I wrote a Perl script back around '08 that read a MySQL schema and turned it into Mediawiki documentation. It was really handy for providing visibility into a database which had never been documented.

what kind of backups do you make, just regular database dumps?

I take a snapshot of the underlying zfs dataset.

There are dozens of good open-source wikis available. Getting one set up is generally less than an hour's work.

Getting people to contribute can be a problem, but if the workflow is easy and there are things to document, it will work out.

Cleaning up after the fact is usually a bigger problem. Even with full-text search (a requirement, IMO) a large wiki can become a terrible dump. Library science is a real field, and if you can afford a librarian, you definitely want one.

> Getting people to contribute can be a problem This is so spot on. and I don't think it even has to be a problem.

The way people actually work is they 1) write a ton of private notes 2) share a small amount of these notes ad-hoc 3) publish a tiny amount of this to a wiki

To make knowledge more available, the key is to streamline these steps.

Building an app that's grounded in this workflow. Would love to hear the community's feedback on it.

[0] https://bytebase.io

> We experimented with TiddlyWiki. [...] But its non linear organization makes it super unintuitive and confusing.

The main reason I like TiddlyWiki is precisely because it is so simple and easy to use.

Having used a variety of different self-hosted wiki platforms, I found that a self-hosted TiddlyWiki behind a server is perfect for my needs.

TiddlyWiki is ideal for a few scenarios I work on.

1. It's great as a notebook for organizing a creative endeavor like tabletop roleplaying. 2. Its tagging querying capabilities are robust. So robust that I've had success using it to tag media and run complex queries (e.g., select all items having tag1 and exclude items having tag2 and exclude items with value "value1" for key "key1") to where I can use it to manage media

For a small startup team, we now simply do this as Markdown files in our monorepo.

Some such Markdown files correspond 1:1 with code, and (for things like devops processes with a script component), are named the same, or with the same codename, often with just the filename extension differing. Other Markdown files have names like `ops/aws.md` and `20200713-foo-braindump-meeting-notes.md`.

Normally, these are in the git main branch (unless some documentation addition/change is really tied to changes in a development branch).

Just putting it in the repo means one fewer place people have to look (or not see) for important info. GitLab handles all the version-preserving, awareness of changes, etc.

I usually use GitLab Web IDE for quick changes, and my favorite file editor for bigger changes.

I do this after previously using wikis for key information, and decided that the monorepo is simpler, and seems more likely to be kept updated. (I previously loved wikis, and wrote an Emacs mode for one of the wikis when I used it at a well-known company, but I'm liking the monorepo approach even better for the current startup. https://www.neilvandyke.org/erin-twiki-emacs/ )

If you're already using Google docs internally then https://youneedawiki.com/ is a great front end for a quick and easy wiki

If you like low-tech https://dokuwiki.org (PHP, no-DB).

Been using DokuWiki for personal worklog and team notes for ten years. Love it.

I appreciated the design of Outline, until I looked at their website and found that... it's a complete rip-off of Notion?

I've been using Notion for a while, and the commands/block mechanism has been bothering me the most. I don't think it's the way forward for WYSIWYG markup editors.

Others have already pointed out that outline is not really open source, so I will just link to the one alternative that worked for me as a self-hosted, open source (straight AGPL) alternative to Confluence: https://documize.com

Also worth noting that Outline's license seems to come from the future:

  Change Date:          2023-07-03

That's the date when the licensed software becomes GPL-compatible. That's the main feature of the BSL.

[Bookstack](https://www.bookstackapp.com/) has been working very well for us. Lots of great features and good UI. Also it integrates with LDAP and is open-source.

I looked into self-hosted wikis for our team earlier this year. Outline looked very promising, but as the author here mentioned, the documentation was indeed lacking. It seemed to me that they're more intent on pushing their paid plans.

Ultimately we landed on BookStack (https://www.bookstackapp.com/) and people in our org love it. Deployment instructions were pretty easy to follow for someone who doesn't do many server deployments, the UI is great, and the feature set is sufficient for our needs. Plus, the lead developer is extremely helpful in answering questions on Discord.

BookStack creator/lead dev here. Great to hear your users like the platform and that installation was smooth. Hope the platform works well for you going into the future.

Thanks for creating such a great product. After trying (and being dissatisfied) with many different self-hosted Wikis, we stumbled on BookStack - and never looked back.

Interesting. I am currently building a personal self-hosted knowledge base program that uses ElasticSearch to find and organize your data but is also synced into your filesystem with markdown files. So you create a new file in your data/ dir and it will automatically create a new search index that you can view in the software's ui.

It also allows you to have bookmarks where it actually downloads the contents of the bookmarked webpage to make sure it's preserved on your own system.

Quite surprised it hasn't been mentioned here yet, but Wiki.js [0] is absolutely phenomenal. We use it in our research group as a team knowledge base, using LDAP authentication and scheduled backups to our GitLab instance. It's open source software that, in another era, we would have paid $10k for a license.

[0]: https://wiki.js.org

Has wiki-style linking been added yet? I gave it a trial run for several users and was baffled by the lack of linking features (short syntax, autocomplete of existing paths, highlight non-existent endpoints) which I consider part of the essential functionality of modern wiki software.

You can link to another page by selecting from the list of existing pages.

Why do you want to link to a non existing page? You can create an empty page first and link to it.

It's too bad the author doesn't demo the admin panel as I didn't figure out how good it was until I installed it myself recently.

I for one have had a huge success for my private note taking as well as my own team's collaboration with BookStack. https://www.bookstackapp.com/

Has anyone used the GitHub wiki as part of a professional work group? Wondering how that went? If you're already using paid github it seems no brainer.

We tried. But github search is such a joke that it's basically impossible to navigate; hence looking for something else now

Try Emvi [1]. We put a strong focus on search.

[1] https://emvi.com/

That's also been my experience. To be fair, most of today's search engines suck really bad. No exact match, no special symbols, no wildcards, etc. The power user had better tools at their disposal back in 1999.

The main problem with Outline is that it does not support collaborative editing. That's a deal-breaker (for our team at least).

Hey hey — I'm an Outline contributor (OS, not part of the company). It's on the roadmap, a big part of the reason for a major recent rewrite of the underlying engine was to set up support for live collaborative editing.

Why do you need slack for a wiki?

Reply on news.ycombinator.com