If you do not already have an FORGEBOX account, you can create an account in order to publish and collaborate on packages on the public registry.

Creating an account on the website

2. In the user signup form, type in the fields:

   • Username: The username that will be displayed when you publish packages or interact with other users on forgebox.io.

   • Email address: Your email will be used to confirm your account and to send notifications about your account. Invites to collaborate on a package, invites to join an organization, a team etc.

   • Password: Your password must be at least 8 characters long

4. Confirm the captcha

6. Click Create Account.

Creating an account via CommandBox (CLI)

1. In your terminal open CommandBox by typing box

2. Type forgebox register and enter the required information to complete the registration

Note: After signing up for a ForgeBox account, you will receive an account verification email. You must verify your email address in order to publish packages to the registry.

Bug

Improvement

New Feature

Version 7.0

This major update has a bunch of performance updates, and more activity logs to keep track of all the actions you perform via CommandBox and the ForgeBox UI. We have made a big change to our search engine and introduced Elastic Search as the default search engine which provides better and more accurate results when searching on the site or using our search endpoint.

Version 6.0

Bug

Improvement

New Feature

CommandBox functions as a package manager which means you can use it to locate and install code packages for you. This gives you a consistent and scriptable method to install the libraries you need in a simple manner.

install myPackage

By default, the list of available packages is on ForgeBox, our CFML code sharing site. Additional endpoints such as Git, HTTP/HTTPS, and local file/folder are also available. When a package is installed, all of its dependencies are automatically installed for you for quick, easy experience.

You can easily create your own packages and register them on FORGEBOX so the whole community can start using them.

There are two ways to manage your packages on FORGEBOX.

It's up to you to choose the way you interact with your packages or you can even use them both if desired.

Bug

Improvement

New Feature

Task

There are several factors that determine where a package gets installed to. Here are the ways CommandBox determines the install location in order of importance.

1. The value of the directory parameter passed into the install command by the user.

2. The value of the installPaths.packageName property set in the project's main box.json by the user. Where packageName is the name of the package you are installing like logbox.

3. The value of the directory property in the package's box.json by the package author. Note, this must be a path relative to the current working directory (CWD).

4. Based on the package type convention if the package is a command, coldbox module, commandbox module, plugin, or interceptor.

5. If the package being installed 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.

6. The current working directory (CWD)

Once the installation directory is determined, a folder is created that matches the package's slug which is where the package is finally copied to. If the package's createPackageDirectory property is set to false in the box.json, the package will be copied to the root of the installation directory. An example of this would be a complete application that needs to go in the web root.

The install command is used to tell CommandBox what you want. Here we ask for the stable release of the ColdBox MVC Platform. "coldbox" is the name of the ForgeBox slug.

install coldbox

Packages should always have a box.json descriptor file inside them. This is especially true of packages installed from endpoints other than Forgebox since they don't have any other metadata available. CommandBox will install any zip file even if it doesn't have a box.json, but this isn't ideal since the name, version, and type of the package must be guessed in that instance.

If you find a package on the internet that doesn't have a box.json, please contact the maintainer and request that they add one or submit a pull request!

ForgeBox Semantic Versioning Support

ForgeBox supports semantic version ranges for installing packages. Here are some examples:

# Latest stable version
CommandBox> install foo

# Same as above
CommandBox> install foo@stable

# latest version, even if pre release (bleeding edge)
CommandBox> install foo@be

# A specific version
CommandBox> install foo@1.2.3

# Any version with a major number of 4 (4.1, 4.2, 4.9, etc)
CommandBox> install foo@4.x

# Any version greater than 1.5.0
CommandBox> install foo@>1.5.0

# Any version greater than 5.2 but less than or equal to 6.3.4
CommandBox> install "foo@>5.2 <=6.3.4"

# Any version greater than or equal to 1.2 but less than or equal to 3.2
CommandBox> install "foo@1.2 - 3.2"

# Allows patch-level changes if a minor version is specified. Allows minor-level changes if not.  (2.1.2, 2.1.3, 2.1.4, etc)
CommandBox> install foo@~2.1

# Any greater version that does not modify the left-most non-zero digit.  4.2, 4.3, 4.9, etc
CommandBox> install foo@^4.1.4

Install Process

When you install a package, here are the steps that are taken. Most all of this should be evident by the output streamed to the console during the install process. To get even more juicy details, use the --verbose flag while installing.

1. CommandBox inspects the ID passed to the install command to determine the endpoint to use.

2. The matching endpoint is asked to fetch the package represented by the ID.

3. For example, the ForgeBox endpoint checks the local artifact cache and possibly downloads the package.

4. If FORGEBOX is offline, the best match package will be looked for in your artifacts.

5. The package is unzipped and its box.json is read

6. Installation directory is finalized

7. Contents of package are copied based on the ignore and --production flag

8. The package is saved as a dependency in the root box.json

9. The package's dependencies are installed

Saving dependencies

By default, any package you install will be saved as a dependency. To save it as a development dependency instead, use the --saveDev flag.

install testbox --saveDev

If you DON'T want the package you're installing to be saved as a dependency pass save=false or negate the save flag as --!save.

install cborm --!save

Production Installation

When you install a package, all dependencies will be installed. If you want to skip development dependencies, use the --production flag. This will also cause CommandBox to obey the package's ignore property in its box.json.

install cbvalidation --production

Verbose Installation

If you're a glutton for information, or perhaps you just want to debug what's going on, set the --verbose flag to get extra debugging information out of the install command including a list of every file that's installed.

install cbi18n --verbose

Forced Installation

If CommandBox sees the directory that it was going to install into already exists with a newer or equal version of the package inside, it will decline to install again since it would be overwriting what's already there. If you want to install anyway, use the --force flag.

install cbsoap --force

Advanced Installation

In the CFML world, there are no global conventions for where to install things to nor where to store dependencies. Therefore, CommandBox for the most part will just stick packages in the root of your site unless you tell it otherwise. It may not be pretty, but it's as good as stock CFML apps can get. That means a lot of the cool things other package managers like NPM can do simply won't be available to you.

If you're using the ColdBox MVC Platform, congratulation! You just unlocked advanced mode! ColdBox uses conventions that tells you where to put stuff, and most importantly it has modularity as a first class citizen. Not only that, but modules can be nested infinitely to nicely encapsulate dependencies and WireBox will automatically find and register each module's models for your application to use.

Module Conventions

Modules are basically smart packages and when CommandBox installs or uninstalls modules it will behave a bit differently to take advantage of the functionality only available to the CFML world via the ColdBox Platform.

When installing a module, it will be placed in the modules/ directory. That means the cbvalidation module will install here:

<webroot>/modules/cbvalidation

The cbvalidation module has dependencies of its own but it is an island unto itself and will encapsulate these. Therefore the cbi18n module will be installed in a modules/ folder inside cbvalidation.

<webroot>/modules/cbvalidation/modules/cbi18n

You'll be able to see a nice representation of this when you use the list command.

CommandBox> list
Dependency Hierarchy myApp (1.0.0)
├── coldbox (4.2.0)
└─┬ cbvalidation (1.0.0)
  └── cbi18n (1.0.0)

Moduleplicity

What this opens the door for is more than one module to depend on different versions of the same second module. Both can be installed and nested under the respective parent. In the near future, WireBox will be smart enough to present these nested modules only to their parents so they are fully encapsulated.

The idea is that a module can "see" and use another module installed at the same level or higher in the hierarchy, but not lower. That makes dependencies a bit of a black box to their parents. This also allows us to bypass some redundancy. For instance, when installing a module, if a satisfying version of that module already exists at a higher level, we skip the installation. Consider this example:

install cbi18n
install cbvalidation

We know that cbvaliation requires cbi18n, but since it is already installed in the root modules folder, we won't install it again under cbvalidation.

Smart Uninstall

The last way modules are better than sliced papusas is in how they uninstall. We talked about how non-modules install-- just littered in the web root in a jumble of dependencies. When uninstalling a non-module package, CommandBox will recursively go through the dependencies and remove them as well. However, when uninstalling a module, that module's folder is simply deleted and that's it. Since all dependencies are contained in the "black box", there's no need to go hunting for them.

Packages are quite simply a folder that contains some code and a box.json file. A package can be a simple CFC, a self-contained library, or even an entire application. ColdBox and ContentBox modules also make great "smart" packages.

Remember, packages aren't just the things you install into your application, but your application is a package too! That's why when you install something in your app, we'll create a /box.json if it doesn't exist to start tracking your dependencies.

Your box.json file describes your package, dependencies, and how to install it. To turn a boring folder into a sweet package just run the init command in the root of the folder.

init name="My Package" version="1.0.0"

Distribution

When making a package available on ForgeBox, each version of that package has its own location. Most download locations point to a zip file, that when extracted, contains a folder with a box.json in it. The box.json designates the root of the package. However, the location property of your box.json can be any valid endpoint ID. An example would be:

{
  "name":"my project",
  "slug":"my-project",
  "version":"1.0.0",
  "location":"githubUser/repoName#v1.0.0"
}

In that case, the location for version 1.0.0 of this package is the v1.0.0 tag in that GitHub repository.

Storing Package Binaries on ForgeBox

ForgeBox can store the binaries for your packages in the ForgeBox Cloud. This provides you with an easy way to store multiple versions of your package distributed across the globe.

To utilize ForgeBox Storage, simply set forgeboxStorage as the value of your package's location.

package set location=forgeboxStorage

When you publish a package, CommandBox will automatically zip up your package and send it to ForgeBox.

Publishing to ForgeBox from start to finish

Below is an example of the commands that would take you from scratch to a published package:

# Create user (first time only)
forgebox register username password your@email.com firstName lastName
forgebox login username password

# Create package
mkdir mypackage --cd
package init slug=my-package type=modules
bump --major

# Publish it
publish

# Viewable and installable by the world!
forgebox show my-package
install my-package

Private Packages

FORGEBOX supports private packages. Private packages are only visible to the user who created it. To create a private package, pass the private flag to the package init command.

CommandBox:my-package> package init slug=my-package --private
- Set name = My Package
- Set slug = my-package@username
- Set version = 0.0.0
- Set private = true
- Set shortDescription = A sweet package
- Set ignore = ["**/.*","test","tests"]
Package Initialized & Created /Users/username/code/sandbox/my-package/box.json

CommandBox does more than help you install packages. It also helps you keep them up to date as well. Remember, you can always get a quick list of all the dependencies installed on your app with the list command.

Getting the Latest

To check and see if any of your installed packages can be updated to a newer version, run the update command.

Entering "yes" will install the newest version of the package. Use the --force flag to automatically answer "yes". It is also possible to get a list of outdated dependencies without the prompt to update them with the outdated command.

The table of information in the outdated and update command has several different version numbers. This is what they mean:

• Package - This contains the slug and semver range you've put in your box.json file. i.e., what version you "asked" for.

• Installed - This is the exact version installed right now in your project

• Update - This is the newest possible version of the package that satisfies the semver range in your box.json. Not there may be newer versions of the library not shown here depending on what your semver range is allowing. A red highlight in this columns means a new version is available.

• Latest - This is the absolute latest stable version of this package regardless of your semver range. In order to update to this version, you may need to run the install command again and ask specifically for it. An orange highlight in this column means a new major update is available.

FORGEBOX Semantic Versioning Support

If you are using a ForgeBox package, the update command will comply with the semantic versioning range you specify. For example, if you have a dependency installed with a version saved of ^2.0.0 it will update you all the way to 2.9.9 but it will never install 3.0.0 until you ask it to. This is because breaking changes come in major versions, but minor releases are supposed to be compatible.

Determining Freshness

The way CommandBox determines whether there is a new version of a package differs based on the endpoint that installed the package. Versions are always treated as a semantic version (Major.Minor.Patch).

• ForgeBox - The ForgeBox REST API is used to get the latest package version.

• HTTP(S) - Package is always considered outdated, and re-downloaded.

• File - The box.json's version is used from the zip. If box.json doesn't exist, the package is always considered outdated.

• Folder - The box.json's version is used from the folder. If box.json doesn't exist, the package is always considered outdated.

• Git - Package is always considered outdated, and re-cloned.

External JSON Integration

If you want to integrate your package updates with an external process, you can get this data back as JSON so it can be parsed and used by another system.

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 are 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 trouble 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

As a registered user, you will be able to access the package manager and you will be able to create, update and delete packages and its package versions.

Publishing private packages to ForgeBox

To create a private package, set the private property to true in your box.json prior to publishing.

package init
package set private=true
package set slug=my-slug@forgeBoxUser
etc...
publish

Installing private packages from ForgeBox

Replace forgeBoxUser with your actual ForgeBox username. When you install the package, you'll need to use the full slug like so:

install my-slug@forgeBoxUser

You can install specific versions or version ranges as you would expect:

install my-slug@forgeBoxUser@1.0.0
install my-slug@forgeBoxUser@be

Keep in mind that the private packages are a paid feature, however, we are giving one private package with the community plan for free for you to explore and play with it.

FORGEBOX is and will be FREE forever, however, there are some editions if you want to have additional features, manage your organization and teams or even host your own instance of FORGEBOX so you can have the exclusivity and security with all the benefits of the community version.

Free Account

Pro Account

Business Account

Enterprise

The free edition of FORGEBOX allows you to browse packages, install packages and publish public packages to the registry, and that way you help grow the ColdFusion (CFML) community.

The pro account is directed to the software professional or small business in need of many packages and collaborations.

This is a subscription-based plan, in order to subscribe you can go to Plan & Billing under Settings on the user sidebar.

With your free account, you will get the following features.

• Unlimited public packages

  • Publish as many packages as you want, with no limit on public packages. The CFML community will appreciate this.

• Unlimited collaborators on public packages

  • On FORGEBOX you can collaborate on other users' packages and invite other users' to collaborate on your own packages.

• 1 private package

  • You will be able to create one private package for FREE so you can get to know the private package capabilities.

• 10GB of storage for your packages

  • Up to 10GB of storage for you to store packages in the FORGEBOX cloud.

• 7 days of activity log

  • You will be able to see all kinds of activities such as package updates, collaboration invites, profile updates, etc for up to 7 days.

• Community support

  • Get to know the FORGEBOX community and get support from them.

• Collaborators public community support

  • Collaborators can be another important resource when requiring support.

With your pro account you will get the following features.

• Unlimited private packages

  • Publish as many packages as you want, no restrictions here. The CFML community will appreciate this.

• 10 collaborators on private packages

  • Get unlimited collaborators on public packages and up to 10 collaborators on private packages.

• Private package based permissions

  • You can have read access only or read/publish access on private packages

• 90 days of activity log

  • You will be able to see all kinds of activities such as package updates, collaboration invites, profile updates, account changes, system actions etc for up to 90 days.

• 50GB of storage for all packages

  • Up to 50GB of storage for you to store your public and private packages in the FORGEBOX cloud.

• Basic support (Email + Slack)

  • Get access to the boxteam slack channel where you get support from the community and the Ortus members. Get basic support via Email.

FORGEBOX Business allows you to create your organization, members and teams to contribute to your organization; have the ability to read, write, and publish public or private scoped/non-scoped packages.

Within the organization exists roles that can be assigned to the organization members according to their duties and permissions.

Super Admin

Controls billing & adding and removing people in the org.

Admin

Manages teams & package access.

Member

Works on packages they are given access to.

CommandsIntegrating CommandBox with your own ForgeBox endpoint is very simple. Please review the available commands and follow our guide to learn how to interact with ForgeBox from the CLI.This is a list of the commands you have available to integrate with ForgeBox enterprise.

• forgebox endpoint list

• forgebox endpoint register

• forgebox endpoint remove

• forgebox endpoint set-default

You can always ask CommandBox for help by adding a question mark at the end of your command. example: forgebox endpoint ?

ForgeBox Enterprise is an offering by Ortus Solutions that allows you to have a custom and private hosted version of ForgeBox for your company to use. You can always use the public ForgeBox version if you want too.

All the goodness of the community version, but with the exclusivity and security of your own instance to collaborate, modernize and conquer!

Capabilities

FORGEBOX ENTERPRISE is a hosted private software registry with exclusive security, collaboration and scalability features. Empower your development teams to build applications rapidly, modern and secure. FORGEBOX ENTERPRISE will enhance development team the following capabilities:

• Private software registry to manage and shared code packages (engines, projects, demos, modules, etc. ) across your organization.

• Public or Private packages

• Internal collaborators and access controls

• Custom named integration with CommandBox CLI.

• Fine grained User Access Control, Roles and Permissions.

• Package type management

• Scalable Artifact Storage

• Up to 250GB of storage included

• SSL Included

• Software firewall included

• Artifact CDN Included

• Enterprise Support, SLAs and mentorship

• Containerized Environment with redundancy and scalability

• Package Security Audits (**Coming Soon)

• Package white and black lists (**Coming Soon)

• Two-factor authentication (**Coming Soon)

• Single Sign On (**Coming Soon)

Every FORGEBOX Enterprise includes up to 250GB of binary storage with elastic capabilities.

Storing Package Binaries on FORGEBOX

ForgeBox can store the binaries for your packages in the ForgeBox Cloud. This provides you with an easy way to store multiple versions of your package distributed across the globe.

To utilize ForgeBox Storage, simply set forgeboxStorage as the value of your package's location.

CommandBox:my-package> package set location=forgeboxStorage

When you publish a package, CommandBox will automatically zip up your package and send it to ForgeBox.

https://www.forgebox.io/api/v1/ is the default endpoint and you can always check your registered endpoints by typing

forgebox endpoint list

In order to register a new endpoint, just give it a name and set your endpoint as follows:

forgebox endpoint register stg-forgebox

https://forgebox.stg.ortushq.com/api/v1/

The next step is to authenticate against your endpoint using valid credentials as is shown below:

forgebox login endpointName=stg-forgebox

If you want to update your endpoint to be the default one, just do it like this:

forgebox endpoint set-default stg-forgebox

This will default your endpoint and you will be able to install packages from your endpoint without giving a namespace.

Once you have registered your endpoint and you are authenticated, you will be able to install packages from your custom endpoint like this:

install stg-forgebox:coldbox

In the previous example you can see we are installing a coldbox package from stg-forgebox which is our custom endpoint instead of the default one.

You can remove endpoints anytime by using the remove command:

forgebox endpoint remove demo-endpoint