-
Notifications
You must be signed in to change notification settings - Fork 125
Quick Start
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.
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.
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:
- https://myapplication.com/myapp/getdown.txt
- https://myapplication.com/myapp/digest.txt
- https://myapplication.com/myapp/application.jar
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.
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.
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.
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.
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.
See the main documentation page for more details.