Pony Forum is a forum (also known as a bulletin board) written in Python for the Django framework. It is intended as a replacement of the decade-old forums like vBulletin, PHPBB, etc.---and a free one easy to deploy at that.

Pony Forum features such niceties as:

• Installed in few easy steps on dotCloud
• Written in Python and uses the popular Django framework
• Mobile CSS that adapts the layout to your iPhone
• Experimental dyslexia support
• A powerful editor for writing and creating content:
  • Super simple Markdown-based formatting learnt in no time ...
  • ... with automatic, typography-friendly SmartyPants conversion
  • You can even create tables for data- and fact-based discussions!
• Values security and privacy with such things as:
  • SSL support
  • PBKDF2 password-hashing
  • django-secure vetting

One of the ideas behind Pony Forum was to create a forum that is easily deployed with little head-scratching. At the moment dotCloud accommodates this goal and allows us to deploy a whole working forum to a dotCloud instance using only these terminal commands:

git clone git@github.com:ndarville/pony-forum.git
cd pony-forum
dotcloud create ponyforum
dotcloud push ponyforum

The ponyforum name is temporary and can be replaced with any other name. In the future, it will be probably be renamed to forum or pony forum in the future.

You will also need to set up an e-mail server (which is very, very easy), all of which is explained in Setting Up an E-Mail Server later on in this README. Fret not.

The results on Windows 7 have been uneven at best, but if you want to try your luck, you can install the dotCloud dependencies dotCloud can be installed using either dotCloud's own installation instructions (not recommended) compared to just downloading and executing DotCloudWin. Users on other platforms can use dotCloud's installation guide to set it up with no hitches.

Remember to sign up for free on dotCloud, if you don't already have an account, in order to retrieve your API key.

If you want to use your forum locally, remember that you need to install the needed packages. If you have already installed pip, you can go to the directory of requirements.txt and type pip install -r requirements.txt in the terminal (sudo pip install -r requirements.txt, if you aren't on Windows), and all the packages will be downloaded and installed on you local development computer.

As said, Windows is a very, very wonky experience, and it seems to take issue with the PIL package most of the time for reasons beyond my scant knowledge.

A thorough step-by-step installation guide is available here. Look below for how to configure your installed dotCloud app.

When the forum is first deployed on dotCloud, an admin user is created and assigned a default password (wait for it): "password". This is done through the mkadmin.py script, which is called by postinstall if you want have a look under the bonnet.

Normally, you get to create your own admin, when the database is created, but since this happens automagically behind the scenes, you will not be able to enter your own credentials. Instead, you will have to change the password and details for the admin user to suit your own needs or create your own user(s) and dispose of the default admin user.

The important thing here is to tell you that all deployed pony forums will have the same password. This is fine, but you will eventually need to prevent other people from hijacking the admin user and wreaking havoc by either changing the user's password (done at /admin/auth/user/1/password/) or stripping the user of its staff and superuser status.

Just make sure you have another admin-like user ready, so you don't lock yourself out. If you do, you can always wipe and recreate the forum with these commands:

dotcloud destroy ponyforum
dotcloud create ponyforum
dotcloud push ponyforum

Speaking of automatic changes, Pony Forum guesses the name and domain of your website based on respectively

1. Your dotCloud project name
2. The URL for you dotCloud instance

How all this is done can be seen in definesite.py, which is (also) called in postinstall.

"So what?" you ask; what are these used for? As it happens, as of this writing, the name of your site is only relevant, if you want the name to appear in the header in the top middle of your forum¹ Besides that, it doesn't appear anywhere, really.

The domain on the other hand is much more important. It is used, amongst other things, to send activation e-mails to your users. As you may know, these e-mails contain an activation link that your users have to follow in order to activate their accounts.

But how does Pony Forum know which site the link points to? You guessed it, it uses the domain defined by definesite.py.

If you need to change these two fields---for instance, if you were to give your forum a better-looking URL---you will need to change the domain field. This can be done at /admin/sites/site/1/.

Speakiiing of activation e-mails, you need to, you know, send e-mails. "Jesus &"¤!#! Christ!" you think to yourself, but if you use a Gmail account, it's all actually quite easy! (I was surprised, too.)

Using sontek's intelligible guide, if you use a Gmail e-mail account, you can define your own e-mail server by entering these credentials:

EMAIL_HOST = 'smtp.gmail.com'
EMAIL_HOST_USER = 'user@gmail.com'
EMAIL_HOST_PASSWORD = 'password'
EMAIL_PORT = 587
EMAIL_USE_TLS = True

(If you use a Gmail e-mail, you just need to change the username and password, as the default values for the other keys will work fine.)

However! Putting this kind of configuration information in a place that may end up in a publicly viewable place is not adviseable. Instead:

1. If you are working in a local development environment, add above information to your local_settings.py. The file does not come with pony-forum for good reasons, but you can create it by renaming the templated and included example_local_settings.py to local_settings.py and change the relevant values there.

2. If you are setting up your forum on dotCloud, follow their guide to environmental variables and, instead, enter the information like environment variables like so:

dotcloud var set ponyforum EMAIL_HOST_USER=your_user_name@gmail.com
dotcloud var set ponyforum EMAIL_HOST_PASSWORD=your_password

The problem with this method is that dotCloud restarts your server, which takes a while, so to save your time, you can also do it like this on some operating systems:

dotcloud var set ponyforum \
    'EMAIL_HOST_USER=your_user_name@gmail.com' \
    'EMAIL_HOST_PASSWORD=your_password'

I think the last one is the easiest one, but choose whichever you prefer.

All dotCloud environment variables for your app can be viewed with

dotcloud var list ponyforum

If you have an admin user, you can also view these key/values in your configuration view located by default at /accounts/configuration/.

NOTE! If you are having problems with this, do not post the entirety of what this command returns, as it contains sensitive information that would jeopardize your app---and potentialy e-mail---security. It is better to engage in a yes-no dialogue with the people asking you what values are present in the list, and what they contain.

This should set up your e-mail server. At any point, you can alter the values by the approaches above. You can remove any erroneous environment variables entirely using

dotcloud var unset ponyforum EMAIL_HOST_PASSWORD

Obviously, you need to change the USER and PASSWORD fields to your own. Also note that if you are using Google's two-factor authentication, you default password will not work, because you need to create a designated application password for it here. The reason is that if you use two-factor authentication, you will not use the password for your actual account outside of Google's own sites, but an application password. The advantage of this is that you can remove this application in your Google account settings right away, if you accidentally share it through GitHub or elsewhere.

This is a much better security solution, because it is much easier to shut down a compromised application password by just removing it in your account settings than replacing your general password and playing cat and mouse with any potential hacker, as well as trying to recall your mother's middle name. If you aren't already using two-factor authentication, I urge you to do it to improve your Google and Gmail security significantly. Not because of Pony Forum, but the general security advantages it affods you.

After you have changed and saved your new settings in settings.py, run the dotcloud push ponyforum command again, and your new settings will be (derp) pushed to your instance. If nothing happens, follow it up with the command dotcloud restart ponyforum.www.

Last of all, there's another way out to avoid e-mail validation altogether for people on local servers. In urls.py, replace the line

url(r'^accounts/',  include('registration.backends.default.urls')),

with this

url(r'^accounts/',  include('registration.backends.simple.urls')),

In other words, replace default with simple. This allows your registration to work right away; don't worry about providing the right e-mail address nor setting up your e-mail server. If you want to read more about this, check out the documentation for the registration back-end.

Note that if you use this "trick" and are logged in as admin, you might still get a configuration error ("please set up your site/e-mail settings"), but because there is no e-mail server the configuration addresses, you are free to ignore the warnings.

While you're still in settings.py, you might consider changing the value of DEBUG, whether it is set to True or False.

It all depends on where you are in your development cycle, but remember to flip it off, once you open it to the public---and on, if you are testing your site.

Set it to True, if you are customizing it yourself, but set it to False, once you launch your site. By default, DEBUG is set to False, but you can alter this by changing the value of your DEBUG key in your dotCLoud environment variable.

Let's recapitulate the adjustments needed to set up Pony Forum:

1. Clone, create, push.
2. Set up your e-mail server.
3. Change the default admin "password" password.
4. Check that your defined site name and domain match your intended name and used URL.
5. Evaluate whether Django's debug mode should be on of off.

Boom! You're done.

(To be decided.)

Fire up some music and let's take a look at what I hope to get to at some point.

I want to implement Markdown footnotes, but as of now, they get identical anchor IDs, which breaks the links (since they all point to the same). I hope to find something that will work in the end, because I regard this as a very important feature to a forum that encourages long-form discussion.

1. Subscriptions
2. Bans
3. Avatars
4. Moderator management interface w/ back-end
5. Better report system

• Consolidate POST templates (and templates?) to fewer

  • Throw moderation-based templates in a separate folder
  • Rename prepend _ to _base.html and _page.html?

• CSS

  • General
  • Print

• Maintenance

  • Unit testing
  • Logging
  • Database optimization

• Internationalization

• Registration

  • Finite log-in attempts
  • Invitation-based sign-up
  • Two-factor authentication

• Category-ordering

• Thread polls

• Spoiler code

• Moderation and special access

  • Moderation action tracker
  • Members-only threads, categories, and forums
  • Threadmins and moderator groups

• Caching

• Embedding

  • Gist
  • Tweets
  • U.S. states

• Replacement of URLs with secure ones (secure, https, etc.)

• Search
• Formatting buttons
• Syntax highlighting
• Post edit time stamps
• Markdown Video
• Post and thread drafts
  • HTML5 storage?
• LaTeX/MathML support
• E-mail check with better regex. (Section 3.)
• iOS home screen icon trick
• Security:
  • Separate account and password reset e-mail
  • Implicit password

And much, much more.

1: This has been disabled for the time being.