Fossil

Fossil Forums
Login

Introduction

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

Permissions

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.

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.

Enable Forum Search

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 Notification

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 address — forum-bounces@example.com 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 admin@example.com.

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 -t, say 

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

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 -t"
    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 /subscribe page on your Fossil instance and sign your regular Fossil user up for email alerts. (Alternate path: click the login/logout link in the upper right corner, 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, and it 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, we can test the email subsystem separately from the rest of the Fossil email alerts system with the following command: 

    $ fossil alerts test-message you@example.com --body README.md --subject Test

That should send you an email with "Test" in the subject line and the contents of your project's README.md 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?

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

Troubleshooting

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.

Moderation

Fossil forum moderation is easy:

  1. Add the Moderate Forum (5) capability 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 without WriteTrusted Forum (4) capability submits a post, you'll get a notice on the timeline if the type filter is set to "Forum" or "Any Type". It will also appear on the /modreq page; you might want to keep that page open in a tab in your browser, and reload it occasionally to check for pending moderation requests.
  3. On an unmoderated post, click the "Approve" or "Reject" button. "Approve" writes the message semi-permanently into the Fossil blockchain, from which only shunning can remove it. "Reject" deletes the post permanently, with no way to retrieve it. Be careful!