Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
To install a package from a local folder, 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.
You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.
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.
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.
You can specify packages from file endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.
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. For example:
The installation ID consists of a series of identifiers separated by underscores that describe the Java version, type, JVM, etc that you want installed.
An example utilizing every option would be
However, everything is optional except the major version. These are also valid installation IDs
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, arm etc...
os - windows, linux, mac, solaris, alpine_linux (openjdk11+ only)
jvm-implementation - hotspot
release - latest, jdk8u172, jdk8u172-b00, etc...
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
When java is installed as a package endpoint, the name of the folder that it 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 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:
If the URL has the zip file name in it, the name without ".zip" is used.
If the URL contains github.com, the repo name will be used.
Otherwise, the entire URL will have non alpha-numeric characters removed and used.
To install a package from a website, use the full URL like so:
You can specify packages from HTTP(S) endpoints as dependencies in your box.json in this format:
If you know a given URL will always return the exact same package, then you can request CommandBox to cache the download in local artifacts to speed up builds. To do so, use an endpoint name of https+cached or http+cached in your install ID.
Or
Cached artifacts will be stored under the slug HTTP_Cached and can be viewed like so:
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.
Here is a list of the package endpoints currently supported by CommandBox.
ForgeBox - Cloud-based packages (Read more)
HTTP(S) - Point to a hosted zip file containing a package (Read more)
File - A local file containing a package (Read more)
Folder - A local folder containing a package (Read more)
Git - Any Git repo containing a package (Read more)
Java - Install OpenJDK for your servers (Read more)
Jar - A jar file hosted via HTTP that's not contained in a zip file (Read more)
Lex- A Lucee Extension hosted via HTTP that's not contained in a zip file (Read more)
S3 - A package zip stored in a private S3 bucket (Read more)
CFLib - UDFs posted on CFLib.org (Read more)
Gist - A package hosted as a Gist from gist.github.com (Read more)
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).
Files from the jar: endpoint will be placed in a lib/ folder by default unless you provide another folder for installation.
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.
The jar endpoint will make the following assumptions about what version of a jar a particular URL may point to:
It tries and parse a semantic version from the URL's path
It will store that version in the package's box.json (0.0.0 if not found)
It will use that version when checking for updates to the jar
This will be reflected in what you see in the package list and outdated commands.
So for example, if you install a jar dependency like so:
CommandBox will parse out the 1.24.0 from the path of the URL and will assume that as the version of the package. When checking for outdated dependencies, that version will be used to compare to the current URL in your box.json which means an unchanged URL will know it is not out of date.
Packages hosted in private S3 buckets can be installed directly from S3 URLs.
To install a package from a S3 bucket, use a URL like so:
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:
Info If your S3 path does not end in
.zipthe 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.zipwill 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.zipextension:s3://my-private-bucket/myPackage.
You can specify packages from S3 endpoints as dependencies in your box.json in this format:
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:
or on a per bucket basis:
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 an
AWS_SHARED_CREDENTIALS_FILEenvironment 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_PROFILEenvironment 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
ForgeBox is an online registry of packages run by Ortus Solutions. The web UI for ForgeBox is located at . 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.
Every package on ForgeBox has a unique slug. To install a package, use the slug like so:
You can also specify the version of a package you want to install from Forgebox.
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.
You can specify packages from ForgeBox as dependencies in your box.json in this format:
info The caret
^means that theupdatecommand will update minor releases but not major releases.
If the package being installed from ForgeBox is of type lucee-extensions and if the current working directory is found to have a Lucee server in it, the lex file will instead be installed to the server context's deploy folder. Note the Lucee server will need to have been started at least once so CommandBox "knows" about it, but it need not be running at the time.
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.
Inside CommandBox, use the forgebox namespace to search for packages or show packages of your choosing.
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:
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.
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:
Too many results on one page? Use the built-in pagination options:
Or just pipe the output into the built-in "more" or "grep" command.
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.
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.
Lucee Extensions
If you have external Lucee Extensions that need downloaded into your Lucee Server, you can use the lex: endpoint to download them. The lex endpoint does not expect the download 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 lex based on the URL.
The Lex endpoint can also be used to install local lex files.
Please note that if a Lucee extension is already hosted on ForgeBox, you do not need the Lex extension, as you can simply use the ForgeBox slug just like you would any other page and get the same result but with the addition of semantic versioning.
Files from the lex: endpoint will be placed in a folder named the same as the package by default unless you provide another folder for installation. If the current working directory is found to have a Lucee server in it, the lex file will instead be installed to the server context's deploy folder. Note the Lucee server will need to have been started at least once so CommandBox "knows" about it, but it need not be running at the time.
You can specify a lex as dependencies in your box.json in this format.
This means you can run a box install on a fresh project to pull down extensions needed for your app to run.
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.
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.
You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.
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.
To install a package from CFLib, use the slug from the website's URL like so:
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:
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.
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.
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.
Or inject the wrapped UDF to use in your handlers or models.
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.
You can specify packages from the CFLib endpoint as dependencies in your box.json in this format.
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.
To install a package from a Git repo, use the URL like so:
You can target a specific branch, tag, or commit by adding a "commit-ish" to the end of the URL.
If you don't specify a commit-ish, the Girt endpoint will assume you want the master branch. If there is no master branch, we will attempt to checkout the main branch.
If the repo you wish to install is located on Github.com, you can use this shortcut to specifying the package.
You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.
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.
Some Git endpoints (like private Github repos) need a user before the site name in the url string like below:
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_hostsfile. The quickest way to do this is to usegit clone git@github.com/user/repo.gitfrom the terminal OR add the line from your local machine to the server.
If you receive an invalid private key exception (Error cloning git+ssh repository and com.jcraft.jsch.JSchException: Auth fail), check your version of SSH. OpenSSH (7.8 and newer) generates keys in the new OpenSSH format, which starts with -----BEGIN OPENSSH PRIVATE KEY-----. JGit does not support this key format. Generate your key in the classic format using the following:
You can authenticate to a Git repo over HTTP using a username/password combination or a personal access token. The format looks like this:
Github personal access tokens can be specified as either
or just the personal access token like
and they both appear to work the same. It appears that a private Github repo requires the “repo” scope selected for the personal access token.
GitLab seems to want a username, but it doesn’t seem to matter what the username is.
You can use environment variables from the CLI or in your box.json to protect sensitive information like passwords and keys.
We also support the NetRC file format. Just create a files in your user's home directory called ~/.netrc or ~/_netrc with the following format:
CommandBox will find this file, match the hostname to the Git repo being cloned, and use the username and password as specified.
We do not support any of these username/password options over HTTP as it just seems unwise. Please use HTTPS.
Some users of Circle-CI have reported the following error when trying to clone a Git repo over HTTPS.
It is changing the https github url to ssh in the call. You can remove the config setting like so: