run

boxfuse:run

Runs one or more Instances of this Image in the specified environment (on your machine or on AWS).

All necessary resources (Elastic IPs, ELBs, Security Groups, Auto-Scaling Groups, Databases, ...) will be provisioned automatically if they don't already exist. Already running applications will be updated with zero-downtime blue/green deployments.

Usage: mvn boxfuse:run -Dboxfuse.image=image -Dboxfuse.env=environment

> mvn boxfuse:run -Dboxfuse.image=hello:1.0

Launching Instance of axelfontaine/hello:1.0 on VirtualBox ...
Forwarding http port localhost:8888 -> vb-ec717c5e:80
Instance launched in 00:04.006s -> vb-ec717c5e
Waiting for Payload to start on Instance vb-ec717c5e ...
Payload started in 00:08.786s -> https://127.0.0.1:8888

Note: When an image isn't specified, CloudCaptain will automatically search for a compatible payload to fuse within the current directory. If the command is executed at the root of a Maven project, CloudCaptain will also automatically look for the project's build artifact.

Properties

Plugin Parameter Maven/System property Default Description
user boxfuse.user Required - Your CloudCaptain Client user. Also configurable via the BOXFUSE_USER environment variable or the Maven settings.xml
secret boxfuse.secret Required - Your CloudCaptain Client secret. Also configurable via the BOXFUSE_SECRET environment variable or the Maven settings.xml
serverid boxfuse.serverid boxfuse The id of the server in the Maven settings.xml file to load the credentials from.

This is an alternative to passing the credentials in directly through properties.
capacity boxfuse.capacity

AWS only

The capacity to scale an app to in a certain environment

Valid formats:

5:t2.small ensure there are always 5 t2.small instances running
2-10:c4.large:cpu30-70 auto-scale between 2 (min) and 10 (max) c4.large instances based upon average CPU load over the last 300 seconds scale in at 30% and below, scale out at 70% and above
2-10:c4.large:cpu30-70:60 auto-scale between 2 (min) and 10 (max) c4.large instances based upon average CPU load over the last 60 seconds scale in at 30% and below, scale out at 70% and above
2-10:c4.large:netin1024-8300 auto-scale between 2 (min) and 10 (max) c4.large instances based upon incoming network traffic per instance over the last 300 seconds scale in at 1024 KB and below, scale out at 8300 KB and above
2-10:c4.large:netin1024-8300:60 auto-scale between 2 (min) and 10 (max) c4.large instances based upon incoming network traffic per instance over the last 60 seconds scale in at 1024 KB and below, scale out at 8300 KB and above
2-10:c4.large:netout1024-8300 auto-scale between 2 (min) and 10 (max) c4.large instances based upon outgoing network traffic per instance over the last 300 seconds scale in at 1024 KB and below, scale out at 8300 KB and above
2-10:c4.large:netout1024-8300:60 auto-scale between 2 (min) and 10 (max) c4.large instances based upon outgoing network traffic per instance over the last 60 seconds scale in at 1024 KB and below, scale out at 8300 KB and above
cmd boxfuse.cmd first executable file in image

Generic Linux x64 apps only

When fusing new images only

The command to start the app including relative path and all necessary arguments
cpus boxfuse.cpus same as host

VirtualBox only

The number of CPUs to assign to an Instance
debug boxfuse.debug false Start the Payload in debug mode when an Instance launches
debug.wait boxfuse.debug.wait false

JVM apps only

Whether the JVM should wait for the remote debugger to connect (Only applicable when debug mode is active)
domain boxfuse.domain auto

AWS only

The custom domain to use for this application in the specified environment. auto to let CloudCaptain automatically create a new boxfuse.io subdomain for you.
elasticip boxfuse.elasticip auto

single-instance apps on AWS only

The AWS Elastic IP to use when deploying this application in the specified environment. auto to let CloudCaptain automatically create a new Elastic IP for you.
elb boxfuse.elb auto

load-balanced apps on AWS only

The name of the AWS ELB to use when deploying this application in the specified environment. auto to let CloudCaptain automatically create a new ELB for you.
env boxfuse.env dev Use the AWS test or prod environments instead of the local dev one
envvars boxfuse.envvars.NAME Passes this environment variable into the Instance
Example: boxfuse.envvars.JDBC_URL=jdbc:mydburl
healthcheck boxfuse.healthcheck true

single-instance and load-balanced apps only.
Always true for load-balanced-https apps.

Check whether to payload started correctly
healthcheck.port boxfuse.healthcheck.port autodetected The name of the port to check whether the payload started correctly (must be an https or http port, not tcp or udp). Example: admin-https
healthcheck.path boxfuse.healthcheck.path / The path to check whether to payload started correctly
healthcheck.timeout boxfuse.healthcheck.timeout 300 The number of seconds to wait for the Payload to come up
image boxfuse.image autodetected

Run this specific image.

When run as part of fusing a new image, this overrides the app name and version to assign to a new image. By default this is autodetected based on the payload name. For example myapp-1.2.jar would trigger the creation of the image myapp:1.2. You can override this by explicitly setting this property to say my-other-app:333.
instanceprofile boxfuse.instanceprofile none

AWS only

The ARN of the AWS instance profile to use in the specified environment. This is only for apps using the AWS API. The value none unsets any instance profile.
jvm.args boxfuse.jvm.args

JVM apps only

Extra arguments to pass to the JVM
jvm.jmx boxfuse.jvm.jmx false

JVM apps only

Enable the JMX remote management and profiling interface for the JVM
jvm.main.class boxfuse.jvm.main.class autodetected

JVM apps only

Main class to invoke on JVM startup
jvm.main.args boxfuse.jvm.main.args

JVM apps only

Arguments to pass to the main class
linux.args boxfuse.linux.args quiet

When fusing new images only

Experts only

The arguments to pass from the bootloader to the Linux kernel
live boxfuse.live false

When fusing new images only

Enable live reloading of changes in dev for super fast round-trips. Note that images with live reloading cannot be pushed to the CloudCaptain Vault.
logs.auto boxfuse.logs.auto true Whether to automatically display the instance logs on startup
logs.boot boxfuse.logs.boot true Shows the instance boot logs
logs.dir boxfuse.logs.dir target/boxfuse The directory where the logs should be redirected to
logs.filter boxfuse.logs.filter.FILTER

CloudWatch Logs apps only

The filter to apply when viewing the application logs.

Supported filters:

Name Description Example
instance Only show logs for the instance with this id i-12345678
image Only show logs for instances of this CloudCaptain image myuser/myapp:123
app Only show logs for instances of this CloudCaptain app myuser/myapp
level Only show log events at this log level or higher (possible values: TRACE,DEBUG,INFO,WARN,ERROR) WARN
event Only show logs events with this exact event id USER_CREATED
logger Only show logs events with this exact logger com.myapp.MyClass
thread Only show logs events created on this exact thread main
account Only show logs events in relation to this account in the system my-account
action Only show logs events in relation to a domain-specific element in the system (like an customer order for example) order-12345
user Only show logs events in relation to this user of the account (for systems with the concept of teams or multiple users per account) MyUser
session Only show logs events for the session with this id session-9876543210
request Only show logs events for the request with this id req-111222333
message Only show logs events with this message my-log-message
limit Limit output to first n log messages where 1 <= n <= 10000 2500
start Limit output to log messages created after this date and time.

Supported date formats:

  • 2016-12-08 11:22:44
  • 2016-12-08 11:22
  • 2016-12-08
  • 11:22:44
  • 11:22

The space between date and time can also be replaced by the letter T like in standard ISO dates. Example: 2016-12-08T11:22:44

By appending Z to the time it will be treated as UTC instead of local time. Example: 2016-12-08 11:22:44Z

As an alternative to the absolute date/time you also have the option to pass in the relative number of seconds to the current time. Example: -600 (10 minutes ago)

 2016-12-07 12:34:56
end Limit output to log messages created before this date and time.

Supported date formats:

  • 2016-12-08 11:22:44
  • 2016-12-08 11:22
  • 2016-12-08
  • 11:22:44
  • 11:22

The space between date and time can also be replaced by the letter T like in standard ISO dates. Example: 2016-12-08T11:22:44

By appending Z to the time it will be treated as UTC instead of local time. Example: 2016-12-08 11:22:44Z

As an alternative to the absolute date/time you also have the option to pass in the relative number of seconds to the current time. Example: -600 (10 minutes ago)

 2016-12-08 20:10:00

Wildcards: Wilcard matching is supported by prepending and/or appending an asterisk (*) to the filter value. Examples:

*abc match all ending with abc
abc* match all starting with abc
*abc* match all starting or ending with abc
logs.layout boxfuse.logs.layout timestamp app? image? instance? event? 40:logger? 10:thread? account? action? user? session? request? message?

CloudWatch Logs apps only

The layout to use when displaying the logs.

Format:

  • All fields are separated by a single whitespace and are variable-width by default
  • Appending ? to the field name hides the field if a filter matches it exactly
  • Prepending a number and a column (example: 10:) left trims or left pads the field to that length
  • Appending a number and a column (example: :10) right trims or right pads the field to that length
  • Valid field names: level, timestamp, app, image, instance, event, logger, thread, account, action, user, session, request, message

Example: level:5 image logger?:30 10:thread shows 4 fields:

  • level fixed width of 5, right padded or right trimmed if necessary
  • image variable width
  • logger fixed width of 30, right padded or right trimmed if necessary, hidden if matched exactly in filter
  • thread fixed width of 10, left padded or left trimmed if necessary
logs.tail boxfuse.logs.tail false Tail (keep running with live updates) the logs
newrelic.licensekey boxfuse.newrelic.licensekey

When fusing new images only

Installs and configures the New Relic agents to monitor your instance.
payload boxfuse.payload build artifact

When fusing new images only

The payload to use when fusing an image. This is useful when running the CloudCaptain Maven plugin from the command-line or when multiple artifacts are produced and you want to use an artifact which is not the main one (an artifact using a classifier for example).
platform boxfuse.platform auto

dev environment only

The hypervisor platform to use for the local dev environment.

Choices:

autoautomatically select the best platform for your machine
virtualboxalways use VirtualBox
hypervalways use Hyper-V (Windows 10 Pro only)
ports boxfuse.ports.NAME http=80

Exposes the port of the app with this name using this definition. Example: boxfuse.ports.jmx=8001

Supported formats:

80HTTP port 80, universally accessible
443HTTPS port 443, universally accessible
5555TCP port 5555, universally accessible
5555/httpsHTTPS port 5555, universally accessible
5555/httpHTTP port 5555, universally accessible
5555/tcpTCP port 5555, universally accessible
5555/udpUDP port 5555, universally accessible
5555/tcp:@TCP port 5555 only accessible from your own IP
5555/udp:@/20UDP port 5555 only accessible from the IPs in the CIDR /20 block of your own IP
5555/udp:1.2.3.4UDP port 5555 only accessible from 1.2.3.4
5555/http:1.2.3.4/31HTTP port 5555 only accessible from the IPs in the CIDR /31 block of 1.2.3.4
portsmap boxfuse.portsmap.NAME same as matching image port

VirtualBox only

The local ports to map to the app inside the instance. By default CloudCaptain will attempt to open the same port locally as has been opened in the VirtualBox VM. On Linux & Mac privileged ports (<1024) will be opened at 10000 + the port number for non-root users.
The ports will be mapped by name (ex.: http) to the ports specified by the Image.

Example:

Image port Default local mapped port
http=80 http=80 (Windows & Mac/Linux when CloudCaptain is running as root)
http=10080 (Mac/Linux when CloudCaptain is running as a regular user)
https=8443 https=8443 (All OSes)
udpsrvc=12345/udp udpsrvc=12345/udp (All OSes)
ram boxfuse.ram 1024

VirtualBox only

The amount of RAM in MB to assign to an Instance
securitygroup boxfuse.securitygroup auto

AWS only

The id of the AWS security group to use in the specified environment. auto will auto-create a new security group based on the configured ports.
subnets boxfuse.subnets auto

AWS only

The AWS subnets to deploy to in the specified environment. AWS supports maximum one subnet per availability zone. auto to let AWS automatically select the subnet(s).
tags boxfuse.tags.key

AWS only

The custom tags to apply to AWS resources in addition to the default CloudCaptain ones.
targetgroup boxfuse.targetgroup auto

load-balanced-https apps on AWS only

The name of the AWS Target Group to use when deploying this application in the specified environment. auto to let CloudCaptain automatically create a new ALB and Target Group for you.
tmp boxfuse.tmp 1 The amount of temp space to allocate to /tmp in GB
windows.user boxfuse.windows.user current user

Hyper-V live images only

The Windows user of your machine.
windows.password boxfuse.windows.password

Hyper-V live images only

The Windows password of your machine.

Sample Configuration

<configuration>
    <user>1234567890abcdef1234567890abcdef12345678</user>
    <secret>ABCDEFGHIJKL1234567abcdefghijklmnopqrstu</secret>
    <capacity>3:t2.large</capacity>
    <cmd>-cmd=bin/myapp -with -my args</cmd>
    <cpus>2</cpus>
    <debug>true</debug>
    <debug.wait>false</debug.wait>
    <domain>myapp.mydomain.com</domain>
    <elasticip>1.2.3.4</elasticip>
    <elb>my-elb</elb>
    <env>prod</env>
    <envvars>
        <JDBC_URL>jdbc:mydburl</JDBC_URL>
        <MY_OTHER_VAR>abc</MY_OTHER_VAR>
    </envvars>
    <healthcheck>true</healthcheck>
    <healthcheck.port>https</healthcheck.port>
    <healthcheck.path>/health</healthcheck.path>
    <healthcheck.timeout>120</healthcheck.timeout>
    <instanceprofile>none</instanceprofile>
    <jvm.args>-DmycustomProp=abc</jvm.args>
    <jvm.jmx>true</jvm.jmx>
    <jvm.main.class>com.mycorp.MyApp</jvm.main.class>
    <jvm.main.args>-abc -def</jvm.main.args>
    <image>hello:1.0</image>
    <linux.args>quiet</linux.args>
    <live>true</live>
    <logs.auto>true</logs.auto>
    <logs.boot>true</logs.boot>
    <logs.dir>${project.outputDirectory}/logs</logs.dir>
    <logs.filter>
        <level>WARN</level>
        <account>MyAccount123</account>
    </logs.filter>
    <logs.layout>timestamp app? image? instance? event? 40:logger? account? session? request? message?</logs.layout>
    <logs.tail>true</logs.tail>
    <newrelic.licensekey>0123456789abcdef0123456789abcdef012345</newrelic.licensekey>
    <payload>my-app-1.2.jar</payload>
    <platform>virtualbox</platform>
    <ports>
        <https>443</https>
        <http>80</http>
    </ports>
    <portsmap>
        <https>8443</https>
        <http>8080</http>
    </portsmap>
    <ram>512</ram>
    <securitygroup>sg-12345678</securitygroup>
    <subnets>
        <subnet>subnet-abcd1234</subnet>
        <subnet>subnet-efgh5678</subnet>
    </subnets>
    <tags>
        <my-tag>My Value</my-tag>
        <my-other-tag>myothervalue</my-other-tag>
    </tags>
    <targetgroup>my-targetgroup</targetgroup>
    <tmp>16</tmp>
    <windows.user>myuser</windows.user>
    <windows.password>mypassword</windows.password>
</configuration>

Dynamically defined properties

After you execute run, CloudCaptain will automatically define the following Maven properties

Maven property Description
boxfuse.image The image that was used to launch the instances
boxfuse.instances Comma-separated list of ids of the instances just launched
boxfuse.instances.0.id Id of the instance just launched
boxfuse.instances.0.url Url of the instance just launched. Very useful for automated testing.

scale