Outline: Self hostable, realtime, Markdown compatible knowledge base | Hacker News Reader

Outline: Self hostable, realtime, Markdown compatible knowledge base

github.com

126 pointsmsk-lywenn64 comments

Just be careful that while it is self-hostable and the source is available, it is not open source [1,2]. If this is something important for your consideration before using it.

[1] https://github.com/outline/outline/blob/main/LICENSE

[2] https://fossa.com/blog/business-source-license-requirements-...

So if I understand this correctly, I have _no_ license to use the software until late 2027? Including installation and contribution instructions in the README seems deceptive, since neither can be done legally.

I don’t think that’s right. You have no license to use it to host a commercial offering to third-parties, until the BSL rolls over to fully open source.

But the license explicitly allows free self-hosting for your own company / employees.

You cannot use it in production. I'm actually curious how this license works for them.

If they get a contribution without a CLA, then they themselves can hypothetically not use it in prod too?

Edit: you can actually use it for your own, but you can't compete with their offering until the date mentioned in the license:

> 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.

I missed that, I guess that counts as a license. But it's fearfully short, even MIT is longer than that. But there's no grant for contributors, so you have to violate the copyright to make a contribution, even with a CLA (which is a license from the contributor to the rights-holder, not usually the other way round).

I thought it is licensed under BSL 1.1 until 2027, after that it will become Apache 2. You can install and use it as long as you don't provide commercial service with it.

The license allows all use _except_ competing with the cloud offering – you can run in for personal use, or your company without issue. This style of BSL license has become fairly common to protect the business model that allows the software to remain under development.

BSL can be quite open-source-like or extremely restrictive depending on the additional use grant. For example this project seem to allow most things besides offering a hosted version as a SaaS, but the BSL itself disallows any production use and "production" as a term is not defined.

I would be weary of even setting up a personal instance of BSL software for anything besides development or evaluation since it could be counted as "production".

is BSL frowned upon? is it a bad choice if I wanted to provide a service and make source code available for those who want to self-host for free?

Generally what's frowned upon is using phrases like "open source" or words like "open" and "free" to describe source-available licenses that are not open source per the Open Source Initiative definition[0] or libre (versus no-cost). There are lot of people (me included) who take a very pedantic view of these terms. Makers of proprietary software sometimes use these terms to unfairly exploit the goodwill associated with actual free/libre and open source software licenses.

A lot of people don't regard BSL-licensed (and other source-available licenses) as much different than any other proprietary license. There will always be the people who object to any proprietary licenses. You'll always offend those people by using a proprietary license. Using precise and correct language with a source-available license like the BSL won't offend those who take open source and free software terminology seriously however.

[0] https://opensource.org/osd/

Corporate bootlickers frown upon developers restricting corporate uses of their software.

The OSI is run by corporations, for corporations, and has successfully run propaganda campaigns to shit on source available licenses purely on the basis of them not being bootlicker enough.

No. There is absolutely nothing wrong with restricting how corporations can use your code. Fuck the OSI.

Some of us in "open source" are also interested in helping independent developers (including arrangements such as worker-owned cooperatives) gain access to the means of production they can also use to make a living from. BSL excludes small/independent/worker-owned orgs, not only the big and exploitative corporations. If everyone moves to BSL then only those who already have access to capital will be able to afford to build software on top of non-free foundations - a gap which widens with time and a kind of "pulling up the ladder behind you" practice deployed at scale

There are other interesting licenses for this issue that exclude exploitative corporate use without cutting out e.g. worker-owned cooperative use [0] but nothing currently in popular use, and these may be less desirable in "exvestment" opportunities such as linux where corporate investment has vastly contributed to public goods with values that are not represented by those corporations own goals and otherwise wouldn't exist given current society

[0] https://anticapitalist.software which encourages free reuse by for-profit (or otherwise) entities in markets, but excludes exploitative use. I just posted the link to discuss.

> 2. The User is one of the following: a. An individual person, laboring for themselves b. A non-profit organization c. An educational institution d. An organization that seeks shared profit for all of its members, and allows non-members to set the cost of their labor

> 3. If the User is an organization with owners, then all owners are workers and all workers are owners with equal equity and/or equal vote.

> 4. If the User is an organization, then the User is not law enforcement or military, or working for or under either.

I think you’re assuming things that I don’t actually believe.

The OSI are scum because of their incessant propaganda against source-available and constant attacks of developers that aren’t being bootlickers.

If a developer wants for their code to be free for corporate use. Fine. If they don’t, also fine.

I am for developers getting paid for their work that they want to be paid for, and if they believe that licensing to corporations differently helps them achieve that, then so be it.

I create source under both open source and source available licenses depending on what it is.

Sounds good

What an ambiguous mess.

> Change License: Apache License, Version 2.0

> 1. To specify as the Change License the GPL Version 2.0 or any later version

So which is it?

> Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License

That text was was added in a commit on March 27, 2020. That commit also lists a change date of "2023-03-01". So when was the "first publicly available distribution"?

---

Can we please just stop wasting each other's time with this nonsense? Clearly none of us is enjoying the exercise.

Developers laugh at lawyers who think they can write code, and lawyers laugh at developers who think they can write contracts.

The truth is there are probably more lawyers who can write good code than developers who can write good contracts.

If you ever find an IP attorney who studied engineering as an undergraduate (and was good at it), hang on to them, they are the best. Mine saved me from a single mistake that would've cost more than 100x what I paid him (and several other less-spectacular disasters).

The concept of a "good contract" can be argued to death. I don't think that argument needs to overwhelm my point: this is an incoherent contract. It doesn't require any expertise to say so.

Per the license itself:

    Additional Use Grant: 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.

Then you come across Trilium and drop the mic

[0] https://github.com/zadam/trilium

I just recently came back up from a deep dive through knowledge management systems, and Trilium is what I settled with. It might not look like much on the surface, especially compared to the bling and hype of the VC baked alternatives, but once the basics click (everything is a note, notes can have inheritable attributes, you build types of notes like in OOP inheriting from base notes by leveraging the hierarchy, instances are just notes that have a template relationship to the model notes and can be stored anywhere), it's a damn elegant and powerful tool.

Definitely underrated/highly recommended!

Trilium or Obsidian are not comparable to Outline, because they're single-user with no accounts or access control.

Outline is not comaparable to Trilium because you cannot extend Outline by simply writing your extension code as a document that is inherited.

Or maybe they are comparable because they have slightly different feature sets..

Maintainer here, happy to answer questions and glad to see it get some attention on HN :)

Outline is a bootstrapped business. The software is used by thousands of teams, including government agencies, universities, and companies from startups to large corporates.

Does it support video uploading with native html video tag? (Cloud version)

Yep, cloud and self-hosted both support embedding video (native tag) as of a few versions ago.

So this is the new generation of Javascript self-hostable wikis inspired by Notion. I remember in the late 2000s, most were PHP-based, with Twiki being an exception: it was Perl-based and also had a powerful wiki/database combination [1]. But it was not intuitive to use. That's what Notion nailed a decade later.

Now All the new (OSS ?) Notion clones like Outline are still deficient in that second database aspect. I hope we are eventually getting there.

[1] https://twiki.org/cgi-bin/view/Codev/StructuredWiki

Give Trilium a shot (as to why, I commented elsewhere in this thread in response to someone mentioning it), it's not super flashy at first sight, but in my experience, it gets the database aspect right.

When I was a younger developer I thought tooling solved all problems. As I grew more experience I slowly changed my mind that some problem spaces require not only tooling but process change. I am firmly in the camp that you don't need yet another documentation tool. The problem is a human/process one, documentation/knowledge bases need to be part of the process. As long as you can search it and its easy to update/create, I don't think the tool is solving much for you.

Friction frustrates processes though. If working with a tool is constant pain, then the process is going to suffer.

Totally agree. Have definitely seen a bad tool used but largely the problem in my experience has been human.

> When I was a younger developer I thought tooling solved all problems. As I grew more experience I slowly changed my mind that some problem spaces require not only tooling but process change.

Lets take it one step further.

You start out thinking everything is tooling. As you grow more experienced you realize that everything is process. As you grow more experienced still, you realize that the world is really messy and rarely ever anything is everything.

Of course the world is messy and there are many variables. I still sit in the camp that documentation is a human problem that requires both tooling and process. I wish Outline luck but on the documentation side, its largely a human/process one.

> both tooling and process

so better tooling helps then?

Sure? The problem is largely a human/company culture/process problem and sure tooling can help remove friction but it does not fix the larger problem.

It's nowhere near as featureful as Outline, but I wrote my own Markdown knowledge base thingy in Python. It is web-based and geared toward single-user (or _very_ small team use) but it's Apache licensed and has no commercial tie-ins. Super easy to deploy as long as you know how to layer some rudimentary authentication on top of it.

https://github.com/cu/silicon

I just spun up a self hosted instance this past weekend, and while its fairly decent it doesn't seem to hit the mark compared to Notion (which I use at my day job). There's just a bit too much friction in creating pages (you need to click "publish" on every page you create), no /page command to quickly jump into a nested page, and.

I'm more excited by Affine (https://affine.pro/), though their self hosting support seems to be neglected, and it has the same "not actually open source" issue as Outline.

Very interesting! I wonder how much friction there would be in migrating the data from outline to affine.

Have you tried affine? If you did, how is the performance? Something I like a lot with outline is that it's super reactive and fast, even on low end servers or clients. Only the startup time is bad.

What do they mean by "neglected self host"? Is it just because the docker packages are not up to date? Can't we just build and run what's on github?

Improving how drafts work is near the top of the roadmap, one of Outline's main value props is it's speed –so definitely want to reduce the friction here.

Have been using it for over 2 years now, for a team of nearly 80 people. Love it - both self-hosted and as a service. Very quick to respond to issues on github, and the tool keeps evolving.

After years of a personal PIM (in org-mode and experiments with DokuWiki) I've concluded that to manage notes we do need some kind of structure, a free graph will became unmanageable after a certain quantity of notes. That structure is simply a chronology, since the flow of time is a thing common to pretty anything.

My actual setup is:

- daily notes, meaning when I want to write something I'll put in today note, no thinking about where to archive, under a common year root, with a monthly recap;

- binders notes, who transclude or link single notes inside a daily one (headings in org-mode lingo) assembling and arranging them as I wish, under a "live archive" root;

- not current anymore binders under a "dead archive" root.

Such structure so far allow me to store and retrieve pretty anything and always find and consolidate things, something I can't do with ZK, LYT, PARA and other common techniques.

That's to simply say a thing: we do not need the nth wiki style slick UI app but something that offer:

- live rendering, like org-mode or even Zim, no separation between source form and rendered form, because that's makes easy write and edit things;

- transclusion (TiddlyWiki, Dokuwiki+Include plugin (a bit limited), BookStack, org-transclude albeit a bit slow and limited) because to create our library of babel (cfr. Conrad Gessner ~1545 but also many others) we must been able to take atomic notes AND COMPOSE THEM in various ways;

- attachment support (a decent one, org-attach it's ok, but only because it's bare simple so it's easy to hijack, Paperless it's damn slow but flexible enough and so on);

- ability to INTEGRATE anything. In this regard ALL modern software can't win, simply because modern systems are designed for commercial reasons, not like classic ones where the OS was a single user-programmable application, and an application is just code added to the OS. The web try to recover DocUIs and composability but it's really limited. We can let's say link GMail threads in notes, but it's far from link a notmuch-accessed local mail linked in org-mode;

- offering by default a chronology, even Zim offer that to a certain extent with the builtin calendar.

Without the above just write some new and uncertain project fully knowing that migrating contents is far from being easy or granted and it's a very painful thing, is IMVHO a waste of time...

Our team quite recently switched from GitLab Wiki to (a self-hosted) Outline.

The initial impressions were very good but after using it daily for a couple of months I really don't like the default theme(s) (dark nor bright) as the formatting options are very limited and the end result is less readable documents. You can probably tweak these things but we haven't gotten there yet.

The search is great and you can set explicit "edit mode" in your profile settings so both reading and editong becomes clearer.

It was a mess to set up the first time. It's getting better. With been using it for about a year and we're very happy with it.

Just curious: any features (from your point of view obviously) making it a better choice compared to i.e free version of GitLab?

I've never used gitlab so I can't say. We use gitea. I thought gitlab was some kind of github alternative, like gitea. It's a wiki too now?

Well, both GitHub and the GitLab have wiki functionality. Not on par afaik with more familiar MediaWiki but nevertheless good enough for not just software project documentation. No experience with transforming these wikis into stand alone web sites with different styles etc.

what are other good opensource alternatives?

Your question implies that Outline is opensource. It's not. I reread your question as "What are good opensource alternatives?" and it makes sense.

My org has used mdBook: https://rust-lang.github.io/mdBook/ (That link is itself a rendered mdBook, so that'll give you an idea of the feature set.)

(While it's definitely a Rust "thing", if you just have a set of .md files, all you need is a "SUMMARY.md" (which contains the ToC) and a small config file; i.e., you don't have to have any Rust code to use it, and it works fine without. We document a large, mostly non-Rust codebase with it.)

This is pretty fast. Wow. Question for you. Does the search feature works out of the box, or does it need a plugin?

It works out of the box.

It's pretty basic: mdBook just emits a JSON file containing the entire search index. The rendered book's JS then fetches that index, and uses it to implement the search client-side. (So that the whole book — search index included — can be served statically.)

It usually finds what I'm looking for pretty easily, as long as I pick a good search term. It isn't the best search, though, and sometimes I'll just revert to `rg` in a CLI if it's in the way.

The things I think people in our org didn't like: some people really really want a WYSIWYG editor, some people don't want to have to deal with making a commit to update docs¹, some people didn't like that the ToC enforced a hierarchy (and wanted a more Wiki style thing²).

(¹I'm in the camp that docs should be reviewed through normal processes, though … I've seen a lot of instances otherwise of incorrect docs getting through, and/or just bad/nonsensical docs getting written. Our org's code review policy at the time most of the docs were written was "you should get a review, but a bot will auto-stamp it if you want to opt-out and then it's just on you", but nowadays we require review, but I don't feel like the reviews are rigorous.)

(²to me a ToC is a wiki superset: if you want wiki behavior … just create a single level in the ToC, and all docs are at the same level. Alphabetize them if you don't want to think about the order. We call this section "Misc" in our ToC, but we do break some other parts out into more full-fledged sections. mdBook enforces that docs must appear in the ToC, which I think is a good thing for discoverability.)

What are the advantages over Obisidian?

- Team oriented

- Integrated with Slack

- ?

I haven't really used Obsidian, but I'd imagine that the team aspect is the main advantage plus realtime collaborative editing as part of that.

Outline is also used in a lot of orgs where the users are less technical, I'd imagine Obsidian could be quite intimidating in comparison.

What are the advantages of Figma over Illustrator?

- Team oriented

This is more of a self-hosted collaborative alternative to Notion than a personal note taking tool like Obsidian.

Could be used to host public pages for tutorials/guides for a SaaS?

You can yes, in fact Outline's own documentation are hosted on Outline:

https://docs.getoutline.com/s/guide

Reply on news.ycombinator.com