Packages that are either stored locally on your machine or are accessible via a network drive as a zip file can be installed by using their file system path. The path can be absolute or relative.

Make sure your package zip file has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the file without the extension will be used as the package name.

Installation

To install a package from a local file, use the path like so:

Note if using Windows, you need to escape backslashes in the command parameter.

Relative paths will start in the directory where the command is being run from.

In box.json

You can specify packages from file endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

Packages hosted on a website as a zip file can be installed by using the direct URL to the package. Both HTTP and HTTPS URLs are supported. If the URL returns a 301 or 302 redirect, it will be followed until the package is reached.

Make sure your package zip file has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the following rules will be decided to determine the name of the package:

1. If the URL has the zip file name in it, the name without ".zip" is used.

2. If the URL contains github.com, the repo name will be used.

3. Otherwise, the entire URL will have non alpha-numeric characters removed and used.

Installation

To install a package from a website, use the full URL like so:

install http://www.site.com/myPackage.zip

In box.json

You can specify packages from HTTP(S) endpoints as dependencies in your box.json in this format:

{
    "dependencies" : {
        "myPackage" : "http://www.site.com/myPackage.zip"
    }
}

Packages that are either stored locally on your machine or are accessible via a network drive in an unzipped folder can be installed by using their file system path. The path can be absolute or relative.

Make sure your package folder has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the last folder in the path will be used as the package name.

Installation

To install a package from a local folder, use the path like so:

install /var/libs/myPackage/

Note if using Windows, you need to escape backslashes in the command parameter.

install C:\\websites\libs\\myPackage\\

Relative paths will start in the directory where the command is being run from.

install libs/myPackage/
install ../../libs/myPackage2/

In box.json

You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

{
    "dependencies" : {
        "myPackage" : "/var/libs/myPackage/"
        "myPackage2" : "C:\\websites\libs\\myPackage\\"
    }
}

ForgeBox is an online registry of packages run by Ortus Solutions. The web UI for ForgeBox is located at http://forgebox.io. Signing up for a ForgeBox account is quick, easy, and free. You will need your own account to post packages, but anyone can browse and install packages anonymously.

Installation

Every package on ForgeBox has a unique slug. To install a package, use the slug like so:

install cborm

You can also specify the version of a package you want to install from Forgebox.

install coldbox@3.8.1

Given the install command above, if the file ~/.CommandBox/artifacts/coldbox/3.8.1/coldbox.zip exists on your hard drive, the installation will not connect to Forgebox at all. It will be a completely offline installation. This only works when you type an exact version that includes a major, minor, and patch number.

In box.json

You can specify packages from ForgeBox as dependencies in your box.json in this format:

{
    "dependencies" : {
        "coldbox" : "^4.1.0"
    }
}

info The caret ^ means that the update command will update minor releases but not major releases.

ForgeBox Pro

For companies who want to host internal code endpoints for private packages, we will soon support an Enterprise version of ForgeBox that can be installed behind your company's firewall. Please contact us if this feature interests you.

ForgeBox namespace

Inside CommandBox, use the forgebox namespace to search for packages or show packages of your choosing.

forgebox search

The first command to try out is "forgebox search". It takes a single parameter which is a string to perform a case-insensitive search for. Any entry whose title, summary or author name contains that text will be displayed:

forgebox search awesome

forgebox show

The "forgebox show" command takes several parameters and is pretty flexible. The first way to use it is to just view the details of a single entry using the slug.

forgebox show coldbox

You can get lists of items filtered by package type (modules, interceptors, caching, etc) and ordered by popular, new, or recent. Here's some examples:

forgebox show plugins
forgebox show new modules
forgebox show recent commandbox-commands

Too many results on one page? Use the built-in pagination options:

forgebox show orderby=new maxRows=10 startRow=11

Or just pipe the output into the built-in "more" or "grep" command.

forgebox show new | more
forgebox show modules | grep brad

forgebox show help

If you have troubles remembering the valid types or order by's, remember you can always hit "tab" for autocomplete within the interactive shell. Adding "help" to the end of any command will also show you the specific help for that command.

forgebox help
forgebox search help
forgebox show help

forgebox types

The list of types in ForgeBox is dynamic so we don't list them out in the help. Instead, we made a handy "forgebox types" command to pull the latest list of types for you.

forgebox types

The Java endpoint is capable of downloading and installing any version of Java in the AdoptOpenJDK API. Use the java search command to search the API to find what Java versions are available. The endpoint will use the local artifacts cache.

NOTE: If you simply want to start a server with a given version of OpenJDK, you don't need to use this endpoint directly, You can ask CommandBox to use a specific java version and it will handle the installation for you as well as re-using identical Java installs across servers.

Installation ID

The installation ID consists of a series of identifiers separated by underscores that describe the Java version, type, JVM, etc that you want installed.

install java:<version>_<type>_<arch>_<os>_<jvm-implementation>_<release>

An example utilizing every option would be

install java:OpenJDK8_jre_x64_windows_hotspot_8u181b13

However, everything is optional except the major version. These are also valid installation IDs

install java:openjdk8
install java:openjdk8_jre
install java:OpenJDK8_jdk_8u181b13

ID Definitions

Here are the possible options for each section of the ID.

• version - openjdk8, openjdk9, openjdk10, etc...

• type - jdk, jre

• arch - x64, x32, ppc64, s390x, ppc64le, aarch64

• os - windows, linux, mac

• jvm-implementation - hotspot, openj9

• release - latest, jdk8u172, jdk8u172-b00, etc...

Defaults

For items not specified in the endpoint ID, the endpoint will default as follows:

• type - jre

• arch - Whatever the current OS arch is

• os - Whatever the current OS is

• JVM-implementation - hotspot

• release - latest

Installation Folder

The name of the folder that Java is installed into will mirror the ID you use. This means two different installation IDs that resolve to the exact same Java version may end up in different folders. We do this for a couple reasons. One of which is simplicity, the other is that if you have configuration expecting a specific folder name, Mac users and Windows users may get a different download, but if the id is simple java:openjdk8_jdk, they would both install into a folder called openjdk8_jdk.

This endpoint will NOT edit your registry, create any symlinks, or add environment variables. It will simply drop the Java installation into a folder so you can point servers at it. You are free to use one of these Java installations in such a manner, but we don't do this by default so you can install as many java versions as you like and they don't fight with each other.

Packages hosted in private S3 buckets can be installed directly from S3 URLs.

Installation

To install a package from a S3 bucket, use a URL like so:

install s3://my-private-bucket/myPackage.zip

The S3 endpoint will automatically determine which region your bucket is in order to download your package. You can, however, bypass this automatic bucket region resolution by encoding the region of your bucket into the S3 path by using a : after the bucket name:

install s3://my-private-bucket:eu-west-2/myPackage.zip

Info If your S3 path does not end in .zip the S3 endpoint will make a HEAD request to S3 for the package path to determine if your package exists at that location. If it does not, then .zip will be appended to your S3 path and that new path will be used as the location of your package. This means it is possible for you to specify a package without adding the .zip extension: s3://my-private-bucket/myPackage.

In box.json

You can specify packages from S3 endpoints as dependencies in your box.json in this format:

{
    "dependencies" : {
        "myPackage" : "s3://my-private-bucket/myPackage.zip"
    }
}

Authentication

In order for S3 endpoints to be resolved, CommandBox needs an AWS access key and AWS secret key belonging to an AWS IAM user or role that has permission to get objects from the S3 bucket where the package is stored. The access and secret keys can be set in CommandBox settings either globally:

config set endpoint.s3.aws_access_key_id=XXXXXXXXXX
config set endpoint.s3.aws_secret_access_key=XXXXXXXXXX

or on a per bucket basis:

config set endpoint.s3.my-private-bucket.aws_access_key_id=XXXXXXXXXX
config set endpoint.s3.my-private-bucket.aws_secret_access_key=XXXXXXXXXX

If aws_access_key_id and aws_secret_access_key are not set in your CommandBox settings, the S3 endpoint checks for credentials in the same places and order as the AWS CLI and SDKs:

It checks for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables containing the credentials.

It checks for an AWS credentials ini file. (If you use the AWS CLI, this file is created by the CLI when you enter your credentials during setup. The default location for this file is at~/.aws/credentials.)

Info The location of the credentials ini file can be overwritten by setting anAWS_SHARED_CREDENTIALS_FILE environment variable to an alternate file path (this can also be set in your CommandBox settings:endpoint.s3.aws_shared_credentials_file). Further, the AWS credentials file has the concept of "profiles", where the default profile is named "default". The profile to use can be changed from "default" by setting an alternate profile name in anAWS_PROFILE environment variable or CommandBox endpoint setting (endpoint.s3.aws_profile).

Finally the S3 endpoint will check for the presence of an IAM role from which credentials can be obtained. This credential location is only valid on AWS EC2 instances.

The full list of possible credential locations and the order in which they are checked is as follows:

• Per bucket credentials in your CommandBox endpoint settings

• Global credentials in your CommandBox endpoint settings

• Environment variables

• AWS credentials file

• IAM role

CommandBox can install UDFs from the popular site CFLib.org. Each project on CFLib is a single CFML function. You can find UDFs via the web site and copy the URL slug for a given UDF to use in your installation.

For example, if the URL to a given UDF is http://www.cflib.org/udf/CalculateWindChill, the slug you'll want to use would be CalculateWindChill.

Standard Installation

To install a package from CFLib, use the slug from the website's URL like so:

install cflib:AreaParallelogram

This will create a folder in your installation directory named after the UDF containing a .cfm file of the same name. The above command would create the following folder:

AreaParallelogram/AreaParallelogram.cfm

That file contains a single function that you can call. It is up to you to include that file where ever you want to use the UDF.

include '/AreaParallelogram/AreaParallelogram.cfm';
var area = AreaParallelogram( base, height );

ColdBox Installation

If you're using ColBox, you can use a slightly different version of the CFLib endpoint called CFLib-ColdBox which will wrap up the UDF inside a CFC and place it in an ad-hoc module which automatically registers the model with WireBox.

install cflib-coldbox:AreaParallelogram

This frees you up from needing to manually include the file. Once you install the module, you can immediately ask WireBox for the UDF using the convention UDFName@cflib. WireBox will register this mapping by convention so there is no additional setup required to use the UDF.

var area = getInstance( `AreaParallelogram@cflib` ).AreaParallelogram( base, height );

Or inject the wrapped UDF to use in your handlers or models.

component {
    // Inject the UDF wrapped in a CFC
    property name='areaHelper' inject='AreaParallelogram@cflib';

    function onDIComplete() {
        var area = areaHelper.AreaParallelogram( base, height );
    }
}

Package Metadata

Packages installed from the CFLib endpoint don't have any way to get new version information. They will always show as outdated using the outdated or update commands and their downloads will not get stored in the artifact cache.

In box.json

You can specify packages from the CFLib endpoint as dependencies in your box.json in this format.

{
    "dependencies" : {
        "AreaParallelogram" : "cflib:AreaParallelogram"
        "FahrenheitToCelsius" : "cflib-coldbox:FahrenheitToCelsius"
    }
}

Entire Git repos that represent a package can be installed via the Git endpoint. This can be a public Git server like GitHub or Bitbucket, or a private Git repo behind your firewall.

Make sure the root of your Git repo has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the repo will be used as the package name.

Installation

To install a package from a Git repo, use the URL like so:

install git://github.com/username/repoName.git
install git+https://github.com/username/repoName.git
install git+ssh://git@github.com:username/repoName.git

You can target a specific branch, tag, or commit by adding a "commit-ish" to the end of the URL.

install git://site.com/user/repo.git#development
install git://site.com/user/repo.git#v1.2.3
install git://site.com/user/repo.git#09d302b4fffa0b988d1edd8ea747dc0c0f2883ea

GitHub shortcut

If the repo you wish to install is located on Github.com, you can use this shortcut to specifying the package.

install username/repoName

In box.json

You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

{
    "dependencies" : {
        "myPackage" : "git://github.com/username/repoName.git"
    }
}

Authentication

Git repos that allow anonymous pulls do not require any additional configuration for authentication. CommandBox's Git endpoint supports SSH authentication via public/private keys by using the git+ssh:// protocol.

install git+ssh://site.com:user/repo.git#v1.2.3

Some Git endpoints (like private Github repos) need a user before the site name in the url string like below:

install git+ssh://git@github.com:user/repo.git

Info Note the git+ssh URL is a little different than a HTTP(S) URL. There is a colon (:) after the host instead of a forward slash (/).

The git+ssh endpoint will look for a private SSH key in your ~/.ssh directory named id_rsa, id_dsa, or identity. If you are using a multi-key setup with a ~/.ssh/config file, it will be read, and the appropriate key will be used for the host. The matching public key needs to be registered in the Git server.

Info If you are deploying to a server and you have not previously logged into the Git server from the new machine you will need to make sure the Git server is added to your known_hosts file. The quickest way to do this is to use git clone git@github.com/user/repo.git from the terminal OR add the line from your local machine to the server.

Password authentication is not supported yet for HTTP, HTTPS, or SSH Git protocols.

CommandBox can install projects from the popular site RIAForge.org. You can find projects via the web site and copy the URL slug for a given project to use in your installation.

For example, if the URL to a given project is http://javaloader.riaforge.org/, the slug you'll want to use would be javaloader.

Installation

To install a project from RIAForge, use the slug from the website's URL like so:

This will create a folder in your installation directory named after the project containing all the files in the zip.

Info Note this endpoint will only work for RIAForge projects who's download URL points to a zip file.

Package Metadata

Packages installed from the RIAForge endpoint don't have any way to get new version information. They will always show as outdated using the outdated or update commands and their downloads will not get stored in the artifact cache.

If the package has a box.json, its version information will be used, and any dependencies will be installed as well.

In box.json

You can specify packages from the CFLib endpoint as dependencies in your box.json in this format.

CommandBox can install a Github Gist from as a package.

Make sure the root of your Git repo has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the Gist ID will be used as the package name.

Installation

To install a package from a Github Gist, you must pass the Gist ID from gist.github.com:

The Github username is optional.

You can target a specific commit by adding a "commit-ish" after the Gist ID.

In box.json

You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

If you have external jars that need downloaded into your project, you can use the jar: endpoint to download them. The jar endpoint does not expect the jars to be contained in a zip file or to have a box.json. As such, there is no real package slug or name, so CommandBox will "guess" the name based on the name of the jar (if a jar name appears in the path or query string).

Installation path

Files from the jar: endpoint will be placed in a lib/ folder by default unless you provide another folder for installation.

In box.json

You can specify jars as dependencies in your box.json in this format.

Note this installation method does not include any dependencies of the jar like a Maven installation would. That will be a future endpoint.

For CommandBox to be able to install packages for you it needs to connect to package registry where packages are stored so it can download them for installation. CommandBox integrates seamlessly with ForgeBox, our community of ColdFusion (CFML) projects. CommandBox also integrates with HTTP(S), local file/folder, and Git endpoints.

Supported Endpoints

Here is a list of the package endpoints currently supported by CommandBox.

• ForgeBox - Cloud-based packages

• HTTP(S) - Point to a hosted zip file containing a package

• File - A local file containing a package

• Folder - A local folder containing a package

• Git - Any Git repo containing a package

• Java - Install OpenJDK for your servers

• Jar - A jar file hosted via HTTP that's not contained in a zip file

• S3 - A package zip stored in a private S3 bucket

• CFLib - UDFs posted on CFLib.org

• RIAForge - Projects posted to RIAForge.org

• Gist - A package hosted as a Gist from gist.github.com

Examples