Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
174 lines (119 sloc) 11.6 KB
  1. Installation
  2. After-Installation Instructions

Installation

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 -A ponyforum --git

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 CLI (command line interface) using either dotCloud's own installation instructions or DotCloudWin. Users on other platforms should 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.

After-Installation Instructions

The Default "Admin"

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 -A ponyforum --git

Your Site Name

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 forum1 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 /configuration/.

Setting Up an E-Mail Server

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 env set -A ponyforum EMAIL_HOST_USER=your_user_name@gmail.com
dotcloud env set -A 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 env set -A 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 env list -A ponyforum

If you have an admin user, you can also view these key/values in your configuration view located by default at /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 env unset -A 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 -A ponyforum --git 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.

Postponing the Set-Up

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.

DEBUG = True or False?

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.

Aaand You're Done!

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.