lando.events:pre-engine-build()

Event that allows you to do some things before a compose object's containers are built

Kind: global function
Since: 3.0.0

lando.events:post-engine-build()

Event that allows you to do some things after a compose object's containers are built

Kind: global function
Since: 3.0.0

lando.events:pre-engine-destroy()

Event that allows you to do some things before some containers are destroyed.

Kind: global function
Since: 3.0.0

lando.events:post-engine-destroy()

Event that allows you to do some things after some containers are destroyed.

Kind: global function
Since: 3.0.0

lando.events:pre-engine-run()

Event that allows you to do some things before a command is run on a particular container.

Kind: global function
Since: 3.0.0

lando.events:post-engine-run()

Event that allows you to do some things after a command is run on a particular container.

Kind: global function
Since: 3.0.0

lando.events:pre-engine-start()

Event that allows you to do some things before a compose Objects containers are started

Kind: global function
Since: 3.0.0

lando.events:post-engine-start()

Event that allows you to do some things after a compose Objects containers are started

Kind: global function
Since: 3.0.0

lando.events:pre-engine-stop()

Event that allows you to do some things before some containers are stopped.

Kind: global function
Since: 3.0.0

lando.events:post-engine-stop()

Event that allows you to do some things after some containers are stopped.

Kind: global function
Since: 3.0.0

lando.engine.build(data) ⇒ Promise

Tries to pull the services for a compose object, and then tries to build them if they are found locally. This is a wrapper around docker pull and docker build.

NOTE: Generally an instantiated App instance is a valid compose object

Kind: global function
Returns: Promise - A Promise.
Emits: lando.events:pre-engine-build, lando.events:post-engine-build
Since: 3.0.0

Param Type Default Description
data Object A compose Object or an Array of compose Objects if you want to build more than one set of services.
data.compose Array An Array of paths to Docker compose files
data.project String A String of the project name (Usually this is the same as the app name)
[data.opts] Object Options on how to build the compose objects containers.
[data.opts.services] Array 'all services' The services to build.
[data.opts.nocache] Boolean true Ignore the build cache.
[data.opts.pull] Boolean true Try to pull first.

Example

return lando.engine.build(app);

lando.engine.createNetwork(name) ⇒ Promise

Creates a Docker network

Kind: global function
Returns: Promise - A Promise with inspect data.
See: docker api network docs for info on opts.
Since: 3.0.0.

Param Type Description
name String The name of the networks

Example

return lando.engine.createNetwork('mynetwork')

lando.engine.destroy(data) ⇒ Promise

Removes containers for a compose object or a particular container.

There are two ways to remove containers:

  1. Using an object with {id: id} where id is a docker recognizable id
  2. Using a compose object with {compose: compose, project: project, opts: opts}

These are detailed more below.

NOTE: Generally an instantiated App instance is a valid compose object

Kind: global function
Returns: Promise - A Promise.
Emits: lando.events:pre-engine-destroy, lando.events:post-engine-destroy
Since: 3.0.0

Param Type Default Description
data Object Remove criteria, Need eithers an ID or a service within a compose context
data.id String An id that docker can recognize such as a container hash or name. Can also use data.name or data.cid.
data.compose Array An Array of paths to Docker compose files
data.project String A String of the project name (Usually this is the same as the app name)
[data.opts] Object Options on what services to remove.
[data.opts.services] Array 'all services' An Array of services to remove.
[data.opts.volumes] Boolean true Also remove volumes associated with the container(s).
[data.opts.force] Boolean false Force remove the containers.
[data.opts.purge] Boolean false Implies volumes and force.

Example

return lando.engine.destroy(app);

lando.engine.exists(data) ⇒ Promise

Checks whether a specific service exists or not.

There are two ways to check whether a container exists:

  1. Using an object with {id: id} where id is a docker recognizable id
  2. Using a compose object with {compose: compose, project: project, opts: opts}

These are detailed more below.

NOTE: Generally an instantiated app instance is a valid compose object

Kind: global function
Returns: Promise - A Promise with a Boolean of whether the service exists or not.
Since: 3.0.0

Param Type Description
data Object Search criteria, Need eithers an ID or a service within a compose context
data.id String An id that docker can recognize such as a conatainer hash or name. Can also use data.name or data.cid.
data.compose Array An Array of paths to Docker compose files
data.project String A String of the project name (Usually this is the same as the app name)
data.opts Object Options on what service to check
data.opts.services Array An Array of services to check

Example

return lando.engine.exists(compose);

lando.engine.getNetwork(id) ⇒ Object

Gets a Docker network

Kind: global function
Returns: Object - A Dockerode Network object .
Since: 3.0.0.

Param Type Description
id String The id of the network

Example

const network = lando.engine.getNetwork('mynetwork')

lando.engine.getNetworks([opts]) ⇒ Promise

Gets the docker networks.

Kind: global function
Returns: Promise - A Promise with an array of network objects.
See: docker api network docs for info on filters option.
Since: 3.0.0

Param Type Description
[opts] Object Options to pass into the docker networks call
[opts.filters] Object Filters options

lando.engine.isRunning(data) ⇒ Promise

Determines whether a container is running or not

Kind: global function
Returns: Promise - A Promise with a boolean of whether the container is running or not
Since: 3.0.0

Param Type Description
data String An ID that docker can recognize such as the container id or name.

Example

// Check to see if our app's web service is running
return lando.engine.isRunning('myapp_web_1').then(isRunning) {
  lando.log.info('Container %s is running: %s', 'myapp_web_1', isRunning);
});

lando.engine.list([options]) ⇒ Promise

Lists all the Lando containers. Optionally filter by app name.

Kind: global function
Returns: Promise - A Promise with an Array of container Objects.
Since: 3.0.0

Param Type Default Description
[options] Object Options to filter the list.
[options.all] Boolean false Show even stopped containers
[options.app] String Show containers for only a certain app
[options.filter] Array Filter by additional key=value pairs

Example

return lando.engine.list().each(function(container) {
  lando.log.info(container);
});

lando.engine.logs(data) ⇒ Promise

Returns logs for a given compose object

NOTE: Generally an instantiated app instance is a valid compose object

Kind: global function
Returns: Promise - A Promise.
Since: 3.0.0

Param Type Default Description
data Object A compose Object or an Array of compose Objects if you want to get logs for more than one set of services.
data.compose Array An Array of paths to Docker compose files
data.project String A String of the project name (Usually this is the same as the app name)
[data.opts] Object Options on how to build the compose objects containers.
[data.opts.follow] Boolean false Whether to follow the log. Works like tail -f.
[data.opts.timestamps] Boolean true Show timestamps in log.

Example

// Get logs for an app
return lando.engine.logs(app);

lando.engine.run(data) ⇒ Promise

Runs a command on a given service/container. This is a wrapper around docker exec.

UNTIL the resolution of https://github.com/apocas/docker-modem/issues/83 data needs to also be or be an array of compose objects for this to work correctly on Windows as well. See some of the other engine documentation for what a compose object looks like.

Kind: global function
Returns: Promise - A Promise with a string containing the command's output.
Emits: lando.events:pre-engine-run, lando.events:post-engine-run
Since: 3.0.0

Param Type Default Description
data Object A run Object or an Array of run Objects if you want to run more tha one command.
data.id String The container to run the command on. Must be an id that docker can recognize such as a container hash or name.
data.cmd String A String of a command or an Array whose elements are the parts of the command.
[data.opts] Object Options on how to run the command.
[data.opts.mode] String 'collect' Either collect or attach. Attach will connect to the run stdin.
[data.opts.pre] String A String or Array of additional arguments or options to append to the cmd before the user specified args and options are added.
[data.opts.env] Array [] Additional environmental variables to set for the cmd. Must be in the form KEY=VALUE.
[data.opts.user] String 'root' The user to run the command as. Can also be user:group or uid or uid:gid.
[data.opts.detach] String false Run the process in the background
[data.opts.autoRemove] String false Automatically removes the container

Example

// Run composer install on the appserver container for an app called myapp
return lando.engine.run({id: 'myapp_appserver_1', cmd: ['composer', 'install']});

// Drop into an interactive bash shell on the database continer for an app called myapp
return lando.engine.run({
  id: 'myapp_database_1',
  cmd: ['bash'],
  opts: {
    mode: 'attach'
  }
});

lando.engine.scan(data) ⇒ Promise

Returns comprehensive service metadata. This is a wrapper around docker inspect.

There are two ways to get container metadata:

  1. Using an object with {id: id} where id is a docker recognizable id
  2. Using a compose object with {compose: compose, project: project, opts: opts}

These are detailed more below.

NOTE: Generally an instantiated app instance is a valid compose object

Kind: global function
Returns: Promise - A Promise with an Object of service metadata.
Since: 3.0.0

Param Type Description
data Object Search criteria, Need eithers an ID or a service within a compose context
data.id String An id that docker can recognize such as a conatainer hash or name. Can also use data.name or data.cid.
data.compose Array An Array of paths to Docker compose files
data.project String A String of the project name (Usually this is the same as the app name)
data.opts Object Options on what service to scan
data.opts.services Array An Array of services to scan.

Example

// Log scan data using an id
return lando.engine.scan({id: '146d321f212d'}).then(function(data) {
  lando.log.info('Container data is %j', data);
});

lando.engine.start(data) ⇒ Promise

Starts the containers/services for the specified compose object.

NOTE: Generally an instantiated app instance is a valid compose object

Kind: global function
Returns: Promise - A Promise.
Emits: lando.events:pre-engine-start, lando.events:post-engine-start
Since: 3.0.0

Param Type Default Description
data Object A compose Object or an Array of compose Objects if you want to start more than one set of services.
data.compose Array An Array of paths to Docker compose files
data.project String A String of the project name (Usually this is the same as the app name)
[data.opts] Object Options on how to start the compose Objects containers.
[data.opts.services] Array 'all services' The services to start.
[data.opts.background] Boolean true Start the services in the background.
[data.opts.recreate] Boolean false Recreate the services.
[data.opts.removeOrphans] Boolean true Remove orphaned containers.

Example

return lando.engine.start(app);

lando.engine.stop(data) ⇒ Promise

Stops containers for a compose object or a particular container.

There are two ways to stop containers:

  1. Using an object with {id: id} where id is a docker recognizable id
  2. Using a compose object with {compose: compose, project: project, opts: opts}

These are detailed more below.

NOTE: Generally an instantiated app instance is a valid compose object

Kind: global function
Returns: Promise - A Promise.
Emits: lando.events:pre-engine-stop, lando.events:post-engine-stop
Since: 3.0.0

Param Type Default Description
data Object Stop criteria, Need eithers an ID or a service within a compose context
data.id String An id that docker can recognize such as a container hash or name. Can also use data.name or data.cid.
data.compose Array An Array of paths to Docker compose files
data.project String A String of the project name (Usually this is the same as the app name)
[data.opts] Object Options on what services to setop
[data.opts.services] Array 'all services' An Array of services to stop.

Example

return lando.engine.stop(app);