Packaging and Distributing Apps

Packaging your apps empower other users to install and run them on their own Dropserver instance with minimal effort. A package contains an archive of the application files and assets, and a manifest describing the app.

Prepare Your App

While an app may run fine in ds-dev or even ds-host, it may need a little more polish before distributing it to a broader audience.

Developers should follow the guidelines for building an app.

Note that the backend code might import code from deno.land/x and possibly other sources. This is acceptable. The ds-host instance will fetch and cache these dependencies as necessary.

Some nice things to include in your app before packaging:

• short-description
• icon
• accent-color
• changelog
• license
• listing of authors, websites, etc…

See the app manifest reference for specific details on each.

Changelog file format

The changelog is a plain text file that describes changes in the app for the benefit of the end-user.

The changes for a given version are preceded by a line containing the version being described. This version must match exactly the version in the app manifest.

Multiple versions can be described in the changelog file, in any order. See example below:

0.1.1

Removed all the explosions. Sorry about that.

0.1.0

Major release! Explosive new features!

Multiple lines of explosive new features in this release!!

0.0.1

Initial release.

Create an App Package

Make sure all built assets get built before running the app packaging tool.

To actually create an app package you must have ds-dev installed. Run the following command:

ds-dev -app=/path/to/app -create-package=/path/to/dist -package-name=my-super-app

Note that the app directory is not necessarily the root of your code repository. See the section on directory structure in building and app.

The directory passed to -create-package is where the package file and manifest will be written.

The -package-name is the base file name of the package. ds-dev will append the version (as specified in the manifest) and the tar.gz extension. In this case: my-super-app-0.1.0.tar.gz.

ds-dev will also output a complete manifest alongside the package with extension .json, as well as a .txt changelog file containing the changes for just the current version, and an app icon. These files get used by the application distribution website generation process (see below).

Use your packaged app

Once a package is created you can use it via ds-dev:

ds-dev -app=my-super-app-0.1.0.tar.gz

Upload the packaged app to your ds-host instance via the user interface. You can then create appspaces for this app. If you don’t have a ds-host instance, you can spin one up temporarily via Docker.

Distribute Your App

Distributing your app means making it very easy to install for other users. In Dropserver a user can install an app by pasting a URL that points to a special JSON file called an “app listing” that contains the list of available versions of an app.

ds-dev can generate this “app listing” just by looking at a directory of packaged apps. to generate the listing run:

$ ds-dev -create-listing=/path/to/packages/dir/

This creates app-listing.json and an index.html files alongside the package files. The listing looks like this:

{
  "versions": {
    "0.6.1": {
      "manifest": "my-super-app-0.6.1.json",
      "package": "my-super-app-0.6.1.tar.gz"
    },
    "0.6.2": {
      "manifest": "my-super-app-0.6.2.json",
      "package": "my-super-app-0.6.2.tar.gz",
      "changelog": "my-super-app-0.6.2-changes.txt",
      "icon": "my-super-app-icon-4226f914.png"
    }
  }
}

Each value of package manifest changelog and icon are paths.

The HTML file is a minimal self-contained web page that echoes some of the information about your app for human consumption. It also includes the listing URL and invites users to install your app in their own Dropserver instance.

The generated files are intended to be served together. Simply upload the whole directory to a static host and you’re good to go.

Release a new version of your app

Thanks to the “app-listing” users will be able to install the latest version of your app soon after you publish. To ensure this process works well please ensure the following:

• Increment the version of the app regardless of how small the change is. If you do not change the version your existing users will not get the latest changes. Version changes should be in accordance with the semver specification.
• Add an appropriate entry to the changelog.
• Remember to rebuild all assets and run all tests before creating the new version package.
• Create package files for the new version using the same -package-name as before, and output the files alongside the older versions.
• Run the -create-listing command again. The app-listing.json and index.html files will be overwritten.
• Upload or sync all files to your static site server. Make sure the URL for app-listing.json doesn’t change!

Dropserver instances that have your app installed from this URL will eventually pick up on the new version and suggest its installation to your users.

Move your published app to a new URL

If you move the published site to a new address, users who installed your app using the previous address will no longer get updates. To give these users a better experience, let them know what the new address is. You can do this in one of two ways:

• Set up your static site to return a status of 301 Moved Permanently or 308 Permanent Redirect and a Location header with the new URL when requesting app-listing.json.
• Change the app-listing.json at the old URL to include the new-url field that points to the new URL:

{
    "new-url": "https://<the new URL for your app>"
}

In both cases the new URL should point to the new URL for app-listing.json.

With either of these changes Dropserver will invite users to update the link for the app.

What Next?

• Build a hello world app in this tutorial.
• Report any problems with ds-dev in github issues.
• Question or comment? Find me, the developer, on Mastodon or on my site.