Welcome to the SproutCore Deployment Guide.  Once you've built your application, this guide will tell you everything you need to know about putting your application into production, including important best practices that will get you the best performance possible.

How to Build

First you'll need to build your app for deployment. You do this via the sc-build tool:

cd /path/to/my_sproutcore_apps

sc-build --clean --include-required

sc-build produces a local directory hierarchy similar to this:

tmp/

build/

cache/

staging/

You're interested in the tmp/build/static directory. Inside it looks something like this:

tmp/

build/

static/

sproutcore/

animation/

bootstrap/

...

todos/

     en/

7d4f2f0a289b625864d5a2f18bfb554fb28287ea/

index.html

javascript.js

     es/

7d4f2f0a289b625864d5a2f18bfb554fb28287ea/

index.html

javascript.js

sproutcore holds SproutCore's frameworks while the rest are your apps.

The en and es folders carry English and Spanish-localized versions of your app, respectively. Of course you can add additional localizations.

That nasty hex string (7d4f2f0a289b625864d5a2f18bfb554fb28287ea) is your application's build number.

Build numbers are hashes of your application's content. When you modify your app in any way and re-run sc-build, it will automatically generate and assign it a new build number.

What to Copy and Where to Copy It

SproutCore hard-codes resource paths, so things have to be in a certain location in your web server's document directory. Assuming your web server's document root is /var/www, you should copy your entire local static directory into it, so it looks like this:

var/

www/

static/

sproutcore/

animation/

bootstrap/

...

todos/

en/

7d4f2f0a289b625864d5a2f18bfb554fb28287ea/

index.html

javascript.js

Now things are in the right place for the web client to find them and you can access your application at http://example.com/static/todos/en/7d4f2f0a289b625864d5a2f18bfb554fb28287ea/index.html.

However that url is rather ugly (intentionally so for versioning purposes). Fortunately your can symlink your app's index.html anywhere you like since it hardcodes its paths. For instance, if we wanted our todos application available at http://example.com/todos we could have the following web document root directory structure:

var/

www/

todos -> static/todos/en/7d4f2f0a289b625864d5a2f18bfb554fb28287ea

static/

sproutcore/

animation/

bootstrap/

...

todos/

en/

7d4f2f0a289b625864d5a2f18bfb554fb28287ea/

index.html

javascript.js

Here /var/www/todos is a symlink to /var/www/static/todos/en/7d4f2f0a289b625864d5a2f18bfb554fb28287ea/index.html.

When time comes to redeploy, you'll want to write a script that somehow copies (rsync, scp, git) your local tmp/build/static folder to your web server's /var/www/static directory and updates your symlinks to point at their newer build numbers.

Deployment Notes

This will be expanded into a full guide, but here are the highlights that are most important:

1. All SproutCore apps have a single index.html and other static resources.  
1. You should deploy your app so that all the static resources are accessed under a common URL (say /static).
2. The actual URL a user visits to load your app should appear somewhere else.  Usually you will set this up by creating a symbolic link to the index.html under static.  
3. For example, your app might be available at /my_app, which is symlinked to /static/my_app/en/BUILD_NUMBER.  The static assets are all hosted under /static/my_app and /static/sproutcore
2. Caching
1. MOST IMPORTANT: Configure your web server to serve any static resources with a 1-year expiration header.
1. This is most important thing you can do for performance.  It means that once a user loads your SproutCore app 1 time, they will never even have to go back to your server until you roll out a new version or until their cache expires.
2. Some people try to set the cache header to 10-years instead of 1-year since 10-years is the maximum time.  We do not recommend this.  Some proxies on the internet are misconfigured and assume any cache header > 1-year must be a mistake and so they ignore it.
2. SECOND MOST IMPORTANT:  Configure your web server so that any URL outside of your static resources URL are service with a small (10min or less) or NO cache.
1. With this design, when a user visits /my_app, the browser will go back to your server to get the very latest index.html.  This way when you deploy a new version, it will be served up immediately.
2. The index.html references only assets in your static resources area so ALL other resources will be served using caching.
3. Other Configuration Tips
1. Turn on GZIP compression.  SproutCore's JS itself is about 500Kb, but it is designed to compress down to just under 100K over the wire.  Gzipping can shorten your app load time by almost 500msec over slow connections.
2. Turn on ETag support.  Etage and If-Modified-Since will allow browsers to revalidate cached items without having to fetch them.  This is not as good as simply keeping data cached in the web browser, but it is second best.
3. Do not use file extensions for any dynamic URLs. 
1. Some proxies on the internet are misconfigured.  They will look at the file extension (i.e. /contacts/index.json) and if the extension looks like something the proxy things should be a static asset, it will cache the file no matter what your HTTP headers say.
2. The best thing is to simply omit the file extension from dynamic URLs.  This will cause proxies to respect your HTTP caching headers instead.
3. It's a common practice with some web frameworks to use file extensions to let you fetch your data in different forms (i.e. /contacts.html gets HTML, contacts.xml gets XML, contacts.json gets JSON).  Don't do this; it can break with some proxies.  Instead, we recommend you follow Google's practice with Gdata and use the "alt" query instead.  (i.e. /contacts?alt=html, /contacts?alt=xml, /contacts?alt=json)