This guide should be enough to get you up and running with a (bare-bones) functional, publicly accessible website in just a few hours.
We’re going to accomplish this using Pinax, an open-source project that aims to “deal automatically with what most websites have in common, and let you focus on what makes your site unique.”
Pinax is made up of several components. The core is a tool that generates new Django projects, configures them to work out of the box, and installs some “django apps” which provide basic essential website functionality. (As you hopefully remember, Django is designed to work with modular apps that let you easily package and install reusable bits of functionality.) In addition to the core apps, Pinax also provides a number of additional apps you can install that provide extra bits of functionality like managing user accounts or enabling basic social networking. Finally, Pinax provides starter projects that provide “out of the box” websites with various configurations of apps pre-installed.
So at a very high level, the steps we’re going to go through are:
1) Set your system up to use Pinax
2) Choose a starter project that suits your needs
3) Use Pinax to generate the project
4) Install any other apps you want
5) Customize your website!
6) Put it all online
I’ll walk you through the whole process step-by-step
1: Set your system up to use Pinax
Start by following the basic setup directions from the Pinax Documentation here.
1. Create and activate a virtual environment (which helps you make sure that you’re using the right versions of the right packages for your project, without worrying about accidentally upgrading a package a different project depends on.)
2. Install Pinax inside your virtual environment (`pip install Pinax`)
The official documentation for this step is good, so follow it for more detail.
2: Choose a starter project
The starter project you choose will serve as the foundation of your website. You can either start with the extreme barebones and install all the apps you want one-by-one, or you can The next step is to pick a “starter project” to use as the foundation of your project.
Most Pinax starter projects fit into three categories:
Foundational projects are intended to be the starting point for real projects. They provide the ground-work for you to build on with your domain-specific apps. Examples of foundational projects are zero_project and account_project.
Demo projects are really just intended to showcase particular functionality and demonstrate how a particular app works or how a set of apps might work together. You probably wouldn’t use them to kick off your projects (other than to get ideas) and they aren’t intended to be used for real sites.
Out-of-the-box projects are intended to be useful for real sites with only minor customization. That is not to say they couldn’t be highly modified, but they don’t need to be, beyond things like restyling.
Currently, Pinax only officially provides four foundational projects for you to use, though the developers intend to add some Out-of-the-box projects soon. You can also find some old starter projects in the old Github repo, but these are no longer supported and may have broken dependencies, so use at your own risk.
To see a full list of the officially supported startup projects, type
`pinax-admin setup_project –l`
See here for more details on the official starter projects.
In this guide, I’m going to use a partially configured project “account” that includes the most essential infrastructure apps plus basic user registration. Right now, setting up accounts if you start with the “zero” project is a little tricky (though the developers are planning on fixing that very soon.) From there, I’ll then walk you through the whole process of getting from zero to hero.
3: Use Pinax to generate the project
So, create a new directory where you want your project to live (this nested structure will make it easier to deploy your website in step 6). Cd into that directory, and from there (and with your virtual environment activated), type
`(mysite-env)$ pinax-admin setup_project -b account mysite `
Your system should create a new subdirectory and install the required packages. Now you’ve got a working Django project. Get it started by running
`(mysite-env)$ cd mysite`
`(mysite-env)$ python manage.py syncdb `
`(mysite-env)$ python manage.py runserver `
syncdb will create a SQLite database named dev.db in your current directory. We’ve configured your project to do this, but you can change this simply by modifying settings.py where DATABASES dictionary is constructed. You can find more information about this at the get your database running Django documentation.
runserver runs an embedded webserver to test your site with. By default it will run on http://localhost:8000. This is configurable and more information can be found on runserver in Django documentation.
Go ahead and create a git repo now:
`(mysite-env)$ git init`
`(mysite-env)$ git add .`
`(mysite-env)$ git commit –m “initial commit”`
So now you’ve got a website! Check it out and smile.
4: Install whatever apps you want
Your new website is pretty (because it uses Twitter Bootstrap open-source styling), and has some solid core functions (users can register, change passwords, etc.) But you’re going to want more than that.
To add functionality, we add prepackaged Django apps (or write our own). You can find an extensive directory of apps designed to work with Pinax here. I’ll walk you through installing some apps to get a site with some actual functionality.
If you’re not super familiar with Django, the process of installing and using Pinax apps can seem a bit mysterious. The key thing to remember is that apps are just bundles of code (and sometimes templates) that extend the core codebase of your project. Let’s walk through an example and see how everything works.
Let’s start with the “idios” app, which adds profile functionality to Pinax. You can find detailed installation instructions here, but I’ll repeat the basics.
1. In most cases, you’ll be able to simply type `pip install this_app` (from within your virtual environment, of course!). But for some of the apps that don’t yet have stable releases, pip won’t work automatically. The way that Pinax handles required packages is to put a /requirements directory inside of your project folder which has two files, “base.txt” and “requirements.txt”. Base.txt contains the default packages that were installed with your starter project, plus extra URL’s that tell pip where to look for packages that aren’t in the standard Python Package Index. If you used Pinax-admin to create your project, your base.txt file should already have an extra URL for Pinax apps that are still under development. The other file, project.txt, lets you specify other packages that your project needs. So to install idios:
a. Open myproject/requirements/project.txt
b. Add the line “idios” (In the future, the Pinax developers are planning on providing a list of the latest versions of the different apps so that you can specify which version to use and avoid accidental incompatible upgrades. But that’s not available yet, so just add the name without a version and pip will automatically grab the latest version)
c. In the terminal (with your venv activated), typed `pip install –r requirements.txt`
d. Idios (and any other packages you’ve specified but not downloaded yet) should install themselves
2. Now that we have the package, we need to make Django use it. So open the settings.py file in your project and in the ‘installed apps’ list add:
INSTALLED_APPS = [
3. Hook up idios to your urlconf file (urls.py)
urlpatterns = patterns(“”,
So what actually just happened? You’ll notice that no new files were actually added to your project directory, so where is the extra functionality coming from and how do you use it?
They key is to remember how Python goes about finding code ot use in the first place. When you reference a function in Python, it will sequentially tick down your PATH variable (i.e. the list of places where code packages are included) looking for appropriate bits of code to use. So if you have an actual app folder inside of your project (e.g. if you created your own Django app in this project), Python will look for the code there. If not, and if you’ve included a package name in your “installed apps” list in Settings.py, it will look inside your site packages directory (which will be inside of the virtual environment you created for this project.)
As a shortcut, you can find that directory by typing `cdsitepackages` in the terminal. Do an `ls` inside this folder and you’ll see all the packages you have installed. Note that ‘idios’ is in this list and cd into the directory. This is where all the code for the idios app lives. Unfortunately, most of the current Pinax apps are not extensive documented, so you’ll by and large have to figure out how they work by reading the code.
Take a look at the idios/urls.py folder. Remember above how our urlconf said “url(r”^profiles/”, include(“idios.urls”))” The include means urls your project received that contain ‘profiles’ are being syndicated out to the urls.py file inside the idios package. The urlconf there references functions in the idios/views.py file.
If you want to modify the functionality of an app, you should copy the entire folder into your apps directory of your project, which will put it higher in your path than the site-packages version. That will let you change the code while still keeping your environment reproducible.
5: Customize your site
Awesome. By now, you should have a functional website that allows user registration. You can even got straight to deployment and make this site publicly accessible as is (see Step 6). But you probably don’t want your site covered in filler text and “example.com”. So let’s start making this site your own.
First, let’s change the names that appear throughout the site. Open the file mysite/fixtures/initial_data.json, and change ‘name’ and ‘domain’ to whatever is appropriate. Then in the terminal, run `python manage.py syncdb` to update everything.
Now a word about the Pinax template structure. By default, your project folder will have a templates folder which contains a few basic templates. Most of these inherit from “banner_base.html” or “theme_base.html” which are located inside “Pinax_theme_bootstrap” app which is inside of the site-packages section of your virtual environment.
In Django, the template processors work much like the app PATH; your settings.py file has a template loaders section that looks like this
` # List of callables that know how to import templates from various sources.
TEMPLATE_LOADERS = [
This tells Django that it should first check for templates inside your project folder, then should look inside the apps you have installed. In Pinax, the bootstrap theme is packaged as an app, so the template loader knows to look for templates that get referenced inside of the apps folder. Remember that you can find the source code for your installed apps by typing `cdsitepackages`.
Several of the other installed apps like ‘account’ reference templates that are also held inside of the bootstrap theme.
If you want to modify any of these templates (which you probably will to some extent as you personalize your site), just copy the relevant templates from the bootstrap folder into the templates directory in your project folder. If the templates are inside of folders (e.g. /account/signup.html), make sure that you keep them inside of folders inside of your templates directory.
Let’s try giving ourselves a custom 404 page.
2. cd pinax_theme_bootstrap/templates
3. cp 404.html mysite/templates/
4. emacs 404.html
5. add something crazy
6. open settings.py and change the DEBUG flag to False
7. Load up a broken page, and see your glorious new error
Using these pretty simple customization processes, you should be able to build yourself a full production website. Remember to aim for modularity, and if you build anything useful, consider contributing it back into Pinax!
6: Deploy your app on the web
Pinax is produced by the guys at Eldarion. They also produce Gondor.io, a platform-as-a-service solution that allows you to automatically deploy Django websites to production. So naturally, using Gondor.io is the fastest way to get your Pinax-based website online and publicly accessible.
To use Gondor.io, just head over to their website and sign up for an account. Then follow the directions to configure your website to use Pinax.
At the time of writing, those directions are clear and accurate, with two exceptions
1. ignore the instruction about changing the WSGI entry in your .gondor/config file (which will be clear as you follow the instructions.)
2. In your .gondor/config file, edit the line `staticfiles = false` to say `staticfiles = true`
Do all of that, type `git push primary master`, and you’ve got a live website. Surf over to dyn.com/dns (or your favorite dynamic DNS provider) and set up a dynamic DNS entry to make your personal domain point to your shiny new website.
Congratulations. You’ve got a fully functional publicly accessible website!