Fossil Forums


As of Fossil 2.7, Fossil includes a built-in discussion forum feature.

Any project complex enough to benefit from being managed by Fossil and which has more than one user can probably also benefit from having a discussion forum. Even if your project has a discussion forum already, there are many benefits to using Fossil's built-in forum feature, some of which you cannot get by using third-party alternatives:

Setting up a Fossil Forum


Fossil forums use the same role-based access control mechanism as for normal Fossil repository logins.

There are several dedicated forum-related capability bits you can grant a user:

By default, no Fossil user has permission to use the forums except for users with Setup and Admin capabilities, which get these as part of the large package of other capabilities they get.

For public Fossil repositories that wish to accept new users without involving a human, go into Admin → Access and enable the "Allow users to register themselves" setting. You may also wish to give users in the anonymous category the Read Forum (2) and Write Forum (3) capabilities: this allows people to post without creating an account simply by solving a simple CAPTCHA.

For a private repository, you probably won't want to give the anonymous user any forum access, but you may wish to give the Read Forum capability (2) to users in the reader category.

For either type of repository, you are likely to want to give at least the WriteTrusted capability (4) to users in the developer category. If you did not give the Read Forum capability (2) to anonymous above, you should give developer that capability here if you choose to give it capability 3 or 4.

You must give at least one user or user category the Email Alerts capability (7), else the only people able to sign themselves up for email notifications are those with the Setup or Admin capability. Those users could sign others up via Admin → Notification, but you probably want to give this capability to one of the user categories. Give it to nobody if you want anyone to sign up without any restrictions. Give it to anonymous if you want the user to solve a simple CAPTCHA before signing up. Give it to reader or developer if you want only users with Fossil logins to have this ability. (That's assuming you give one or both of these capabilities to every user on your Fossil repository.)

By following this advice, you should not need to tediously add capabilities to individual accounts except in atypical cases, such as to grant the Moderate Forum capability (5) to an uncommonly highly-trusted user.

Skin Setup

If you create a new Fossil repository with version 2.7 or newer, its default skin is already set up correctly for typical forum configurations.

Those upgrading existing repositories will need to edit the Header part of their existing Fossil skin in Admin → Skins, adding something like this to create the navbar link:

  if {[anycap 23456] || [anoncap 2] || [anoncap 3]} {
    menulink /forum Forum

These rules say that any logged-in user with any forum-related capability (2-6 inclusive, as of this writing) or an anonymous user with read or write capability on the forum (2, 3) will see the "Forum" navbar link, which just takes you to /forum.

The exact code you need here varies depending on which skin you're using. Follow the style you see for the other navbar links.

The new forum feature also brings many new CSS styles to the table. If you're using the stock skin or something sufficiently close, the changes may work with your existing skin as-is. Otherwise, you might need to adjust some things, such as the background color used for the selected forum post:

  div.forumSel {
    background-color: rgba(0, 0, 0, 0.05);

That overrides the default — a hard-coded light cyan — with a 95% transparent black overlay instead, which simply darkens your skin's normal background color underneath the selected post. That should work with almost any background color except for very dark background colors. For dark skins, an inverse of the above trick will work better:

  div.forumSel {
    background-color: rgba(255, 255, 255, 0.05);

That overlays the background with 5% white to lighten it slightly.

One of the underlying assumptions of the forum feature is that you will want to be able to search the forum archives, so the /forum page always includes a search box. Since that depends on search being enabled on the Fossil repository, Fossil warns that search is disabled until you go into Admin → Search and enable the "Search Forum" setting.

You may want to enable some of the other Fossil search features while you're in there. All of this does come at some CPU and I/O cost, which is why it's disabled by default.

Single Sign-On

If you choose to host your discussion forums within the same repository as your project's other Fossil-managed content, you inherently have a single sign-on system. Contrast third-party mailing list and forum software where you either end up with two separate user tables and permission sets, or you must go to significant effort to integrate the two login systems.

You may instead choose to host your forums in a Fossil repository separate from your project's main Fossil repository. A good reason to do this is that you have a public project where very few of those participating in the forum have special capability bits for project assets managed by Fossil, so you wish to segregate the two user sets.

Yet, what of the users who will have logins on both repositories? Some users will be trusted with access to the project's main Fossil repository, and these users will probably also participate in the project's Fossil-hosted forum. Fossil has a feature to solve this problem which is probably less well known than it should be, and which has been a feature of Fossil since April of 2011: Admin → Login-Group. This allows one Fossil repository to recognize users authorized on a different Fossil repository.

Email Notifications (Alerts)

The detailed information for this feature of Fossil is in two other documents:

You may want to study those in detail, since email is complicated. Some of that complexity necessarily leaks out to the configuration of email notification in Fossil.

Quick Setup

However, if you've already got a working Postfix, Exim, or Sendmail server on the machine running your Fossil instance(s), and you aren't using Fossil's chroot feature to wall it off from the rest of the machine, it's fairly simple to set up email notifications:

  1. Go to Admin → Notification and fill out all of the Required fields:
    • Canonical server URL — Use the suggested URL
    • "From" email is traditional, but do what you like
    • Repository nickname — See the suggested examples on the web page.
  2. Set "Email Send Method" to "Pipe to a command"
  3. Set the "Administrator email address" to a suitable email address. It could be the same value you used for the "From" address above, or it could be a different value like

Save your changes.

For all of the following fossil CLI commands, we're going to assume that you've cd'd into a checkout directory for your repository on the central server. Otherwise, we'd need to add -R /path/to/repo.fossil to each of them.

Give this command:

    $ fossil set email-send-command

If that gives a blank value instead of sendmail -ti, say

    $ fossil set email-send-command "sendmail -ti"

to force the setting. That's a known bug which should be squished soon.

This is the correct command even if you're running Postfix or Exim rather than Sendmail. These mail servers (and perhaps others) provide a sendmail command for this very sort of reason: it lets programs send email without having to care exactly which server implementation is running at a given site.

If you reload the Email Notification Setup page, the Status section at the top should show:

    Outgoing Email: Piped to command "sendmail -ti"
    Pending Alerts: 0 normal, 0 digest
    Subscribers:    0 active, 0 total

Subscribe to Alerts

Above, we see that there are no subscribers, so the next step is to add one.

Go to the /alerts page on your Fossil instance and sign your regular Fossil user up for email alerts. (Alternate path: click the user name or login/logout link in the upper right corner, depending on the skin you're using, then go to "Email Alerts".) You will need "Forum Posts" checked at the least for the testing steps below.

If you use the same user name and email address as you used for your normal user login, Fossil will simply tie your alert preferences to your login record, and the email address in your user's Contact Info field will be considered already-verified. Otherwise, Fossil will create an alert-only record, and you will have to verify the email address before Fossil will send notifications to it.

This shows a key aspect of the way Fossil's email alerts system works, by the way: a user can be signed up for email alerts without having a full-fledged Fossil user account. Only when both user names are the same are the two records tied together under the hood.

Test the Email Subsystem

If you'd rather not create an inane "testing" post in your Fossil instance just to force out an email alert, you can test the email subsystem separately from the rest of the Fossil email alerts system with the following command:

    $ fossil alerts test-message --body --subject Test

That should send you an email with "Test" in the subject line and the contents of your project's file in the body. If it works, the file's contents may be truncated. I'm uncertain whether that's due to an intentionally-small buffer size or if it's a bug.

That command assumes that your project contains a readme file. Of course it does. Why would it not?

First Post

Since you've already edited the skin per the instructions above, you can click the "Forum" link in the navbar and create a new post. I suggest taking the time to compose a suitable introductory message especially for your project's forum, one which a new user would find helpful.

Wait a few seconds, and you should receive a notification email with the post's subject and body text in the email.


If email alerts aren't working, there are several useful commands you can give to figure out why.

(Be sure to cd into a repo checkout directory first!)

    $ fossil alerts status

This should give much the same information as you saw above. One difference is that, since you've created a forum post, the pending-alerts value should only be zero if you did in fact get the requested email alert. If it's zero, check your mailer's spam folder. If it's nonzero, continue with these troubleshooting steps.

    $ fossil backoffice

That forces Fossil to run its "back office" process. Its only purpose at the time of this writing is to push out alert emails, but it might do other things later. Sometimes it can get stuck and needs to be kicked. For that reason, you might want to set up a crontab entry to make sure it runs occasionally.

    $ fossil alerts send

This should also kick off the backoffice processing, if there are any pending alerts to send out.

    $ fossil alert pending

Show any pending alerts. The number of lines output here should equal the status output above.

    $ fossil test-add-alerts f5900
    $ fossil alert send

Manually create an email alert and push it out immediately.

The f in the first command's final parameter means you're scheduling a "forum" alert. The integer is the ID of a forum post, which you can find by visiting /timeline?showid on your Fossil instance.

The second command above is necessary because the test-add-alerts command doesn't kick off a backoffice run.

    $ fossil ale send

This only does the same thing as the final command above, rather than send you an ale, as you might be hoping. Sorry.

How Moderation Works

In this section, we're going to call all of the following a "forum update:"

When a person with the normal Write Forum capability (3) updates the forum, Fossil saves the update in its block chain, but this update is impermanent because of two other table updates made at the same time:

  1. Fossil saves the update artifact's ID in its private table, preventing Fossil from sending such artifacts to any of the repository's clones. (This is the same mechanism behind private branches.)
  2. Fossil also adds a reference to that artifact in the modreq table, which backs the moderation feature. This is what causes Fossil to leave out the Reply button when rendering that post's HTML in the forum's web interface.

When a moderator approves an update, Fossil deletes these table entries, making the update semi-permanent. This changes how Fossil renders the HTML for that update. It also means the artifact will now sync to clones, if the sync is done by a user with Check-Out capability (o).

When a forum user edits a moderator-approved artifact, what actually happens under the hood is that Fossil writes another artifact to the repository which refers to the original version as its parent, causing Fossil UI to present the new version instead of the original. The original version remains in the repository, just as with historical checkins. The parent must remain in the repository for referential integrity purposes.

When you "Delete" a moderator-approved post or reply through Fossil UI, it's actually an edit with blank replacement content. The only way to truly delete such artifacts is through shunning.

When a user with WriteTrusted Forum capability (4) updates the forum, it happens in the same way except that Fossil skips the private and modreq table insertions.

When a moderator rejects an update, that artifact is unceremoniously removed from the tip of the block chain. This is safe because Fossil prevents replies to a reply or post awaiting moderator approval, so referential integrity cannot be harmed. Rejecting an edit is even safer, since the original post remains behind, so that replies continue to refer to that original post.

Using the Moderation Feature

Having described all of the work that Fossil performs under the hood on behalf of its users, we can now give the short list of work left for the repository's administrators and moderators:

  1. Add the Moderate Forum capability (5) to any of your users who should have this ability. You don't need to do this for any user with Setup (s) or Admin (a) capability; it's already included.
  2. When someone updates the forum, an entry will appear in the timeline if the type filter is set to "Forum" or "Any Type". If that user has only the Write Forum capability (3), any other user with the Moderate Forum capability (5) will see a conditional link appear at the top of the main forum page: "Moderation Requests". Clicking this takes the moderator to the /modreq page. A moderator may wish to keep the main forum page open in a browser tab, reloading it occasionally to see when the "Moderation Requests" link reappears.
  3. A moderator viewing an update pending moderation sees two buttons at the bottom, "Approve" and "Reject" in place of the "Delete" button that the post's creator sees. Beware that both actions are durable and have no undo. Be careful!