This tutorial will walk you through the process of installing Table Stacker and publishing an example.
01. Install the code on your computer¶
It’s not required, but I recommend creating a virtual environment to store your application. I like to do this with the Python module virtualenv, which creates a walled-off garden for the Python code to work without distraction from the outside world. If you don’t have it, you’ll need to install it now, which just might be as easy as
$ pip install virtualenv # Or maybe ... $ sudo easy_install install virtualenv # Or, if you're in Ubuntu ... $ sudo apt-get install python-virtualenv
Once you have virtualenv installed, make it happen by navigating to wherever you keep your code and firing off the following. I’m going to call this project my-table-stacker, but you should substitute whatever you’re calling your version.
$ virtualenv --no-site-packages my-table-stacker
Now jump into the directory it creates.
$ cd my-table-stacker
Activate the private environment with virtualenv’s custom command.
$ . bin/activate
Download the latest version of the code repository into a directory called project.
$ git clone git://github.com/datadesk/latimes-table-stacker.git project
And jump in and get ready to work.
$ cd project
Install our app’s Python dependencies.
$ pip install -r requirements.txt
Create the project’s database
$ python manage.py syncdb $ python manage.py migrate
02. Build the example tables¶
You’ll learn how to layout your own data later, but for now we’ll work with the example files. Jump back to your first terminal shell and drop the following line, which instructs our build management command to bake out a static site using the instructions in settings.py and the table recipes in the yaml directory.
$ python manage.py build
03. Launch the static version of the site¶
You’ll want to run this step in a new terminal shell. So open up a new window or tab, navigate to the project directory and fire off the following. It is a Django management command that will start a test version of the site on your machine, tailored to serve the static files we used created.
$ python manage.py buildserver
04. Check it out¶
If everything clicked, you should see your demo site up and running with all the example tables at http://localhost:8000.
05. Deploy your app¶
The static files we’ve created in your build directory could probably be served from most common web servers. So, if you’ve already got yours worked out, you can just stop here and deploy that folder where you like.
However, the app is prepared to help you easily deploy to Amazon S3. To make that happen, you’ll need to do a little set up. First, go to aws.amazon.com/s3 and set up an account. Then you’ll need to create a bucket for storing our files. If you need help there are some basic instructions here.
Next configure the bucket to act as a website. Amazon’s official instructions say to do the following:
In the bucket Properties pane, click the Website configuration tab. Select the Enabled check box. In the Index Document Suffix text box, add the required index document name (index.html).
Before you leave that pane, note the URL at the bottom. This is where your site will be published.
Now, set your bucket name in the settings.py file.:
AWS_BUCKET_NAME = 'table-stacker'
Next, install s3cmd, a utility we’ll use to move files back and forth between your desktop and S3. In Ubuntu, that’s as simple as:
$ sudo apt-get install s3cmd
If you’re Mac or Windows, you’ll need to download the file and follow the installation instructions you find there.
Once it’s installed, we need to configure s3cmd with your Amazon login credentials. Go to Amazon’s security credentials page and get your access key and secret access key. Then, from your terminal, run
$ s3cmd --configure
Finally, now that everything is set up, publishing your files to s3 is as simple as:
$ python manage.py publish
Once you do that, your site should appear at the the link provided in your AWS console. If you want to bind that to a subdomain of your site, say, www.tablestacker.com, you need to create a new CNAME record in your domain’s DNS registration. You also need the name of your bucket to line up with the subdomain. Don’t take it from me. Read the detailed instructions provided by Amazon.
For example, if you have registered domain, www.example-bucket.com, you could create a bucket www.example-bucket.com, and add a DNS CNAME entry pointing to www.example-bucket.com.s3-website-<region>.amazonaws.com. All requests to http://www.example-bucket.com will be routed to www.example-bucket.com.s3-website-<region>.amazonaws.com.
More documentation on that is available here.
06. Publish you own data table¶
Before you can publish your own data table, you’ll need to learn about our YAML-based configuration system. But don’t worry, it’s not that hard. You can read about it in the configuration section or school yourself by mimicking the examples files in the project’s yaml subdirectory folder. Then, doing the following:
$ python manage.py build $ python manage.py publish