Permalink
Browse files

Split off the installation section from the README

  • Loading branch information...
ndarville committed May 4, 2014
1 parent d48cad5 commit 6a1b9c1400ed45ee47b8f8686c483d9d38544cbe
Showing with 240 additions and 231 deletions.
  1. +15 −179 README.mdown
  2. +140 −52 _installation/INSTALLATION.mdown
  3. +85 −0 _installation/step-by-step.mdown
View
@@ -17,15 +17,8 @@ Pony Forum is a forum (also known as a bulletin board) written in Python for the
1. [Features](#features)
2. [Requirements](#requirements)
3. [Compatibility](#compatibility)
4. [Installation](#installation)
5. [After-Installation Instructions](#after-installation-instructions)
* [The Default Admin](#the-default-admin)
* [Your Site Name](#your-site-name)
* [Setting Up an E-Mail Server](#setting-up-an-e-mail-server)
* [Postponing the Set-Up](#postponing-the-set-up)
* [DEBUG = True or False?](#debug--true-or-false)
* [Aaand You're Done!](#aaand-youre-done)
6. [License](#license)
3. [Installation](#installation)
3. [License](#license)
[Features](#features)
----------
@@ -67,152 +60,7 @@ At the moment, Windows 7/8 break during testing and dotCloud deployment. It is m
[Installation](#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][dotcloud] accommodates this goal and allows us to deploy a whole working forum to a dotCloud instance using only these terminal commands:
```sh
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][dc-install] or [DotCloudWin][dotcloudwin]. Users on other platforms should use dotCloud's installation guide to set it up with no hitches.
Remember to [sign up][registration] 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][_installation]. Look below for how to configure your installed dotCloud app.
[After-Installation Instructions](#after-installation-instructions)
---------------------------------
### [The Default "Admin"](#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][mkadmin] script, which is called by [postinstall][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:
```sh
dotcloud destroy ponyforum
dotcloud create ponyforum
dotcloud push -A ponyforum --git
```
### [Your Site Name](#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][definesite], 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<sup>**1**</sup> 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](#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][email-guide], if you use a Gmail e-mail account, you can define your own e-mail server by entering these credentials:
```python
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][ex-local] `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][environments] and, instead, enter the information like environment variables like so:
```sh
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:
```sh
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
```sh
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
```sh
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][tfa], you default password will not work, because you need to create a designated application password for it [here][app-password]. 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](#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
```python
url(r'^accounts/', include('registration.backends.default.urls')),
```
with this
```python
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][reg-backend] 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?](#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!](#aaand-youre-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.
Follow the installation instructions [here][installation].
[License](#license)
---------
@@ -222,27 +70,15 @@ Boom! You're done.
**1:** This has been disabled for the time being.
[screenshot1]: https://github.com/ndarville/pony-forum/raw/master/_screenshots/regular.png
[screenshot2]: https://github.com/ndarville/pony-forum/raw/master/_screenshots/iphone-2.png
[screenshot3]: https://github.com/ndarville/pony-forum/raw/master/_screenshots/iphone-1.png
[dotcloud]: https://dotcloud.com/
[new-admin]: https://github.com/riccardo-forina/django-admin-bootstrapped
[dyslexia]: http://dyslexicfonts.com/
[markdown]: http://daringfireball.net/projects/markdown/
[smartypants]: http://daringfireball.net/projects/smartypants/
[tables]: http://packages.python.org/Markdown/extensions/tables.html
[pbkdf2]: https://docs.djangoproject.com/en/1.4/releases/1.4/#improved-password-hashing
[django-secure]:https://github.com/carljm/django-secure
[dc-install]: http://docs.dotcloud.com/firststeps/install/
[dotcloudwin]: https://github.com/speier/DotCloudWin/downloads
[registration]: https://www.dotcloud.com/accounts/register/
[_installation]:https://github.com/ndarville/pony-forum/blob/master/_installation/INSTALLATION.mdown
[mkadmin]: https://github.com/ndarville/pony-forum/blob/master/_postisntall/mkadmin.py
[postinstall]: https://github.com/ndarville/pony-forum/blob/master/postinstall
[definesite]: https://github.com/ndarville/pony-forum/blob/master/_postinstall/definesite.py
[email-guide]: http://sontek.net/using-gmail-to-send-e-mails-from-django
[ex-local]: https://github.com/ndarville/pony-forum/blob/master/ponyforum/example_local_settings.py
[environments]: http://docs.dotcloud.com/guides/environment/
[tfa]: https://accounts.google.com/SmsAuthConfig
[app-password]: https://accounts.google.com/IssuedAuthSubTokens
[reg-backend]: https://bitbucket.org/ubernostrum/django-registration/src/27bccd108cde/docs/simple-backend.rst
[screenshot1]: https://github.com/ndarville/pony-forum/raw/master/_screenshots/regular.png
[screenshot2]: https://github.com/ndarville/pony-forum/raw/master/_screenshots/iphone-2.png
[screenshot3]: https://github.com/ndarville/pony-forum/raw/master/_screenshots/iphone-1.png
[dotcloud]: https://dotcloud.com/
[new-admin]: https://github.com/riccardo-forina/django-admin-bootstrapped
[dyslexia]: http://dyslexicfonts.com/
[markdown]: http://daringfireball.net/projects/markdown/
[smartypants]: http://daringfireball.net/projects/smartypants/
[tables]: http://packages.python.org/Markdown/extensions/tables.html
[pbkdf2]: https://docs.djangoproject.com/en/1.4/releases/1.4/#improved-password-hashing
[django-secure]: https://github.com/carljm/django-secure
[installation]: https://github.com/ndarville/pony-forum/blob/master/_installation/INSTALLATION.mdown
Oops, something went wrong.

0 comments on commit 6a1b9c1

Please sign in to comment.