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
- 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
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
file. In addition, provides and dependencies have a name designed to make each more specific. For example, an
os dependency might have the name
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.
apc package command has the following subcommands:
|build||Creates a new package from a
|create||Creates a new package from local sources using staging pipelines. See Creating a Package using staging pipelines|
|delete||Delete an existing package|
|download||Download the raw package contents to a local file|
|export||Export package(s) into a single package file|
|from file||Create a new package from a tarball|
|list||Show all packages in the current or specified namespace|
|replace||Replace an existing package with a new one|
|show||Show attributes of a package|
|update||Change attributes of a package|
Once a package exists, the
update subcommands work together.
show enables you to see the state of all changeable attributes, and
update enables you to change any of them.
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
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
providesonly when the package is not
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.
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:
Assemble the required elements in a working directory.
Create a package configuration file with the *.conf extension in the same working directory, for example
Add a build script to the configuration file.
Build the package using the following command:
apc package build my-package-script.conf
You can use the
--nameoption to specify a different name, for example:
apc package build --name my-custom-package
You can use the
--stagingoption 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
- Uses a stager (and staging pipeline) called the
compilerwhich 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
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.