Category Archives: 000FLA

000FLA, 02 - Administration

Admin Panel

Welcome to the NZRT Wiki Podcast. Today we’re looking at Admin Panel.

So, if you’re managing a Flarum forum, the Admin Panel is your control centre. You can get to it by navigating to your forum’s address and adding slash admin at the end. Keep in mind that you’ll need to be a member of the Admin group to get in — it’s not open to regular users.

Let’s walk through what you’ll find inside. There are nine main sections, and each one handles a different part of running your forum. First up is the Dashboard, which gives you a quick snapshot of your forum’s activity — things like how many discussions exist, how many posts have been made, your total user count, and how many users are currently active. Think of it as your at-a-glance health check.

Next is Basics. This is where you set the foundational identity of your forum — the title, the description, a welcome banner for new visitors, your default language, and your default theme. If someone lands on your forum for the first time, Basics is what shapes that first impression.

Then there’s Mail, which we’ll come back to in a moment because there’s a bit more to cover there.

After Mail, you’ve got Users. This section lets you browse through your entire user base, edit individual profiles, change what group someone belongs to, suspend an account if needed, or delete a user entirely. It’s your main people-management hub.

Groups sits right alongside it. Here you can create new groups or edit existing ones, and you can assign each group its own colour and icon to make them visually distinct.

Permissions is where things get a bit more nuanced. You set per-group permissions here — so you’re deciding what each group of users can and can’t do on the forum. You can also set permission overrides at the tag level, which means certain tags on your forum can have different rules from the rest.

Appearance gives you control over the look and feel. You can choose a theme, add custom header or footer HTML, and write custom CSS if you want to go further than the built-in options allow.

Tags is where you manage your forum’s topic categories. You can create new tags, edit existing ones, reorder them, set colours and icons, and even nest tags inside each other to create a hierarchy.

And finally, Extensions. This is where you turn installed extensions on or off, and access their individual settings when they have them.

Now, back to Mail. Flarum uses email for three main purposes: verifying email addresses when someone signs up, handling password resets, and sending notification digests if you’ve got that enabled through an extension.

When it comes to how email actually gets sent, you have a few driver options. You can use SMTP, which is the most common setup for production environments. You can use PHP’s built-in mail function. There’s a log driver, which is great for development — instead of actually sending emails, it just writes them to a log file so you can inspect what would have been sent. And there are also drivers for Mailgun and Amazon SES if you’re using those services.

For a typical SMTP setup, here’s what you’re configuring. You’d set the driver to SMTP, then provide the hostname of your mail server, the port number — commonly 587 for TLS — and the encryption type. You’d then enter your username and password for the mail account, and set the from address, which is what recipients will see as the sender. Once you’ve filled all that in, you can send yourself a test email right from Admin, under the Mail section, to confirm everything’s working.

One thing worth knowing is that Flarum doesn’t have a built-in maintenance mode toggle. There’s no button you can flip to take the forum offline while you work on it. If you need to do that, your options are to temporarily rename or remove the main index file in the public folder on the server, or to set up a server-level redirect that sends visitors somewhere else while you work.

Now, if you’re comfortable working on the server directly, there are also some command-line tools available. You run these from the forum’s root directory on the server. There are four key ones to know about. The first clears all caches, which is useful after making config changes. The second republishes extension assets — things like stylesheets and scripts that extensions add to the front end. The third runs any pending database migrations, which you’d typically do after installing or updating an extension. And the fourth just prints out version and extension information, handy for quick diagnostics.

That covers the Admin Panel from top to bottom — from the dashboard overview and core settings, through mail configuration and user management, all the way to the command-line tools you might need when working server-side.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

000FLA, 01 - Core Concepts

Discussions Posts

Welcome to the NZRT Wiki Podcast. Today we’re looking at Discussions & Posts.

If you’ve spent any time in the NZRT forum, you’ve probably used these two concepts without thinking much about them. So let’s break down exactly what a discussion is, what a post is, and how they relate to each other.

A discussion is essentially a thread. Think of it as the container — the topic someone starts. A post is a reply inside that thread. And here’s the key detail to keep in mind: the very first post of any discussion is actually the body of that discussion itself. So when someone creates a new thread and writes an opening message, that opening message is technically a post — just post number one.

Now let’s talk about the fields that make up a discussion. There are quite a few, so let’s walk through them. Every discussion has a unique integer ID, and a title, which is the name of the thread. There’s also a slug, which is just the URL-friendly version of that title — the bit you see in the web address. You get a comment count, which tells you the total number of posts in the thread, and a participant count, which counts how many unique users have actually replied. There are two timestamps to be aware of: when the discussion was created, and when the most recent post was added. Discussions can also be locked, which means no new replies are allowed, or sticky, which means they’re pinned to the top of their tag. Finally, discussions carry relationships — links to the tags they belong to, the opening post, and the user who started the thread.

Posts have their own set of fields. Like discussions, each post has a unique integer ID. There’s also a number field, which tells you the position of that post within its discussion — so number one is always the opening post. The content type field tells you what kind of post it is. Most of the time you’ll see “comment,” which just means a normal reply. But there are other types too, like one that logs when a discussion title was changed. The actual text of the post lives in the content field, stored in a format called TextFormatter XML, and there’s also a content HTML field which gives you the already-rendered HTML version. You get a created-at timestamp and an edited-at timestamp for tracking changes. And like discussions, posts carry relationships back to their parent discussion and to the user who wrote them.

So how do you actually create a discussion through the API? The call goes to the discussions endpoint using a POST request. You include an authorization token in the header, and you send along a JSON body. That body wraps everything inside a data object. You specify the type as “discussions,” then inside the attributes you provide the title and the content — the opening post text. You can also attach tags by including a relationships section, where you pass in an array of tag objects, each identified by its ID. So for example, if you wanted to post to the general tag, you’d pass in its tag ID there.

One more thing worth knowing is how post formatting works in Flarum. The forum uses a system called TextFormatter, which is a superset of both BBCode and Markdown. What that means practically is that you can use standard Markdown — things like headings, bold, italic, lists, code blocks, and links. You can also use some BBCode tags depending on which extensions are active. On top of that, you get emoji shortcodes, so typing a colon, the word smile, and another colon gives you a smiley face. And you can use at-mentions to notify another user directly in a post.

That’s the core of how discussions and posts work in the NZRT forum — threads as containers, posts as the content inside them, and a clean API structure for creating both programmatically.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

00 - Overview, 000FLA

Flarum Overview

Welcome to the NZRT Wiki Podcast. Today we’re looking at Flarum Overview.

So, what exactly is Flarum? At its core, Flarum is a free, open-source forum software. If you’ve ever found older forum platforms bloated, slow, or just plain ugly, Flarum was built as a direct answer to those frustrations. It’s designed around three guiding principles — simplicity, speed, and extensibility — and it’s fully MIT licensed, which means you own your data and can host it yourself.

Let’s talk about those principles a little more. When the Flarum team say simple, they mean a clean, uncluttered interface with minimal configuration needed to get up and running. There’s no legacy baggage dragging it down. When they say fast, they mean it in a very specific technical sense — Flarum is a single-page application, so when you navigate between pages, the browser doesn’t do a full reload. Transitions happen instantly, which makes the whole experience feel much snappier than traditional forums. And when they say extensible, they mean the core is deliberately kept minimal — almost every additional feature you’d want gets added through Flarum’s extension system, which we’ll touch on in a moment.

Now let’s look at how Flarum is actually built under the hood. The backend runs on PHP version 8 and above, using the Laravel framework — so if you’ve worked with Laravel before, you’ll feel right at home. The API layer follows the JSON colon API specification, which is a standardised, RESTful approach to how data gets passed around. On the frontend, Flarum uses a JavaScript framework called Mithril dot JS to power that single-page app experience we just mentioned. For the database, it uses either MySQL or MariaDB. Authentication is handled through session cookies and API tokens, depending on how you’re accessing it. And for search, the default is MySQL’s built-in full-text search, though you can swap that out for a more powerful tool called Meilisearch if you install the relevant extension.

Next up, the key concepts you’ll encounter when working with Flarum. There are six main ones to know. First is a discussion — that’s essentially a thread, made up of a title and a series of posts. Second is a post, which is an individual reply within a discussion. Third is a tag — tags in Flarum work like categories. You can apply them to discussions, they support a hierarchy, and there are two levels: primary tags and secondary tags. Fourth is a user — that’s any member of the forum, identified by a username, email address, avatar, and group memberships. Fifth is a group — groups are how permissions work in Flarum. Out of the box there are four: Admin, Moderators, Members, and Guests, each with their own permission set. And sixth is an extension — these are plugins that add or modify functionality within Flarum. Because the core is intentionally lean, extensions are how you build out the features you actually need.

Now, when it comes to editions, there are two options available to you. The first is Flarum Community, which is the self-hosted version — free, open source, MIT licensed, and gives you full control over your own installation. The second is Flarum Cloud, which is a managed hosting service run by the Flarum team themselves, offered as a paid option if you’d rather not manage the infrastructure. For reference, NZRT runs the Community edition, self-hosted on the Hoopla cPanel server.

If you want to dig deeper into Flarum, the main website is at flarum dot org, full documentation lives at docs dot flarum dot org, and the source code is publicly available on GitHub under the flarum slash framework repository.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

000FLA, 04 - REST API

Rest Api Overview

Welcome to the NZRT Wiki Podcast. Today we’re looking at REST API Overview.

So let’s talk about how Flarum’s API works and how you can interact with it. The first thing to know is that Flarum follows something called the JSON API specification. What that means for you in practice is that every request you send and every response you get back uses a standard content type called application JSON. The base URL you’ll be hitting for everything is your forum domain, followed by slash api.

Let’s start with authentication, because you need to get this right before anything else works. The recommended approach for write operations is to get a session token. You do this by sending a POST request to the token endpoint, passing in a JSON body with your username under the identification field and your password. The API comes back with a response containing two things: a token, which is a long string of characters, and your user ID. From that point on, you include that token in the Authorization header of every request, formatted as the word Token followed by your token string.

Here’s an important warning that will save you a lot of headaches. If you’re using pre-generated API tokens from the user settings panel in Flarum, those work fine for read-only GET requests, but they will fail on POST, PATCH, and DELETE operations because of CSRF validation. So always go through the token endpoint for anything that writes data.

Now let’s walk through what you can actually do with the API. There are three main groups of endpoints. For discussions, you can list all discussions, fetch a single discussion by its ID, create a new discussion, update an existing one, or delete one. For posts, meaning individual replies within a discussion, you can list posts, create a new reply, edit an existing post, or delete one. And for users, you can list all users or fetch a single user by ID. There’s also an endpoint to list all available tags.

Next, let’s talk about how you structure a request body when you’re creating or updating something. The JSON API format wraps everything inside a top-level data object. Inside that, you specify the type, for example the word discussions, then an attributes section where you put things like the title and the body content of your post. If you need to attach a tag, you add a relationships section, and inside that a tags object, which holds a data array. Each item in that array is an object with a type of tags and the numeric ID of the tag you want to apply.

For filtering and pagination, you append query parameters to your URL. To filter discussions by a tag, you use filter with tag as the key and the tag slug as the value. To control how many results come back, you use page limit and set a number. To offset into the results for pagination, you use page offset. You can also do text search across discussions or users by using filter with q as the key and your search term as the value.

Finally, a word on patching tags onto an existing discussion. The structure is similar to creation. You send a PATCH request with a data object specifying the type as discussions, the ID of the discussion you’re targeting, and then a relationships block with the tag you want to apply. One critical thing to be aware of here: you can only send one tag per PATCH request. If you try to send multiple tags in a single request, the API will return a 500 error. So if you need to apply multiple tags, make separate requests.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

000FLA

Tags

Welcome to the NZRT Wiki Podcast. Today we’re looking at Tags.

If you’ve spent any time in Flarum, our forum platform, you’ve probably noticed that every discussion sits inside some kind of category. That category system is powered by Tags. Tags are how Flarum organises discussions, controls who can see what, and manages permissions across the forum. Let’s walk through how they work.

First, let’s talk about the different types of tags you’ll encounter. There are four. The first is a primary tag — this is the main category for a discussion, and depending on how the Tags extension is configured, it may be required. You can’t post without one. The second type is a secondary tag, which is an optional extra label you can layer on top of the primary one. Think of it as a cross-reference or a way to flag a discussion as belonging to more than one topic area. Then you have parent tags, which are top-level grouping tags that sit above other tags. And finally, child tags are nested underneath a parent. So you might have a parent tag called something like Projects, with child tags underneath it for specific project areas.

Now let’s look at what makes up a tag — its fields. There are ten of them. First is the id, which is just a unique number that identifies the tag internally. Then there’s the name, which is the human-readable display name you see in the forum. The slug is the URL-friendly version of that name — it’s what appears in the web address when you filter by a tag. The description is an optional text field where you can explain what the tag is for. Colour is a hex colour string, so you can give each tag its own visual identity in the forum interface. Icon lets you assign a FontAwesome icon class to the tag. Position controls the sort order — lower numbers appear first. Then there are two visibility-related fields: isRestricted, which flags whether the tag is limited to specific user groups, and isHidden, which hides the tag entirely from guests who aren’t logged in. Finally, the parent field is a relationship field — if a tag is a child tag, this field points to its parent.

On the topic of permissions, tags in Flarum aren’t just organisational — they can actually control access. You can set per-tag permission overrides through the Admin panel under Permissions. This is really useful if you want to lock down certain areas of the forum so only specific groups can post to them, or even just view them. It gives you fine-grained control without having to create entirely separate forum spaces.

Managing tags is done through the Admin area. You go to Admin, then Tags, and from there you can create new tags, edit existing ones, and reorder them. Reordering is drag and drop. And if you want to nest a tag as a child under a parent, you just drag it onto the parent tag. It’s a pretty visual interface once you’re in there.

Now let’s talk about the API. If you’re working with tags programmatically — for example, in an agent script or integration — you’ll want to know how to retrieve the tag list. You make a GET request to the tags endpoint on the API. In practice, that means calling the API address with the path ending in api/tags, and you include an authorisation header with your token. What comes back is the full list of all tags in one go. There’s no pagination here — you get everything in a single response, which makes it straightforward to parse and work with. If you’re building something that needs to look up a tag ID by its slug, or populate a dropdown of available tags, this is the call you want.

One practical thing to keep in mind: when you’re creating or tagging a discussion through the API, you’ll often need the tag’s slug for human-readable references, but the actual API calls for things like patching or associating tags with discussions typically need the numeric ID. So it’s worth keeping a mapping of slug to ID handy. In fact, the NZRT operations documentation maintains that exact list for the tags we use regularly.

That’s the Tags system in a nutshell. They’re more than just labels — they’re the backbone of how Flarum structures content, manages visibility, and enforces permissions across the forum. Whether you’re an admin setting things up in the interface or a developer working through the API, understanding tag types, fields, and how permissions layer onto them will save you a lot of guesswork.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

000FLA, 05 - NZRT Forum

Togaf Phase Tags

Welcome to the NZRT Wiki Podcast. Today we’re looking at TOGAF Phase Tags.

If you’ve spent any time in the NZRT forum, you’ve probably noticed that discussions are organised by tags. For TOGAF work specifically, those tags map directly to the ADM phase cycle, and understanding how they fit together makes navigating forum content a lot easier.

Let’s start with the phase tags themselves. There are ten of them covering the full TOGAF ADM lifecycle. The Preliminary phase uses the slug preliminary-phase and has a tag ID of 5. Phase A, Architecture Vision, is phase-a with ID 6. Phase B, Business Architecture, is phase-b with ID 7. Phase C, Information Systems, is phase-c with ID 8. Phase D, Technology Architecture, is phase-d with ID 9. Phase E, Opportunities and Solutions, is phase-e with ID 10. Phase F, Migration Planning, is phase-f with ID 11. Phase G, Implementation Governance, is phase-g with ID 12. Phase H, Change Management, is phase-h with ID 13. And finally, Requirements Management uses the slug requirements-management with ID 14.

Beyond the phase-specific tags, there are eight general-purpose tags. General is ID 15, Tasks is 16, Announcements is 17, Dev is 18, API is 19, and then three business unit tags: ICS at 20, ITE at 21, and NCS at 22.

Now, here’s the practical detail you need to know depending on what you’re doing. When you’re creating a new discussion using the forum tool, you pass the slug string directly into the tag parameter. So you’d write something like phase-f, and the tool resolves that to the correct numeric ID internally. You don’t have to worry about the numbers at that point.

However, if you’re patching an existing discussion to add or change a tag, the numeric ID is required. And there’s an important constraint here: you can only apply one tag per patch request. If you try to include multiple tags in a single patch, you’ll get a 500 error. So keep those calls separate. Also worth noting, you must use Python for patch operations. PowerShell fails because of how it handles CSRF tokens.

On the topic of filtering discussions by phase, the wiki includes an example of the API call you’d use. In plain terms, it’s a GET request to the forum’s API, pointing at the discussions endpoint, with a filter parameter specifying the tag slug you want and a page limit of up to 50 results. You use the full slug, so phase-f rather than any shortened version. If you’re using curl on the command line, you need the -g flag to stop curl from misreading the square brackets in the URL as glob patterns.

Putting it all together in the TOGAF workflow: at each ADM phase, a script called create_togaf_phase_tickets.py is run with the phase letter as an argument. That creates eight agent tickets, one per agent. Each agent then posts their forum discussion under the relevant phase tag. Once all eight discussions are up, both xc and cla review them before the gate sign-off document is produced. The tags are what keep all of that content organised and filterable throughout the process.

So in short, slugs for creating, numeric IDs for patching, one tag per patch, and always Python for forum write operations.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

000FLA

Users Groups

Welcome to the NZRT Wiki Podcast. Today we’re looking at Users and Groups.

We’re going to walk through how Flarum handles users, groups, permissions, and authentication. If you’ve ever wondered how the forum knows who you are, what you’re allowed to do, or how an automated script logs in and posts on your behalf, this episode covers all of that.

Let’s start with users. Every person on the forum is represented by a user object, and that object carries a set of fields that describe who they are and what they’ve been up to. There’s a unique integer ID that identifies the account internally, and a username which is the unique login name you use to sign in. There’s also a display name, which is what other people see in the interface — and if you don’t set one explicitly, it just defaults to your username. Your email address is stored too, though that’s only visible to admins. The system also tracks whether your email has been confirmed, when you first registered, and when you were last active on the forum. On top of that, it keeps a running count of how many discussions you’ve started and how many posts you’ve made. Finally, your user record has a relationship called groups, which links you to whichever groups you belong to — and that’s where permissions come from, as we’ll see in a moment.

Now let’s talk about built-in groups. Flarum ships with four groups already configured. The first is Admin, with an ID of one — this group has full access and all permissions across the board. The second is Guests, ID two — these are unauthenticated visitors, people browsing the forum without logging in. Third is Members, ID three — this covers all registered users, so anyone who has created an account automatically belongs to this group. And fourth is Moderators, ID four — moderators can edit or delete any post, lock threads, and sticky discussions. Beyond these four, you can create your own custom groups through Admin, then Groups in the control panel.

Speaking of permissions — in Flarum, permissions are assigned to groups, not to individual users. You manage this through Admin, then Permissions. There are several core permissions to know about. View forum controls whether a group can see discussions at all. Sign up controls whether visitors can register an account. Start discussions lets a group create new threads. Reply to discussions lets them post in existing ones. Use markdown gives a group the ability to format their posts. Edit own posts lets someone modify a post they’ve already made, and Delete own posts lets them remove it entirely. Moderators and admins automatically have elevated access beyond what this list covers, so they don’t need each of these switched on individually.

Now let’s move on to authentication, which is where things get a little more technical — but don’t worry, we’ll keep it simple. Flarum supports three ways of logging in. The default method is a plain username and password. You can also enable OAuth through extensions, which lets users sign in with accounts from places like GitHub, Google, or Facebook. And finally, there are API tokens, which are used for programmatic access — meaning when a script or an agent needs to interact with the forum on someone’s behalf.

Here’s how API token authentication works in practice. When you make an HTTP request to the forum’s API, you include an Authorization header, and you set its value to the word Token followed by a space and then the token string itself. You can generate tokens inside user settings, or you can create one by making a POST request to the API token endpoint.

There’s an important gotcha here that’s worth paying attention to. Pre-generated tokens — the kind you copy out of the settings page — work fine for read-only requests like fetching a list of discussions. But if you try to use one to create a post, update something, or delete something, it will fail. That’s because write operations go through CSRF validation, which those static tokens don’t satisfy. For any write operation, you need a session token instead, and you get that by making a POST request to the token endpoint with actual login credentials. That session token is what you use for mutations. If you’re building any kind of automation that posts to the forum, this is the distinction you need to get right.

So to bring it all together: users are identified by a handful of fields including their ID, username, and group memberships. Groups are the unit of control — four built-in ones cover admins, guests, members, and moderators, and you can add your own. Permissions are set on groups rather than individuals, covering everything from viewing the forum to deleting your own posts. And authentication can happen via password, OAuth, or API token — with the key rule that session tokens from a fresh login are required for any write operation through the API.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.