Hosting my own wiki

July 2022 ยท 4 minute read

I like taking notes when I’m building and/or learning things that require a lot of my time. Inevitably, I revisit those things from time to time, and I’m always happy when there are breadcrumbs from my past self to assist my memory and help me pick up where I left off.

One realm where I appreciate the writings from my past self is in my home lab. I run several services on single-board computers (i.e. Raspberry Pi or similar) on my home network, and I expose some of those services to the internet. It’s useful to refer to write-ups that I made while configuring or building on those services.

Another realm where I appreciate personalized reference materials is in the planning of big backcountry adventures. Prior to most of these adventures, I spend hours researching routes, conditions, and blog posts of other mountain athletes. If I want to revisit an area or share my knowledge with others, it’s useful to have thorough notes on the topic from my past self.

While I love taking notes, I haven’t found a note app or service that I enjoy or that I trust to keep me satisfied in the long term. I despise vendor lock-in, especially with subscription-based services. I’ve been using Github repositories for note-taking for a couple years now because it works, it’s simple, and markdown files are portable to many other platforms. I decided that it’s time to evaluate other platforms that might enable a better experience for myself now and in the future.

Requirements

I wanted a few things out of a note-taking solution:

  1. no subscription fees
  2. automated backup to plain text (in case of failure)
  3. hierarchical and intuitive organization
  4. a beautiful, easy-to-use interface
  5. Markdown-based editing
  6. all features available on desktop and mobile (web-based OK)
  7. the ability to easily export or share

Candidates

Based on my requirements, I looked closely at the awesome-selfhosted note-taking apps and the awesome-selfhosted wikis.

The final candidates that I evaluated closely were:

Choosing a solution

All of the final candidates are fantastic apps. However, the only one that met all of my requirements was WikiJS. Joplin was a very close second, but the ultimate kicker was that the plaintext backups of Joplin are not organized with filenames that allow one to navigate the backup with ease. In other words, migrating from Joplin to any other solution or platform in the future would be a very significant hassle.

WikiJS, by contrast, can be linked to GitHub in order to sync content in markdown, while preserving page names and folder hierarchy. If my WikiJS server fails, I can simply browse the backup repository in GitHub, and I can move and transform those notes to any other platform with ease. Here’s a link to WikiJS’s Auth page in the WikiJS app, and the same content synced to the backup Github repository.

A screenshot of Chris's wiki

Chris's personal wiki

There are two downsides to WikiJS that I’ve found so far. The first is that it’s not an offline-first solution. I need internet connectivity to access my notes. Since it’s a web-based app, there’s no concept of background syncing to a native desktop or mobile app (Trilium and Joplin are both offline-first). The second downside is that the database doesn’t handle refactoring of the hierarchical note organization very well. I’m glad I discovered this early so that I don’t get frustrated with it later… to avoid it, I’ll put lots of thought into naming folders. Refactoring folder names is best done by reinstalling from scratch and restoring from the .git backup after it has been refactored.

A screenshot of Chris's wiki backup in Github

Chris's wiki backup in Github

Additional benefits

WikiJS offers additional benefits, such as automated LetsEncrypt SSL certificate provisioning, many authentication mechanisms (including a local user database), fine-grained access control, a supported docker image for easy hosting, and a healthy open-source community with active development. It’s neat that I have the option to invite collaborators for certain pages or sections of my personal wiki.

Self-hosting

The last step in this process was to start running WikiJS at home and to make it accessible from the internet, but also lock it down with authentication requirements. Those steps, at a high level, included:

Conclusion

I hope this inspires someone out there to self-host their own wiki! WikiJS is awesome and powerful - it’s a full-featured wiki platform, after all. I look forward to adding to it as my personal knowledge base for years to come. Thanks for reading!