Configuratie als code opties voor Discourse?

AI-generated summary

The discussion explores options for managing Discourse instance configuration as code, aiming to enable declarative management of categories, tags, policies, and content via version control. jrack initiates the thread by asking if a pattern exists for maintaining site organization through a declarative format, allowing technical users to propose changes via Pull Requests (PRs) rather than manual UI updates. simon suggests using the API to script configuration changes triggered by PRs, noting that while feasible, it may be more complex than manual UI management.

mbauman highlights the need to manage themes, components, and site texts via GitHub. Moin clarifies that themes and components can already be imported from and updated via Git repositories. However, mbauman emphasizes that Site Texts (like guidelines and FAQs) remain difficult to manage this way. While Moin suggests hosting these as wiki topics or external URLs, mbauman notes limitations with the FAQ URL setting.

merefield points to an existing topic on controlling site settings with themes. In response, mbauman shares a rudimentary GitHub Action for updating site_texts via the API. david clarifies that Discourse does not plan to release a reusable tool for this, but references their internal sync code. Finally, mbauman releases DiscourseAdmin.jl, a Julia-based tool using GitHub Actions to manage site texts, topic editing, and moderation flags via the Admin API, enabling community-driven norm definition through familiar open-source workflows.

Dus niet over de instantie-implementatie met db etc.

Bestaat er een patroon voor het onderhouden van een instantie met een declaratief formaat? Categorieën, tags, beleidsregels, enz. Ik dacht dat het fijn zou zijn voor onze technische gebruikers om wijzigingen aan te bevelen via PR’s in plaats van via discussies en handmatige uitvoering, maar ik zag geen plugin of ander “as code”-hulpmiddel dat gericht is op de organisatorische configuratie van Discourse.

5 likes

I think the expectation is that sites will use the pre-seeded Contribute > Site feedback category for this. Its description is: “Discussion about this site, its organization, how it works, and how we can improve it.”

That’s an interesting idea. What benefit would it have over just having users suggest changes in regular topics? Is the goal to have a way of keeping track of changes that have been made to the site’s configuration over time?

Site settings, categories, tags, policies etc, can be configured with the Discourse API. It might be possible to have a script that managed your site’s configuration via the API in a git repo. The script could be run when a PR on the repo is accepted. From my point of view this would be more difficult than manually making changes to the site’s config via the UI though.

2 likes

10-4 on the Category. For now I was crowdsourcing a bit on an existing pattern. For me its getting that gitops style community engagement so landed with this one, but can punt it over to the other if it helps.

And yeah we use a bit of config as code for a lot of things so you get the clean revision control, deterministic roll back, clear change review, etc. GUI based changes are not bad (and what we do today via community feedback loops) but its a manual operation and the decision context can be lost to time. And the org constructs exist in the middle between the infra and the actual dialog so its not a deployment or rehydration thing.

And yeah PR based triggers (or even an Issue) can fire off a runbook that figures out the proposed change and does the operation. Doing the diff analysis and linting can be difficult which is why i was poking around to see if anyone had tried it yet. The ask is definitely square in the nice to have camp and only might resonate with a certain demographic.

2 likes

Ik (en ik ben er vrij zeker van dat onze programmeertaal-community) deze mogelijkheid absoluut zou waarderen. Ik zou in het bijzonder graag thema’s, componenten en site-teksten willen beheren in een GitHub-repository waar mensen gemakkelijk pull requests kunnen indienen. Algemene site-instellingen zouden ook fijn zijn, maar het zijn juist die drie dingen die het meest pijnlijk zijn om te onderhouden in een web-UI.

Als dit vandaag niet mogelijk is — en ik denk van niet, althans niet voor een betaalde/gehoste instantie — zou dit dan kunnen worden gehercategoriseerd als een feature request? In het bijzonder zou het geweldig zijn als thema’s en componenten gewoon naar een git-repo zouden kunnen verwijzen.

Of, als alternatief, heeft iemand de hierboven voorgestelde GitHub-triggerintegraties gebouwd?

1 like

Immediately after writing that, I thought to double check the UI. It seems this is possible — at least to create/import a theme from a git repo! How does this work for updates? Is it able to pull new commits? I found Installing a theme from a private Git repository, but that doesn’t discuss update.

Is it possible to convert an existing theme or component to track a git repository?

You can export a theme, upload it to a repository, and install that.

All remote themes have a section at the top where you can decide if you want it to update automatically when Discourse is updated. Furthermore, there is a background job that checks if a more recent version is available, and you can check for new updates manually too. When a new version is available, the button offers to update the component.

You can also find that information in the guide about Installing a theme or theme component.

In case you haven’t already found it, there is also a tutorial about theme development

3 likes

Dat is geweldig, bedankt @Moin! Dat dekt twee grote bronnen van de aanpassing van onze site.

Ik zou nog steeds heel graag git willen gebruiken om de Site Texts te beheren, aangezien veel daarvan (zoals de richtlijnen en FAQ en dergelijke) lang, niet-triviaal zijn en open source kunnen zijn voor input en beoordeling door de community.

De andere site-instellingen zouden fijn zijn om te hebben, maar zeker niet zo cruciaal.

Those are usually base on a topic in the staff category. I think you can move them to a different category and make the post a wiki. Then your members can edit them.

You can also use the FAQ URL, Privacy policy URL and ToS URL site settings and host these somewhere else

1 like

Yeah, but the FAQ URL setting unfortunately has other behaviors that makes its use very much self-defeating for this purpose.

Just to point out that it is clear that it is already possible to manage content in source control, take a look at this topic, it’s maintained on GitHub:

at the bottom:

though I’m not sure if this functionality has yet been released or announced (or if that’s intended)

1 like

I’ve started fiddling around a GitHub action that submits updates to the site_texts section of the admin panel via API. It’s pretty rudimentary at the moment (and is failing for big values with a 422 for some reason), but it’s promising.

https://github.com/JuliaDiscourse/customize

Definitely needs more work.

1 like

We don’t currently have any plans to release it as a re-usable tool. But you can check the code for our sync here. It leans on all the normal Discourse REST APIs, including a data-explorer query (details here).

2 likes

I’ve resurrected the work I mentioned here last year with the help of the ever-improving robot:

It’s in Julia (of course), but there’s really not much code here at all thanks to Discourse’s (largely) straightforward admin APIs. It’s two GitHub actions that hit a few endpoints to support:

  • Site text customization
  • First-post-of-a-topic editing (targeting Guidelines, TOS & privacy, but is extensible)
  • Moderation flags

The goal is to let our open source community use the open source tooling and consensus processes they’re familiar with to help us define our collective norms.

You do really need to take care of that admin API key of course… and also want to make sure you don’t accidentally enable a new endpoint (by merging to main) that could reveal some sensitive setting on its first sync.

1 like