The Marquee SDK is under active development. For production use, the Yeoman Generator is preferred.

Marquee provides a content platform on which applications can be built. We use this platform to build editorial tools and web publications. Over the past few years, we've explored all kinds of strategies for building and maintaining sustainable content-driven applications, and have compiled these into the marquee-sdk, an open-source, public domain software package aimed at making this kind of development work easier.

The Marquee SDK is highly opinionated and is not required for developing on Marquee. We offer a standard REST API if you want to roll your own solution. We've made an effort to keep our SDK pretty decoupled, so even if you don't care for all our decisions, there should be something there you'll find interesting.

The Marquee SDK will generate a Python web application using the Flask microframework. It includes an Ubuntu 14.04 Server development environment which is managed by Vagrant. Provisioning development and production environments is managed with Ansible, and comes with some handy deployment scripts for use with Digital Ocean. Jinja is used for templating, indented Sass generates our stylesheets, and JavaScript is compiled from CoffeeScript sources. Applications generated by the Marquee SDK connect to our REST API using marquee-content.

If you haven't worked with any of these technologies, don't worry. The Marquee SDK is designed to Just Work™ as long as you follow the instructions below to configure your system.

This guide is going to assume you're developing on the most recent stable release of Mac OS X. If you're using Linux or Windows, we'd love to work with you to develop guides for those platforms. At Marquee, we build everything on our local Macs and deploy to an Ubuntu Server running on Digital Ocean. It's a workflow that we've found works really well.

The virtualenvwrapper package is a handy way to create isolated Python environments for your project and pip is used to install our Python development dependencies.

To simplify things, we recommend using Homebrew to install both. Once the brew command is available on your system, installing virtualenvwrapper and pip is a piece of cake.

→ brew install python

Follow the instructions on screen to configure your bash shell to include virtualenvwrapper's workon, mkvirtualenv, and rmvirtualenv commands.

Add the following to ~/.bash_profile

export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
export PIP_VIRTUALENV_BASE=$WORKON_HOME
export VIRTUALENVWRAPPER_PYTHON='/usr/bin/python'
export PIP_RESPECT_VIRTUALENV=true
if [[ -r /usr/local/bin/virtualenvwrapper.sh ]]; then
    source /usr/local/bin/virtualenvwrapper.sh
else
    echo "WARNING: Can't find virtualenvwrapper.sh"
fi

Vagrant manage virtual machines. The Marquee SDK uses virtual machines to create consistent, repeatable development environments for you and your team. Match made in heaven? ❤️ You bet.

Install Vagrant by installing the latest stable version (1.6.x) using the official binary.

The Marquee SDK generates an application that we call a Marquee Runtime. It's just a Flask application, and it can be a nice starting point for building web publications, even if you're not using Marquee to publish them.

For the purposes of this guide, we'll create a Marquee Runtime that collects curated public domain short stories. Let's call it gutenberg.

The first thing you'll want to do is create a Python Virtual Environment (virtualenv) for the project.

→ mkvirtualenv gutenberg
New python executable in gutenberg/bin/python2.7
Also creating executable in gutenberg/bin/python
Installing setuptools, pip...done.
(gutenberg) → 

Now, we can install the Marquee SDK from directly from the git repository using pip.

(gutenberg) → pip install -e git+https://github.com/marquee/marquee-sdk.git#egg=marquee_sdk

The Marquee SDK package and all its dependencies will be install into the gutenberg virtualenv.

To continue work on your project at a later point, all you need to do is make sure that the virtualenv is activated using workon gutenberg before issuing any commands.

With the Marquee SDK installed, you will now have access to the marquee program. This is a command line interface to Marquee and will help you start, deploy, and manage your projects.

Let's create a Marquee Runtime for our example project using the startproject subcommand

(gutenberg) → marquee startproject gutenberg

You'll be first asked to assign a Private IP Address to the system. By convention, we use the 10.0.1.x address space for our Marquee Runtime projects, so choose something that's not in use, say, 10.0.1.10.

You'll next be asked for a Marquee API Token. You can get one of these from us, but for now use this read-only token for this example.

r0_35d6671277c356e582c07f490121483dc05d6a40

We'll want to point this private address to a .local domain name. This will make it easy for use to connect to the development environment from a browser. Once the project is complete, you'll be reminded to add a new entry to your /etc/hosts file. In our example, you'll add the following line to /etc/hosts/:

10.0.1.10       gutenberg.local

Now that everything's in place, you can just change into your new project's directory and bring up our development environment using the vagrant up command. By brining up the machine, you will kick off our Ansible provisioning playbooks which will install all the software and packages we need for our runtime, as well as turn on all the server's services needed to host it.

(gutenberg) → cd gutenberg
(gutenberg) ./gutenberg → vagrant up
...

Once provisioning is complete, you'll be able to visit your new project in your browser. If you're following along, visit http://gutenberg.local.

You may see the following message when starting up a new virtual machine using vagrant up:

fatal: [10.0.1.10] => SSH encountered an unknown error during the
connection. We recommend you re-run the command using -vvvv, which will
enable SSH debugging output to help diagnose the issue

This generally happens when you are rebuilding a destroyed box and SSH caches some information about the old connection. Running vagrant provision should pick things back up from where it left off.