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

Note: When neither a payload (jar/war/zip/tgz file) nor an image is 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, 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 CloudCaptain automatically create a new boxfuse.io subdomain for you.
-elasticip=... 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=... 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=... 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

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

Check whether to payload started correctly
-healthcheck.port=... 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=... 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
-image=... 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=... 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
-linux.args=... linux.args quiet

When fusing new images only

Experts only

The arguments to pass from the bootloader to the Linux kernel
-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 CloudCaptain 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 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

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.
-platform=... 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.NAME=definition ports.NAME http=80

Exposes the port of the app with this name using this definition. Example: -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.NAME=definition 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=... 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).
-tags.key=value tags.key

AWS only

The custom tags to apply to AWS resources in addition to the default CloudCaptain ones.
-targetgroup= 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=... tmp 1 The amount of temp space to allocate to /tmp in GB
-windows.user=... windows.user current user

Hyper-V live images only

The Windows user of your machine.
-windows.password=... windows.password

Hyper-V live images only

The Windows password of your machine.

scale