engine

Contains methods and events related to running docker things.

Emits: event:pre-bootstrap
Since: 3.0.0
Example

// Start the docker engine
return lando.engine.up();

// List all lando containers
return lando.engine.list(data);

// Run a command(s) on a container(s)
return lando.engine.run(data);

// Inspect the details of a container
return lando.engine.inspect(data);

// Destroys a container(s)
return lando.engine.destroy(data);

engine.up() ⇒ Promise

Tries to activate the docker engine/daemon.

Generally the engine will be up and active, but if it isn't for whatever reason Lando will try to start it.

NOTE: Most commands that require the docker engine to be up will automatically call this anyway.

Kind: static method of engine
Returns: Promise - A Promise.
Emits: event:pre-engine-up, event:post-engine-up
Since: 3.0.0
Todo

  • [ ] Does this need to be publically exposed still?

Example

// List all the apps
return lando.app.list()

// Map each app to a summary and print results
.map(function(app) {
 return appSummary(app)
  .then(function(summary) {
   console.log(JSON.stringify(summary, null, 2));
 });
});

engine.isInstalled() ⇒ Promise

Determines whether the docker engine is installed or not

Kind: static method of engine
Returns: Promise - A Promise with a boolean containing the installed status.
Since: 3.0.0

engine.isUp() ⇒ Promise

Determines whether the docker engine is up or not.

Kind: static method of engine
Returns: Promise - A Promise with a boolean containing the engine up status.
Since: 3.0.0
Todo

  • [ ] Does this need to be publically exposed still?

Example

// Start the engine if it is not up
return lando.engine.isUp()

// Check if we need to start
.then(function(isUp) {
  if (!isUp) {
    return lando.engine.up();
  }
});

engine.down() ⇒ Promise

Tries to deactivate the docker engine/daemon.

NOTE: Most commands that require the docker engine to be up will automatically call this anyway.

Kind: static method of engine
Returns: Promise - A Promise.
Emits: event:pre-engine-down, event:post-engine-down
Since: 3.0.0
Todo

  • [ ] Does this need to be publically exposed still?

engine.isRunning(data) ⇒ Promise

Determines whether a container is running or not

Kind: static method of engine
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')

// Log the running status of the container
.then(isRunning) {
  lando.log.info('Container %s is running: %s', 'myapp_web_1', isRunning);
});

engine.list([data]) ⇒ Promise

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

Kind: static method of engine
Returns: Promise - A Promise with an Array of container Objects.
Since: 3.0.0

Param Type Description
[data] String An appname to filter the containers by.

Example

// List all the lando containers
return lando.engine.list()

// Log each container
.each(function(container) {
  lando.log.info(container);
});

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 object is a valid compose object

Kind: static method of engine
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

// Check whether a service exists by container id
return lando.engine.exists({name: 'myapp_web_1'})

// Log whether it exists
.then(function(exists) {
  lando.log.info('Container exists: %s', exists);
});

// Check whether a service exists by compose/app object
// Assume we have an `app` object called `app` already.

// Add the services options
var compose = app;
compose.opts = {
  services: ['web']
};

// Check existence
return lando.engine.exists(compose);

engine.inspect(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 object is a valid compose object

Kind: static method of engine
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 inspect
data.opts.services Array An Array of services to inspect.

Example

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

// Log service data by compose/app object
// Assume we have an `app` object called `app` already.

// Add the services options
var compose = app;
compose.opts = {
  services: ['web']
};

// Inspect the service
return lando.engine.inspect(compose);

engine.start(data) ⇒ Promise

Starts the containers/services for the specified compose object.

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

Kind: static method of engine
Returns: Promise - A Promise.
Emits: event:pre-engine-start, event: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

// Start up all the containers for given app object `app`
return lando.engine.start(app);

// Start and recreate specific services for an `app`
app.opts = {
  recreate: true,
  services: ['web', 'database']
};

return lando.engine.start(app);

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: static method of engine
Returns: Promise - A Promise with a string containing the command's output.
Emits: event:pre-engine-run, event: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.attachStdin] Boolean false Attach to the run's stdin. Helpful if you think there will be interactive options or prompts.
[data.opts.attachStdout] Boolean true Attach to the run's stdout. Helpful to determine what the command is doing.
[data.opts.attachStderr] Boolean true Attach to the run's stderr. Helpful to determine any errors.
[data.opts.env] Array [] Additional environmental variables to set for the cmd. Must be in the form KEY=VALUE.
[data.opts.detachKeys] String 'ctrl-p,ctrl-q' Keystrokes that will detach the process.
[data.opts.tty] Boolean true Allocate a pseudo tty.
[data.opts.user] String 'root' The user to run the command as. Can also be user:group or uid or uid:gid.

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
var bashRun = {
  id: 'myapp_database_1',
  cmd: ['bash'],
  opts: {
    mode: 'attach'
  }
};

return lando.engine.run(bashRun);

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 object is a valid compose object

Kind: static method of engine
Returns: Promise - A Promise.
Emits: event:pre-engine-stop, event: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

// Stop a specific container by id
return lando.engine.stop({name: 'myapp_service_1'})
.then(function() {
  lando.log.info('Container has stopped.');
});

// Assume we have an `app` object called `app` already.

// Stop all the containers for a particular app.
return lando.engine.stop(app);

// Stop a certain subset of an app's services.
app.opts = {
  services: ['index', 'appserver', 'db', 'db2']
};
return lando.engine.stop(app);

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 object is a valid compose object

Kind: static method of engine
Returns: Promise - A Promise.
Emits: event:pre-engine-destroy, event: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

// Remove a specific container by id
return lando.engine.destroy({name: 'myapp_service_1'})
.then(function() {
  lando.log.info('Container has been destroyed.');
});

// Assume we have an `app` object called `app` already.

// Destroy all the containers for a particular app.
return lando.engine.destroy(app);

// Force remove a certain subset of an app's services and their volumes
app.opts = {
  services: ['index', 'appserver', 'db', 'db2'],
  v: true,
  force: true
};
return lando.engine.destroy(app);

engine.logs(data) ⇒ Promise

Returns logs for a given compose object

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

Kind: static method of engine
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);

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 object is a valid compose object

Kind: static method of engine
Returns: Promise - A Promise.
Emits: event:pre-engine-build, event: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

// Build the containers for an `app` object
return lando.engine.build(app);

"event:pre-engine-up"

Event that allows you to do some things before the docker engine is booted up.

Kind: event emitted by engine
Since: 3.0.0

"event:post-engine-up"

Event that allows you to do some things after the docker engine is booted up.

Kind: event emitted by engine
Since: 3.0.0

"event:pre-engine-down"

Event that allows you to do some things after the docker engine is booted up.

Kind: event emitted by engine
Since: 3.0.0

"event:post-engine-down"

Event that allows you to do some things after the docker engine is booted up.

Kind: event emitted by engine
Since: 3.0.0

"event:pre-engine-start"

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

Kind: event emitted by engine
Since: 3.0.0

"event:post-engine-start"

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

Kind: event emitted by engine
Since: 3.0.0

"event:pre-engine-run"

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

Kind: event emitted by engine
Since: 3.0.0

"event:post-engine-run"

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

Kind: event emitted by engine
Since: 3.0.0

"event:pre-engine-stop"

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

Kind: event emitted by engine
Since: 3.0.0

"event:post-engine-stop"

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

Kind: event emitted by engine
Since: 3.0.0

"event:pre-engine-destroy"

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

Kind: event emitted by engine
Since: 3.0.0

"event:post-engine-destroy"

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

Kind: event emitted by engine
Since: 3.0.0

"event:pre-engine-build"

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

Kind: event emitted by engine
Since: 3.0.0

"event:post-engine-build"

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

Kind: event emitted by engine
Since: 3.0.0

results matching ""

    No results matching ""