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:
Subcommand | Purpose |
build | Creates a new package from a .conf file. See Creating a Package from a package script |
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 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
andprovides
only when the package is notready
.
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
Package: | Go_1.1.2 |
---|---|
FQN: | package::/::Go_1.1.2 |
State: | ready |
Dependencies: | os: linux |
package: git | |
package: bzr | |
package: mercurial | |
Provides: | runtime: go |
runtime: go-1.1 | |
runtime: go-1.1.2 | |
Environment: | GOPATH="/opt/apcera/go" |
GOROOT="/opt/apcera/go1.1.2.linux-amd64" | |
PATH="/opt/apcera/go1.1.2.linux-amd64/bin:$PATH" |
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
my-package-script.conf
. -
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
--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
.