Every team has to keep its knowledge in order, it is mandatory to have an internal documentation that is well organized and easy to access. In this post we are going to show how to create a secure private knowledge base with an open-source tool, let’s go forward to it!
Why a knowledge base tool?
There are a lot of excellent answers to this question, but I wanna show you a picture that summarizes why a knowledge base tool is mandatory:
When we started writing down everything we knew we thought that Google Drive was the solution; that escalated pretty quickly into murderous intents. Google Drive was, obviously, an awful choice as a knowledge base tool because it gets messy pretty quickly and it costs time (while the purpose of a knowledge base is to save time).
We also understood pretty quickly that there are some features that we needed no matter what: for example a simple search feature. If you are looking for a particular keyphrase and you don’t even remember the name of the file it makes you frustrated. The point is:
- The team has a global knowledge that needs to be shared amongst all the members
- This knowledge has to be easily accessible and well-organized
- A tool is needed
Basic features for a knowledge bases
In this paragraph we are going to talk about the features that are essential in the knowledge base tool we were looking for:
- Search function (amongst all the docs): the KB tool needs to have a global search feature that allows to find the correct document starting from a keyword
- Self-hosted (and open-source) solution: the KB tool has to be self-hostable because we wanted to have a knowledge base that was accessible only locally; we also wanted an open-source tool because that’s the most beautiful code there is (and we can look into it and maybe make some improvements).
- Integrated Editor: we don’t want to lose time with a lot of tools, we want to be able to edit the documents with the same tool.
- Markdown compatibility: and we want to use Markdown because we like it and we write a lot of documentation in Markdown.
Nice to have features
The previous features were the must-to-have, we could not live without them. Of course, there were other features we would have really liked (even though they were not essential):
- Real-time collaboration: on this one we have to be honest, the real-time collaboration on Google Docs is pretty neat. It would be interesting to have something like that to work in group on some docs.
- API: we like APIs, we really do. It could be interesting to automatize some tasks or integrate with some other tool.
- Integrations with Google Doc: we decided to leave the Google Docs realm for the knowledge base, but we still use Google Docs for other stuff. So it would be handy to have such integration.
And so our research begun to find a perfect match to these requirements. Unlikely some other stories this one has a happy ending.
Outline: the (open-source) solution to our problems
Is name is Outline, and we just love it.
An overview
Outline has all the must-have requirements we were looking for and even more. Its editor (which is integrated) is Markdown-compatible, the search function is globally accessible (through a handy shortcut: Win+K) and it is open-source. Let’s see the features in detail.
Slack integration (and more)
This knowledge base tool can be integrated with Slack, which is perfect because nowadays Slack is the most used collaboration tool for remote working. The integration allows receiving updates on a channel when a document is created or edited and allows the user to search on the knowledge base directly on Slack using the /outline command.
Slack is not the only tool integrated, there are a lot of interesting integrations:
- Google Docs
- Alfred
- Zapier
- Figma
- GitHub Gist
- YouTube
- Vimeo
Powerful editor
The editor is quite powerful. Besides being markdown-compatible has the ‘/’ magic word that works as a toolbar.
On the other hand, there is some missing stuff, like the ability to add headers and footers to a document. It is not even possible to export a document in PDF (the workaround is to print to PDF the page).
APIs!
There APIs for almost everything. This is quite useful not only for developers but also to automatize some tasks based on the content of some knowledge base documents (we don’t say more, there could be a post on this too).
How to setup
That was just a quick overview of that Outline can do for you. We are not going into the specifics of every feature because this is not the purpose of this post. We said that this knowledge base tool is open-source and therefore it can be self-hosted. This is exactly what we have done with our knowledge base which is now accessible only for those who have access on our VPN. As you may have understood from our previous posts (this one, this one, and this one) we really love containers. Therefore we have chosen the container-based setup. To self-host Outline we also need the following:
- Postgres >=9.5
- Redis >= 4
- AWS S3 bucket or compatible API for file storage
- Slack or Google developer application for authentication
- NGINX (optional)
On the Outline GitHub page there is a short tutorial on how to self host the tool, but it is not very helpful. Luckily there is always some angel that helps us, in this case, we found a repo that contains a little script that automatize the creation of a docker-compose.yml to self-host Outline. This means that in 5 minutes we can set up our knowledge base tool and live happily ever after.
Conclusion
Having a knowledge base is important for a team and having a private one could be mandatory for someone. In this post, we talked about the importance of a knowledge base and the minimum requirements for a good knowledge base tool. In the end, we showed an open–source solution that could work for almost every team and showed how to self-host it.
As you may see this post is quite different from the other ones we’ve posted before, but also being organized in a team is very important because disorganization leads to confusion, and that could be risky too.