Skip to content
Michael Bayne edited this page Nov 20, 2018 · 17 revisions

A quick introduction to Getdown

Here we'll walk you through the basic structure of a Getdown project and the steps needed to create and serve it.

Note: there is also a simple demonstration app which you can inspect to see all of these parts fully assembled.

Metafiles

A Getdown project uses two metafiles: getdown.txt and digest.txt. The getdown.txt file you create yourself (we'll explain that in a moment), and the digest.txt file is created by running a tool on the contents of your project.

Note: at some point we changed the algorithms used by the digest.txt file to hash and sign the contents of applications (because the state of the art hashing algorithms in 2004, when Getdown was created, were eventually deprecated due to being too easily broken). It was not possible to do this in a way that was backwards compatible, so we had to introduce a second digest2.txt file. Getdown uses the digest2.txt file when it exists. So even though the documentation refers to a single digest.txt file, now all Getdown app distributions contain both a digest.txt file and a digest2.txt file.

If your app has never shipped with the old digest.txt file, you can omit it from your app distribution and only use a digest2.txt file, but it's often simpler to just include them both.

getdown.txt

The getdown.txt file contains everything that Getdown needs to know to deploy and update your application. Here we'll show a very basic getdown.txt file, and you can refer to this full description for info on all of the configuration options.

Here is a basic getdown.txt file, which we'll explain in comments in the file:

# The URL from which the client is downloaded
appbase = https://myapplication.com/myapp/

# UI Configuration
ui.name = My Application

# Application jar files
code = application.jar

# The main entry point for the application
class = myapplication.MyApplication

The appbase is the URL from which your client will be downloaded. All of the file names in getdown.txt are relative to this URL. For example, in the above case, the following files would be downloaded:

digest.txt

The digest.txt file is created by running com.threerings.getdown.tools.Digester on your Getdown project directory. First download getdown-core-X.Y.jar from Maven Central.

Now, supposing you have a directory structure that looks like so:

myapp/getdown.txt
myapp/application.jar

You can generate the digest.txt file like so:

% java -classpath getdown-core-X.Y.jar com.threerings.getdown.tools.Digester myapp

Where myapp is the path to the myapp directory that contains your client files. This will report:

Generating digest file 'myapp/digest.txt'...

And you should then see a digest.txt file in your myapp directory along with your client.

Instructions for generating the digest.txt as a part of your application build can be found on the build integration page.

Hosting

The myapp directory now contains everything you need to serve your application via Getdown. You will need to put the contents of myapp on your webserver so that it can be downloaded via the https://myapplication.com/myapp/ URL described in your getdown.txt file. The webserver does not need to support any special features, it just needs to serve the contents of the myapp directory via normal HTTP.

Testing

To test that your application is working. You can do the following: download the getdown-launcher-X.Y.jar client jar file from Maven Central, then create a "stub" installation directory that looks like the following (rename the downloaded getdown-launcher-X.Y.jar to getdown.jar):

myapp/getdown.jar
myapp/getdown.txt

But the contents of the getdown.txt file in your stub directory need contain only a single line:

appbase = https://myapplication.com/myapp/

Eventually, you will create per-platform installers that create this stub directory and set up application launchers that are appropriate to the platform in question. But for now, we can run Getdown manually from the command line.

With the above directory structure set up, run the following command:

% java -jar myapp/getdown.jar myapp

This will run Getdown, and cause it to download and validate your application and then execute it.

Installers

Creating per-platform installers is unfortunately a more complex process than can be described in this quick start. See the installers page for detailed instructions.

Updating Your App

In order to update your app, you simply create a new staging directory for your client with updated application jar files (and an updated getdown.txt if you need to add additional data to your app), rerun the Digester to generate an updated digest.txt and then upload the contents of myapp to your webserver, overwriting the old myapp directory contents.

Getdown will check the last modified timestamp of the getdown.txt file on the web server and if it is newer than the version the client has locally, it will download any files that have changed. Files that have not changed (as determined by their MD5 hash in digest.txt) will not be redownloaded.

Note that this is how Getdown behaves in versionless mode. It is also possible for applications to provide an explicit version number for each application and control exactly when Getdown attempts to download a new version of the application. For details on this mode of operation see the documentation on explicit-versioned mode.

More Details

See the main documentation page for more details.

Clone this wiki locally