Creating and Managing Packages

This section describes how to author package scripts for creating custom packages. To understand how packages are used within the system, refer to the package resolution section of the documentation.

• Overview of packages
• Package commands
• Using package show
• Creating custom packages from package scripts
• About the build process and the compiler stager
• Creating a Package with Staging Pipelines
• Creating an App from a Package
• Processing Large Packages

Overview of packages

A package is a collection of binary data, typically in a tarball, and associated metadata in a JSON file. A job, including an app, service, service gateway, stager, or anything else that runs in Apcera, starts as a package.

Apcera provides packages for operating systems such as Ubuntu 14.04, software such as nginx-1.11.0, and runtimes such as go-1.6. Refer to the Apcera Package Scripts repository for a list of the package scripts that Apcera provides. If you need a package that is not provided out-of-the-box, you can write your own package following the steps and examples in this article.

Package metadata includes provides and dependencies, and tells other packages what kinds of capabilities they can look for in this package. Each provide and dependency has a type, which can be either os, package, runtime, or file. In addition, provides and dependencies have a name designed to make each more specific. For example, an os dependency might have the name ubuntu. A runtime dependency might have the name ruby, but it might have a more specific name, say ruby 1.9.3. Stagers use provides and dependencies to arrive at a specific set of packages that satisfies all dependencies.

See the package example for more information.

Package commands

The apc package command has the following subcommands:

Once a package exists, the show and update subcommands work together. show enables you to see the state of all changeable attributes, and update enables you to change any of them.

The list subcommand works the same as it does for other Apcera entities. It produces a list of all packages in the user's current namespace or the namespace provided with the optional --namespace flag.

The build command is used to create a package and is described in the next section.

Apcera typically has several packages of given type. It picks the best match it can when resolving packages for your app. For more details, refer the tutorial on resolving packages. You can modify the package's dependencies and provides only when the package is not ready.

Using package show

The package show command is used to view a package's environment variables. It also shows detailed information about an individual package, including its dependencies and what it provides.

Example:

apc package show Go_1.1.2

Creating custom packages from package scripts

A package script uses a simple build definition format, which tells Apcera which sources and dependencies the package requires. Apcera's package configuration format is similar to those of services like Homebrew or MacPorts.

The workflow for creating a custom package from a package script script is as follows:

1. Assemble the required elements in a working directory.

2. Create a package configuration file with the *.conf extension in the same working directory, for example my-package-script.conf.

3. Add a build script to the configuration file.

4. Build the package using the following command:

    apc package build my-package-script.conf
   

   You can use the --name option to specify a different name, for example:

    apc package build --name my-custom-package
   

   You can use the --staging option to specify a stager other than the compiler stager, for example:

    apc package build go-1.2.conf --name /sandbox/dev::test-go-pkg --staging /::my-go-stager
   

About the build process and the compiler stager

When you build an Apcera package:

• Looks in the directory containing the configuration file for the resources specified in the configuration file.
• Gives the package the name supplied in the configuration file or overriden using --name.
• Uses a stager (and staging pipeline) called the compiler which is a special stager that is designed to build packages.
• Uploads the package file with the *.cntmp extension to the cluster.

The compiler stager downloads the code, validates dependencies, compiles the source, sets up env variables, then snapshots the file system to create a package.

The elements of a package script, including the BASH build script, are mapped to a PackageFormula JSON object that is a parsed package script file that can be understood (built) by the compiler stager. The commands in the build() portion of the script are interpreted and processed by the compiler stager.

Creating a Package with Staging Pipelines

The apc package create command creates a package from local source code, similar to how you use apc app create to create an application from local source code. But where the apc app create command creates a new package (the "application package") and links it to a newly created job, the apc package create command simply creates the application package for later use.

For example, suppose you have an HTML web application you want to make available as a package. The following command creates a new package ("website-package") from the example-static sample application:

apc package create website-package --path sample-apps/example-static --provides package.website
Deploy path [sample-apps/example-static]:
╭───────────────────────────────────────────────────────────────╮
│                        Package Settings                       │
├───────────────────┬───────────────────────────────────────────┤
│              FQN: │ package::/sandbox/admin::website-package  │
│        Directory: │ /src/sample-apps/example-static           │
│ Staging Pipeline: │ (will be auto-detected)                   │
╰───────────────────┴───────────────────────────────────────────╯

Is this correct? [Y/n]:
Packaging... done
Creating package "website-package"... done
Uploading package contents... 100.0% (809/809 B)
[staging] Subscribing to the staging process...
[staging] Beginning staging with 'stagpipe::/apcera::static-site' pipeline, 1 stager(s) defined.
[staging] Launching instance of stager 'static-site'...
[staging] Downloading package for processing...
[staging] Validating an index.htm or index.html file exists
[staging] Staging is complete.
Success!

As you can see in the above output, the static-site staging pipeline was automatically selected based on the contents of the source directory (an index.html file, in this case). By default, all files and folders at the specified --path are included in the generated package. You can exclude files from the built package by adding a .apcignore file to the target path. See Excluding files from built packages.

You can then create an application from the new package with the apc app from package command, for example:

apc app from package mywebsite \
-p /sandbox/admin::website-package \
-routes mysite.example.apcera-platform.io

Creating an App from a Package

You can create an app from a package using the following command syntax:

apc app from package <app-name> -p <pkg-name> [optional-args]

Creating an app from a package may be useful for certain types of packages, such as when you want to use a capsule to host a service provider. When you snapshot a capsule, the snapshot is saved as a package. Using this package you can create an app, for example:

apc app from package mysql-app -p snapshot-mysql-cap-142670904 -dr --start-cmd 'sudo /bin/sh /usr/bin/mysqld_safe

To get the package name, run command apc package list.

Processing Large Packages

See how to upload and create large package files.