run

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: boxfuse run payload | image -env=environment

> boxfuse run 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 neither a payload (jar/war/zip/tgz file) nor an image is 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, Gradle or SBT project, the output directory of that project will be automatically scanned as well.

Settings

Argument boxfuse.conf property Default Description
-capacity=... 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=... 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=... cpus same as host

VirtualBox only

The number of CPUs to assign to an Instance
-debug debug false Start the Payload in debug mode when an Instance launches
-debug.wait 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=... domain auto

AWS only

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

AWS only

The AWS Elastic IP to use when deploying this application in the specified environment (single-instance apps only). auto to let Boxfuse automatically create a new Elastic IP for you.
-elb=... 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=... env dev Select the specified environment (ex.: test or prod)
-envvars.NAME=value envvars.NAME Passes this environment variable into the instance.
Example: -envvars.JDBC_URL=jdbc:mydburl
-healthcheck healthcheck true Check whether to payload started correctly
-healthcheck.port=... healthcheck.port autodetected The port to check whether to payload started correctly
-healthcheck.path=... healthcheck.path / The path to check whether to payload started correctly
-healthcheck.timeout=... healthcheck.timeout 300 The number of seconds to wait for the Payload to come up
-instanceprofile=... 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=... jvm.args

JVM apps only

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

JVM apps only

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

JVM apps only

Main class to invoke on JVM startup
-jvm.main.args=... jvm.main.args

JVM apps only

Arguments to pass to the main class
-live 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 logs.auto true Whether to automatically display the instance logs on startup
-logs.boot logs.boot true Shows the instance boot logs
-logs.dir=... logs.dir The directory where the logs should be redirected to
-logs.filter.FILTER=value 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: 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

Important note for Linux and macOS users: when using wildcards the argument should be enclosed in single quotes.
Example: '-logs.filter.message=*my text to match*'

-logs.layout=... 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 logs.tail false Tail (keep running with live updates) the logs
-newrelic.licensekey=... newrelic.licensekey

When fusing new images only

Installs and configures the New Relic agents to monitor your instance.
-ports.NAME=definition ports.NAME http=80

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

Supported formats:

80 TCP port 80, universally accessible
80/tcp TCP port 80, universally accessible
80/udp UDP port 80, universally accessible
80/tcp:@ TCP port 80 only accessible from your own IP
80/udp:@/20 UDP port 80 only accessible from the IPs in the CIDR /20 block of your own IP
80/udp:1.2.3.4 UDP port 80 only accessible from 1.2.3.4
80/tcp:1.2.3.4/31 TCP port 80 only accessible from the IPs in the CIDR /31 block of 1.2.3.4
-portsmap.NAME=definition 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=... ram 1024

VirtualBox only

The amount of RAM in MB to assign to an Instance (VirtualBox only)

-securitygroup=... 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=... subnets auto

AWS only

Comma-separated list of 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=... tmp 1 The amount of temp space to allocate to /tmp in GB

scale