____                                               __     _____  __                __              
   / __ \ ____   _____ __  __ ____ ___   ___   ____   / /_   / ___/ / /_ ____ _ _____ / /__ ___   _____
  / / / // __ \ / ___// / / // __ `__ \ / _ \ / __ \ / __/   \__ \ / __// __ `// ___// //_// _ \ / ___/
 / /_/ // /_/ // /__ / /_/ // / / / / //  __// / / // /_    ___/ // /_ / /_/ // /__ / ,<  /  __// /    
/_____/ \____/ \___/ \__,_//_/ /_/ /_/ \___//_/ /_/ \__/   /____/ \__/ \__,_/ \___//_/|_| \___//_/     
                                                                                                       

Use DocumentCloud to publish PDFs for humans.

• Quickly publish files hosted by DocumentCloud with Google App Engine and serve them on the web for free.
• Collect documents together as projects
• Post an RSS feed and sitemap that promote the latest documents.
• Link similar documents together with blog-style tagging.

• Working demonstration

Go to https://appengine.google.com/. Don’t download the SDK. Don’t read the docs. Just create an account and mint a new application with a name like my-document-stacker. It serves as the unique identifer for your app inside the Google system, and the namespace where it will first appear online (i.e. http://my-document-stacker.appspot.com/).

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-document-stacker, but you should substitute whatever you’re calling your version.

$ virtualenv --no-site-packages my-document-stacker

Now jump into the directory it creates.

$ cd document-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-document-stacker.git project

And jump in and get ready to work.

$ cd project

In the project folder you will find a file called app.yaml. It contains the basic configuration for your Google App Engine site. You only need to make one little change: Replace my-document-stacker with the application id you registered in step one.

application: my-document-stacker

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.

Note that you’ll see me using python2.5 throughout, instead of the usual python command. This is because I work in Ubuntu and I’ve found that Google App Engine is not compatible with newer versions of Python. I suspect is is the case with other operating systems, but I’m not sure. So, I’d recommend using python2.5 but, as always, your mileage may vary.

$ python2.5 manage.py runserver

You’ll learn how to add your own documents later, but for now we’ll work with an example file: a letter from the USC president advising students against attending raves. Jump back to your first terminal shell and drop the following line, which instructs our loaddocument management command to follow instructions in the usc-president-warns-about-raves configuration and create a new document in the test site we just launched at http://localhost:8000.

$ python2.5 manage.py loaddocument usc-president-warns-about-raves --host=localhost:8000

If everything clicked, you should see your demo site up and running with the USC document at http://localhost:8000/.

Once everything’s set, deploying your application to Google App Engine only takes a single command. Here it is.

$ python2.5 manage.py update

You’ll run the same loaddocument command from step five, but drop the host option. It will post to your live site by default, so it’s unnecessary this time around.

$ python2.5 manage.py loaddocument usc-president-warns-about-raves

You should now see your starter site up and running at http://my-document-stacker.appspot.com. You might draw errors for a few minutes as the app builds its indexes, but don’t worry. It’ll be ready after you have a cup of coffee.

Before you can publish your own document, you’ll need to learn about our YAML-based configuration system. But don’t worry, it’s not that hard.