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 -> http://127.0.0.1:8888

Note: When an image isn't specified, Boxfuse 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, Boxfuse will also automatically look for the project's build artifact.

Properties

Plugin Parameter Maven/System property Default Description
user boxfuse.user Required - Your Boxfuse Client user. Also configurable via the BOXFUSE_USER environment variable or the Maven settings.xml
secret boxfuse.secret Required - Your Boxfuse 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)
elb boxfuse.elb auto

AWS only

The name of the AWS ELB to use when deploying this application in the specified environment (load balanced apps only). auto to let Boxfuse 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 Check whether to payload started correctly
healthcheck.port boxfuse.healthcheck.port autodetected The port to check whether to payload started correctly
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
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
image boxfuse.image The Image to use
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 Boxfuse 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 Boxfuse image myuser/myapp:123
app Only show logs for instances of this Boxfuse app myuser/myapp
level Only show log events at this log level or higher (possible values: 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
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
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.
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:

80TCP port 80, universally accessible
80/tcpTCP port 80, universally accessible
80/udpUDP port 80, universally accessible
80/tcp:@TCP port 80 only accessible from your own IP
80/udp:@/20UDP port 80 only accessible from the IPs in the CIDR /20 block of your own IP
80/udp:1.2.3.4UDP port 80 only accessible from 1.2.3.4
80/tcp:1.2.3.4/31TCP port 80 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 Boxfuse 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 Boxfuse is running as root)
http=10080 (Mac/Linux when Boxfuse 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).
tmp boxfuse.tmp 1 The amount of temp space to allocate to /tmp in GB

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>
    <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>
    <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.tail>true</logs.tail>
    <newrelic.licensekey>0123456789abcdef0123456789abcdef012345</newrelic.licensekey>
    <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>
    <tmp>16</tmp>
</configuration>

Dynamically defined properties

After you execute run, Boxfuse 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