Mastodawn

Michael Schneider Mar 20, 2025

Johannes Spielmann

“🚀 Easy to install, scalable and secure alternative to Notion, Outline or Confluence”

This! This is how you do it! Public money, invested in initiatives to remove dependence on outside actors by creating open source products with great engineering.

“While Docs is a public driven initiative our licence choice is an invitation for private sector actors to use, sell and contribute to the project.”

Today is a day where I'm proud to be European!

https://github.com/suitenumerique/docs

GitHub - suitenumerique/docs: A collaborative note taking, wiki and documentation platform that scales. Built with Django and React.

A collaborative note taking, wiki and documentation platform that scales. Built with Django and React. - suitenumerique/docs

GitHub

@shezi but why does it have a full-blown k8s as prerequisite? 😞
@bison

xchangeee Mar 17, 2025

@ttk @shezi @bison

does it? at least here is a docker-compose file:

https://github.com/suitenumerique/docs/blob/main/docker-compose.yml

remove the dev dependencies and it looks like a standard django celery deployment to me.

sure, installation.md is an example for how install it on k8s but there is no hard requirement for this.

docs/docker-compose.yml at main · suitenumerique/docs

A collaborative note taking, wiki and documentation platform that scales. Built with Django and React. Opensource alternative to Notion or Outline. - suitenumerique/docs

GitHub

@xchange @shezi @bison but it seems so in the Readme/Install.md.

xchangeee Mar 17, 2025

@ttk @shezi @bison idk, readme doesnt even mention kubernetes and installation.md just provide a helm chart for convenience

Johannes Spielmann Mar 17, 2025

@ttk @xchange @bison

The `docs/install.md` has the documentation for deployment on a k8s cluster in production. That's entirely optional, though.

The main readme documents how to run it locally, and there is the compose file that you can use for dev or local deployments.

@shezi @xchange @bison i click on "Documentation" on the Readme, right at the top. It links to a folder view, with an installation.md in it. It only talks about k8s. If i need external help for finding additional documentation/installation methods, this is clearly a usability bug in the Doc.

@shezi @xchange @bison maybe rename the installation.md to install_k8s.md and add a install_docker.md?

Johannes Spielmann Mar 17, 2025

@ttk @xchange @bison

Should be simple enough for a PR?

Samuel Paccoud Mar 22, 2025

@shezi @ttk @xchange @bison Sorry guys. No excuse for documentation other than: we focused on our instance up to now and just added documentation on k8s install when someone asked for it. We definitely need to work on documentation now and hope the community will jump in.

Johannes Spielmann Mar 17, 2025

@ttk @xchange @bison

I mean, it _is_ right there in the Readme, without clicking anywhere. You could open an issue or a PR if you think it could be better?

Or maybe the documentation isn't for you then? This is an open-sourced internal tool obviously, not a provided service, so their main goal would be documentation for themselves and similar users.

If you have interest and funding, I'd be happy to host an instance for you and then you get to complain about all these things.

xchangeee Mar 17, 2025

@shezi @ttk @bison complaining on mastodon is a bit easier though

xchangeee Mar 17, 2025

@ttk @shezi @bison What I dont understand is why they made OIDC a hard requirement.

From a user POV thats bullshit, django already has a full blown authn and authz system built-in. Requiring a 3rd party OIDC provider just raises the bar for simple deployments and hinders adoption.

Johannes Spielmann Mar 17, 2025

@xchange @ttk @bison

I assume that's because the project is still “paying-customer-first”. If you look at their demo environment, that's integrated with the french government auth suite, so naturally they'd integrate with that.

In any case, it shouldn't be too hard to either modularise that or add an oidc provider into the compose files. In fact, the k8s documentation even contains a keycloak for exactly that purpose.

xchangeee Mar 17, 2025

@shezi @ttk @bison of course it should not be a problem, but now you have keycloack and just another moving part that you have to take care of. which is fine for larger orgs but adds unnecessary overhead for smaller installs.

Johannes Spielmann Mar 17, 2025

@xchange @bison

collab on adding regular user auth? or maybe add allauth and have optional social auth?

xchangeee Mar 17, 2025

@shezi @bison might be a viable path forward, depending on how project governance was setup

xchangeee Mar 17, 2025

@shezi @bison fwiw, they are already using mozilla-django-oidc

https://github.com/suitenumerique/docs/blob/eb23aefd55ecb3eb1b6acfbac5d10ecfe5e4bb84/src/backend/core/authentication/backends.py#L19

docs/src/backend/core/authentication/backends.py at eb23aefd55ecb3eb1b6acfbac5d10ecfe5e4bb84 · suitenumerique/docs

A collaborative note taking, wiki and documentation platform that scales. Built with Django and React. Opensource alternative to Notion or Outline. - suitenumerique/docs

GitHub

Johannes Spielmann Mar 17, 2025

@xchange @bison

as far as I can see, model authentication is also enabled, and they even have a custom user model. Shouldn't be too hard to. expose that as main auth mechanism, or add other mechanisms. I'll have to play around with that a bit.

Johannes Spielmann Mar 17, 2025

@ttk @bison The install instructions are a bit rough, indeed, but they're still far better than most of the stuff I've seen in Enterprise(TM) software.
And, to be fair, if a project brings with it a fully-grown k8s installation, that would make even more sense for hosting in a professional environment.

Samuel Paccoud Mar 22, 2025

@ttk @shezi @bison the choice of OIDC is b/c we are building a full suite. Also a pattern in which I believe as we see more and more SaaS OIDC. Why recode user management in all our projects so painful and suboptimal.