Installing BBjShip 26.03
BBjShip runs inside BBjServices, so it's always installed on the machine that runs BBjServices. Once it's installed and its deployment endpoint is enabled, your builds deploy to it through the address /webforj-bbjship on the BBjServices web server, either from that same machine or from another one.
How you install BBjShip depends on where BBjServices runs:
| Where BBjServices runs | Who installs BBjShip | How |
|---|---|---|
| Your own machine | The webforJ build plugin | Automatically with mvn, or once with mvn webforj:bbj-setup |
| A shared or production server | An administrator of that server | The BBj Plugin Manager, then bbjship remote enable |
In both cases, install the BBjShip version that matches the webforJ version of your apps. Deploys fail when the two differ.
On your own machine
When BBj runs on the same machine as your build, you don't install BBjShip yourself. The first development run of a project configured for BBjShip installs it and enables its deployment endpoint:
mvn
Through the Maven plugin
To deploy with mvn install before you start any development run, install BBjShip once from the folder of your project:
mvn webforj:bbj-setup
The goal installs the BBjShip version that matches the webforj-maven-plugin and enables the deployment endpoint on the port of your deployment URL. It needs:
- BBjServices running and answering on the port of the deployment URL
- A deployment URL that names your machine, for example
http://localhost:8888/webforj-bbjship - The BBj administrator user name and password, from
<admin>or thewebforj.bbj.admin.*properties. Without them, the goal uses the factory accountadminwithadmin123and prints a warning. - The BBj installation folder, from
<home>,webforj.bbj.homeorBBJ_HOME. Without them, the goal detects it.
After a webforJ upgrade, replace the installed BBjShip with the new version:
mvn webforj:bbj-setup -Dwebforj.bbj.force=true
Your deployed apps stay deployed when you run the goal again.
On Windows, a replacement can fail while BBjServices holds the files of the installed BBjShip open. Restart BBjServices and run the goal again, see Troubleshooting.
On a server
On a shared or production BBj server, an administrator installs BBjShip once on that server. Developers and CI pipelines then deploy to it from their own machines over HTTPS.
- Install BBjShip with the BBj Plugin Manager.
- Enable the deployment endpoint with the HTTPS port of the BBjServices web server.
- Create an authorization token in Enterprise Manager for the builds that deploy, see Deploying from another machine.
Through the BBj Plugin Manager
In the BBj Plugin Manager, install BBjShip from the webforj-bbjship repository of the BBj-Plugins organization. A tag installs a webforJ release, and master installs the development snapshot. Update it later on the Installed tab.
Enabling the deployment endpoint
The deployment endpoint is the address builds deploy to. Enable it on the server with your BBj administrator account and the ports the BBjServices web server listens on. --password takes the password as a value, which other users of the machine see in the process list while the command runs. On macOS and Linux, --password-stdin reads it from standard input, and WEBFORJ_BBJ_PASSWORD keeps it out of the command line on every system:
$ <BBj home>/plugins/webforj-bbjship/bbjship remote enable --username admin --password <value> --port 8888 --ssl-port 8443
Enabled http://localhost:8888/webforj-bbjship
Enabled https://localhost:8443/webforj-bbjship
Without --port, the endpoint uses port 8888. Without --ssl-port, it has no HTTPS address. BBjServices must be running. See Command line for every command.
On Windows, run bbjship.cmd and pass the password with --password or WEBFORJ_BBJ_PASSWORD. --password-stdin isn't available there and ends with exit code 2.
Uninstalling
Run bbjship reset first. It undeploys every app and removes everything BBjShip set up in Enterprise Manager. Then uninstall BBjShip in the BBj Plugin Manager.
bbjship reset can't be undone. Back up <BBj home>/cfg/BBj.properties and keep the deployment archive of every app first, see Reset.