lando ⇒ Object

Contains the main bootstrap function, which will:

  1. Instantiate the lando object.
  2. Emit bootstrap events
  3. Initialize plugins

You will want to use this to grab lando instead of using require('lando')(config). The intiialization config in the example below is not required but recommended. You can pass in any additional properties to override subsequently set/default values.

Check out ./bin/lando.js in this repository for an example of bootstraping lando for usage in a CLI.

Emits: pre_bootstrap, post_bootstrap
Since: 3.0.0

Param Type Description
[options] Object Options to initialize the bootstrap

Returns: Object - An initialized Lando object
Example

// Get the bootstrap function
var bootstrap = require('lando/lib/bootstrap');
var options = {
  logLevelConsole: LOGLEVELCONSOLE,
  userConfRoot: USERCONFROOT,
  envPrefix: ENVPREFIX,
  configSources: configSources,
  pluginDirs: [USERCONFROOT],
  mode: 'cli'
};

// Initialize Lando with some options
bootstrap(options)

// Initialize some other things
.then(function(lando) {
  return cli.init(lando);
})

lando.cli.largv

A singleton object that contains the Lando global options.

This means all the options passed in after the -- flag.

Since: 3.0.0
Example

// Gets all the global options that have been specified.
var largv = lando.tasks.largv;

lando.events

This extends the core node event emitter except where otherwise documented below

See: https://nodejs.org/api/events.html

lando.events.__on

Stores the original event on method.

I don't think you want to ever really use this. Mentioned only for transparency.

See: https://nodejs.org/api/events.html

lando.events.__emit

Stores the original event emit method.

I don't think you want to ever really use this. Mentioned only for transparency.

See: https://nodejs.org/api/events.html

lando.node._

Get lodash

Since: 3.0.0
Example

// Get the lodash module
var _ = lando.node._;

lando.node.chalk

Get chalk

Since: 3.0.0
Example

// Get the chalk module
var chalk = lando.node.chalk;

lando.node.fs

Get fs-extra

Since: 3.0.0
Example

// Get the fs-extra module
var fs = lando.node.fs;

lando.node.hasher

Get object-hash

Since: 3.0.0
Example

// Get the object-hash module
var hasher = lando.node.hasher;

lando.node.ip

Get ip utils

Since: 3.0.0
Example

// Get the ip module
var ip = lando.node.ip;

lando.node.jsonfile

Get jsonfile

Since: 3.0.0
Example

// Get the jsonfile module
var jsonfile = lando.node.jsonfile;

lando.node.rest

Get restler

Since: 3.0.0
Example

// Get the restler module
var rest = lando.node.rest;

lando.node.semver

Get semver

Since: 3.0.0
Example

// Get the semver module
var semver = lando.node.semver;

lando.Promise

Extends bluebird so that our promises have some retry functionality.

All functionality should be the same as bluebird except where indicated below

See: http://bluebirdjs.com/docs/api-reference.html

lando.tasks.tasks

A singleton array that contains all the tasks that have been added.

Since: 3.0.0
Example

// Gets all the tasks that have been loaded
var task = lando.tasks.tasks;

lando.cache.set(key, data, [opts])

Sets an item in the cache

Since: 3.0.0

Param Type Default Description
key String The name of the key to store the data with.
data Any The data to store in the cache.
[opts] Object Options to pass into the cache
[opts.persist] Boolean false Whether this cache data should persist between processes. Eg in a file instead of memory
[opts.ttl] Integer 0 Seconds the cache should live. 0 mean forever.

Example

// Add a string to the cache
lando.cache.set('mykey', 'mystring');

// Add an object to persist in the file cache
lando.cache.set('mykey', data, {persist: true});

// Add an object to the cache for five seconds
lando.cache.set('mykey', data, {ttl: 5});

lando.cache.get(key) ⇒ Any

Gets an item in the cache

Since: 3.0.0

Param Type Description
key String The name of the key to retrieve the data.

Returns: Any - The data stored in the cache if applicable.
Example

// Get the data stored with key mykey
var data = lando.cache.get('mykey');

lando.cache.remove(key)

Manually remove an item from the cache.

Since: 3.0.0

Param Type Description
key String The name of the key to remove the data.

Example

// Remove the data stored with key mykey
lando.cache.remove('mykey');

lando.utils.config.tryConvertJson(value) ⇒ Object

Attempt to parse a JSON string to an objects

Since: 3.0.0

Param Type Description
value String The string to convert

Returns: Object - A parsed object or the inputted value

lando.utils.config.merge(old, fresh) ⇒ Object \| Object

Uses _.mergeWith to concat arrays, this helps replicate how Docker https://lodash.com/docs#mergeWith Compose merges its things

Since: 3.0.0

Param Type Description
old Object object to be merged
fresh Object object to be merged

Returns: Object - The new objectObject - Merged object or arrays
Example

// Take an object and write a docker compose file
var newObject = _.mergeWith(a, b, lando.utils.merger);

lando.utils.config.stripEnv(prefix) ⇒ Object

Strips process.env of all envvars with PREFIX and returns process.env

NOTE: this actually returns process.env not a NEW object cloned from process.env

Since: 3.0.0

Param Type Description
prefix String The prefix to strip

Returns: Object - Updated process.env
Example

// Reset the process.env without any DOCKER_ prefixed envvars
process.env = config.stripEnv('DOCKER_');

lando.utils.config.defaults() ⇒ Object

Define default config

Since: 3.0.0
Returns: Object - The default config object.

lando.utils.config.loadFiles(files) ⇒ Object

Merge in config file if it exists

Since: 3.0.0

Param Type Description
files Array An array of files to try loading

Returns: Object - An object of config merged from file sources

lando.utils.config.loadEnvs(prefix) ⇒ Object

Filter process.env by a given prefix

Since: 3.0.0

Param Type Description
prefix String The prefix by which to filter. Should be without the trailing _ eg LANDO not LANDO_

Returns: Object - Object of things with camelCased keys

lando.cli.argv()

Returns the lando options

This means all the options passed in before the -- flag.

Since: 3.0.0
Example

// Gets all the global options that have been specified.
var argv = lando.tasks.argv();

lando.cli.parseToYargs(task, events) ⇒ Object

Parses a lando task object into something that can be used by the yargs CLI.

A lando task object is an abstraction on top of yargs that also contains some metadata about how to interactively ask questions on both a CLI and GUI.

The interactivity metadata is a superset of inquirer data.

See

Since: 3.0.0
Todo

  • [ ] Injecting the events here seems not the way we want to go?
Param Type Description
task Object A Lando task object (@see add for definition)
events Object The Lando events engine

Returns: Object - A yargs command object
Example

// Add a task to the yargs CLI
yargs.command(lando.tasks.parseToYargs(task));

lando.cli.startHeader() ⇒ String

Returns a cheeky header that can be used after an app is started.

Since: 3.0.0
Returns: String - A header string we can print to the CLI
Example

// Print the header to the console
console.log(lando.cli.startHeader());

lando.cli.initHeader() ⇒ String

Returns a cheeky header that can be used after an app is init.

Since: 3.0.0
Returns: String - A header string we can print to the CLI
Example

// Print the header to the console
console.log(lando.cli.initHeader());

lando.cli.tunnelHeader() ⇒ String

Returns a cheeky header that can be used after an app is shared

Since: 3.0.0
Returns: String - A header string we can print to the CLI
Example

// Print the header to the console
console.log(lando.cli.tunnelHeader());

lando.cli.updateMessage(url) ⇒ String

Returns a mesage indicating the availability of an update

Since: 3.0.0

Param Type Description
url String The URL with the link to the update

Returns: String - An update message we can print to the CLI
Example

// Print the header to the console
console.log(lando.cli.updateMessage());

lando.cli.Table([opts]) ⇒ Object

Utility function to help construct CLI displayable tables

Since: 3.0.0

Param Type Default Description
[opts] Object Options for how the table should be built
[opts.arrayJoiner] String ', ' A delimiter to be used when joining array data

Returns: Object - Table metadata that can be printed with toString()
Example

// Grab a new cli table
var table = new lando.cli.Table();

// Add data
table.add('NAME', app.name);
table.add('LOCATION', app.root);
table.add('SERVICES', _.keys(app.services));
table.add('URLS', urls, {arrayJoiner: '\n'});

// Print the table
console.log(table.toString());

lando.events.on(name, [priority], fn) ⇒ Promise

Our overriden event on method.

This optionally allows a priority to be specified. Lower priorities run first.

Since: 3.0.0

Param Type Default Description
name String The name of the event
[priority] Integer 5 The priority the event should run in.
fn function The function to call. Should get the args specified in the corresponding emit declaration.

Returns: Promise - A Promise
Example

// Print out all our apps as they get instantiated and do it before other `post-instantiate-app` events
lando.events.on('post-instantiate-app', 1, function(app) {
  console.log(app);
});

// Log a helpful message after an app is started, don't worry about whether it runs before or
// after other `post-start` events
return app.events.on('post-start', function() {
  lando.log.info('App %s started', app.name);
});

lando.events.emit(name, [...args]) ⇒ Promise

Reimplements event emit method.

This makes events blocking and promisified.

Since: 3.0.0

Param Type Description
name String The name of the event
[...args] Any Options args to pass.

Returns: Promise - A Promise
Example

// Emits a global event with a config arg
return lando.events.emit('wolf359', config);

// Emits an app event with a config arg
return app.events.emit('sector001', config);

lando.log.debug(msg, [...values])

Logs a debug message.

Since: 3.0.0

Param Type Description
msg String A string that will be passed into nodes core utils.format()
[...values] Any Values to be passed utils.format()

Example

// Log a debug message
lando.log.debug('All details about docker inspect %j', massiveObject);

lando.log.error(msg, [...values])

Logs an error message.

Since: 3.0.0

Param Type Description
msg String A string that will be passed into nodes core utils.format()
[...values] Any Values to be passed utils.format()

Example

// Log an error message
lando.log.error('This is an err with details %j', err);

lando.log.info(msg, [...values])

Logs an info message.

Since: 3.0.0

Param Type Description
msg String A string that will be passed into nodes core utils.format()
[...values] Any Values to be passed utils.format()

Example

// Log an info message
lando.log.info('It is happening!');

lando.log.silly(msg, [...values])

Logs a silly message.

Since: 3.0.0

Param Type Description
msg String A string that will be passed into nodes core utils.format()
[...values] Any Values to be passed utils.format()

Example

// Log a silly message
lando.log.silly('All details about all the things', unreasonablySizedObject);

// Log a silly message
lando.log.silly('If you are seeing this you have delved too greedily and too deep and likely have awoken something.');

lando.log.verbose(msg, [...values])

Logs a verbose message.

Since: 3.0.0

Param Type Description
msg String A string that will be passed into nodes core utils.format()
[...values] Any Values to be passed utils.format()

Example

// Log a verbose message
lando.log.verbose('Config file %j loaded from %d', config, directory);

lando.log.warn(msg, [...values])

Logs a warning message.

Since: 3.0.0

Param Type Description
msg String A string that will be passed into nodes core utils.format()
[...values] Any Values to be passed utils.format()

Example

// Log a warning message
lando.log.warning('Something is up with app %s in directory %s', appName, dir);

lando.plugins.load(plugin, dirs, [inject]) ⇒ Promise

Loads a plugin.

For each directory scanned plugins can live in either the plugins or node_modules subdirectories

Since: 3.0.0

Param Type Description
plugin String The name of the plugin
dirs Array The directories to scan for plugins.
[inject] Object An object to inject into the plugin.

Returns: Promise - A Promise.
Example

// Load the plugin called 'shield-generator' and additionally scan `/tmp` for the plugin
return lando.plugins.load('shield-generator', ['/tmp']);

lando.Promise.retry(fn, [opts]) ⇒ Promise

Adds a retry method to all Promise instances.

Since: 3.0.0

Param Type Default Description
fn function The function to retry.
[opts] Opts Options to specify how retry works.
[opts.max] Integer 5 The amount of times to retry.
[opts.backoff] Integer 500 The amount to wait between retries. In miliseconds and cumulative.

Returns: Promise - A Promise
Example

// Start the deamon
return serviceCmd(['start'], opts)

// And then retry 25 times until we've connected, increase delay between retries by 1 second
.retry(function() {
  log.verbose('Trying to connect to daemon.');
  return shell.sh([DOCKER_EXECUTABLE, 'info'], {mode: 'collect'});
}, {max: 25, backoff: 1000});

lando.scanUrls(urls, [opts]) ⇒ Array

Scans URLs to determine if they are up or down.

Since: 3.0.0

Param Type Default Description
urls Array An array of urls like https://mysite.lndo.site or https://localhost:34223
[opts] Object Options to configure the scan.
[opts.max] Integer 7 The amount of times to retry accessing each URL.
[opts.waitCode] Array [400, 502 The HTTP codes to prompt a retry.

Returns: Array - An array of objects of the form {url: url, status: true|false}
Example

// Scan URLs and print results
return lando.utils.scanUrls(['http://localhost', 'https://localhost'])
.then(function(results) {
  console.log(results);
});

lando.shell.sh(cmd, [opts]) ⇒ Promise

Runs a command.

This is an abstraction method that:

  1. Delegates to either node's native spawn or exec methods.
  2. Promisifies the calling of these function
  3. Handles stdout, stdin and stderr

Beyond the options specified below you should be able to pass in known exec or spawn options depending on whether we have a mode or not.

See

Since: 3.0.0

Param Type Description
cmd Array The command to run as elements in an array or a string.
[opts] Object Options to help determine how the exec is run.
[opts.detached] Boolean Whether we are running in detached mode or not (deprecated)

Returns: Promise - A promise with collected results if applicable.
Example

// Run a command in collect mode
return lando.shell.sh(['ls', '-lsa', '/'], {mode: 'collect'})

// Catch and log any errors
.catch(function(err) {
  lando.log.error(err);
})

// Print the collected results of the command
.then(function(results) {
  console.log(results);
});

lando.shell.escSpaces(s) ⇒ String

Escapes any spaces in a command.

Since: 3.0.0

Param Type Description
s Array A command as elements of an Array or a String.

Returns: String - The space escaped cmd.
Example

// Escape the spaces in the cmd
var escapedCmd = lando.shell.escSpaces(['git', 'commit', '-m', 'my message']);

lando.shell.esc(cmd) ⇒ String

Escapes special characters in a command to make it more exec friendly.

Since: 3.0.0

Param Type Description
cmd Array A command as elements of an Array or a String.

Returns: String - The escaped cmd.
Example

// Escape the cmd
var escapedCmd = lando.shell.esc(['git', 'commit', '-m', 'my message']);

lando.shell.which(cmd) ⇒ String \| undefined

Returns the path of a specific command or binary.

Since: 3.0.0

Param Type Description
cmd String A command to search for.

Returns: String | undefined - The path to the command or undefined.
Example

// Determine the location of the 'docker' command
var which = lando.shell.which(DOCKER_EXECUTABLE);

lando.tasks.add(name, task)

Adds a Lando task to the global lando.tasks.task object.

A lando task object is an abstraction on top of yargs and inquirer with a little extra special sauce.

See

Since: 3.0.0

Param Type Description
name String The name of the task.
task Object A Lando task object
task.command String A yargs formatted command
task.description String A short description of the command
task.options Object A yargs builder object. Each builder also has an 'interactive' key which is an inquirier question object
task.run function The function to run when the task is invoked.
task.run.options Object The options selected by the user, available to the run function.

Example

// Define a task
var task = {
  command: 'destroy [appname]',
  describe: 'Destroy app in current directory or [appname]',
  options: {
    yes: {
      describe: 'Auto answer yes to prompts',
      alias: ['y'],
      default: false,
      boolean: true,
      interactive: {
        type: 'confirm',
        message: 'Are you sure you want to DESTROY?'
      }
    }
  },
  run: function(options) {
    console.log(options);
  }
};

// Add the task to Lando
lando.tasks.add('destroy', task);

lando.updates.updateAvailable(version1, version2) ⇒ Boolean

Compares two versions and determines if an update is available or not

Since: 3.0.0

Param Type Description
version1 String The current version.
version2 String The potential update version

Returns: Boolean - Whether an update is avaiable.
Example

// Does our current version need to be updated?
var updateAvailable = lando.updates.updateAvailable('1.0.0', '1.0.1');

lando.updates.fetch()

Determines whether we need to fetch updatest or not

Since: 3.0.0

lando.updates.refresh()

Get latest version info from github

Since: 3.0.0

lando.user.getUid([username]) ⇒ String

Returns the id of the current user or username.

Note that on Windows this value is more or less worthless and username has has no effect

Since: 3.0.0

Param Type Default Description
[username] String '$(whoami)' The username to get the ID for

Returns: String - The user ID.
Example

// Get the id of the user.
var userId = lando.user.getUid();

lando.user.getGid([username]) ⇒ String

Returns the id of the current user or username.

Note that on Windows this value is more or less worthless and username has has no effect

Since: 3.0.0

Param Type Default Description
[username] String '$(whoami)' The username to get the ID for

Returns: String - The group ID.
Example

// Get the id of the user.
var groupId = lando.user.getGid();

lando.yaml.load(file) ⇒ Object

Loads a yaml object from a file

Since: 3.0.0

Param Type Description
file String The path to the file to be loaded

Returns: Object - The loaded object
Example

// Add a string to the cache
var thing = lando.yaml.load('/tmp/myfile.yml');

lando.yaml.dump(file, data) ⇒

Dumps an object to a YAML file

Since: 3.0.0

Param Type Description
file String The path to the file to be loaded
data Object The object to dump

Returns: - Flename

lando.app.register(app) ⇒ Promise

Adds an app to the app registry.

Since: 3.0.0

Param Type Description
app Object The app to add
app.name String The name of the app.
app.dir String The absolute path to this app's lando.yml file.
[app.data] Object Optional metadata

Returns: Promise - A Promise
Example

// Define an app with some additional and optional metadata
var app = {
  name: 'starfleet.mil',
  dir: '/Users/picard/Desktop/lando/starfleet',
  data: {
    warpfactor: 9
  }
};

// Register the app
return lando.registry.register(app);

lando.app.unregister(app) ⇒ Promise

Removes an app from the app registry.

Since: 3.0.0

Param Type Description
app Object The app to remove
app.name String The name of the app.
app.dir String The absolute path to this app's lando.yml file.

Returns: Promise - A Promise
Example

// Define an app with some additional and optional metadata
var app = {
  name: 'starfleet.mil',
  dir: '/Users/picard/Desktop/lando/starfleet'
};

// Remove the app
return lando.unregister(app);

lando.app.list() ⇒ Promise

Lists all the Lando apps from the app registry.

Since: 3.0.0
Returns: Promise - Returns a Promise with an array of apps from the registry
Example

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

// Pretty print each app to the console.
.map(function(app) {
  console.log(JSON.stringify(app, null, 2));
});

lando.app.get([appName]) ⇒ Promise

Gets a fully instantiated app object.

If you do not pass in an appName Lando will attempt to find an app in your current working directory.

Lando will also scan parent directories if no app is found.

Emits: pre_instantiate_app, post_instantiate_app, app_ready
Since: 3.0.0

Param Type Description
[appName] String The name of the app to get.

Returns: Promise - Returns a Pronise with an instantiated app object or nothing.
Example

// Get an app named myapp and start it
return lando.app.get('myapp')

// Start the app
.then(function(app) {
  lando.app.start(app);
});

lando.app.isRunning(app, checkall) ⇒ Promise

Determines whether an app is running or not. By defualt it only requires that a single service for that be running to return true but see opts below.

You can pass in an entire app object here but it really just needs an object with the app name eg {name: 'myapp'}

Since: 3.0.0

Param Type Description
app Object An app object.
app.name String The name of the app
checkall Boolean Make sure ALL the apps containers are running

Returns: Promise - Returns a Promise with a boolean of whether the app is running or not.
Example

// Let's check to see if the app has been started
return lando.app.isRunning(app)

// Start the app if its not running already
.then(function(isRunning) {
  if (!isRunning) {
    return lando.app.start(app);
  }
});

lando.app.exists(appName) ⇒ Promise

Checks to see if the app exists or not.

Since: 3.0.0

Param Type Description
appName String The name of the app to get.

Returns: Promise - A promise with a boolean of whether the app exists or not.
Example

// Get an app named myapp and start it
return lando.app.exists('myapp')

// Theorize if app exists
.then(function(exists) {
  if (exists) {
    console.log('I think, therefore I am.')
  }
});

lando.app.info(app) ⇒ Promise

Prints useful information about the app's services.

This should return information about the services the app is running, URLs the app can be accessed at, relevant connection information like database credentials and any other information that is added by other plugins.

Emits: pre_info, post_info
Since: 3.0.0

Param Type Description
app Object A fully instantiated app object

Returns: Promise - A Promise with an object of information about the app keyed by its services
Example

// Return the app info
return lando.app.info(app)

// And print out any services with urls
.each(function(service) {
  if (_.has(service, 'urls')) {
    console.log(service.urls);
  }
});

lando.app.uninstall(app) ⇒ Promise

Soft removes the apps services but maintains persistent data like app volumes.

This differs from destroy in that destroy will hard remove all app services, volumes, networks, etc as well as remove the app from the appRegistry.

Emits: pre_uninstall, post_uninstall
Since: 3.0.0

Param Type Description
app Object A fully instantiated app object

Returns: Promise - A Promise.
Example

// Uninstall the app
return lando.app.uninstall(app)

// Catch any errors
catch(function(err) {
  lando.log.error(err);
});

lando.app.cleanup() ⇒ Promise

Does some helpful cleanup before running an app operation.

This command helps clean up apps in an inconsistent state and any orphaned containers they may have.

Since: 3.0.0
Todo

  • [ ] Should this be an internal method? Or can we deprecate at some point?

Returns: Promise - A Promise.
Example

// Do the app cleanup
return lando.app.cleanup()

lando.app.start(app) ⇒ Promise

Starts an app.

This will start up all services/containers that have been defined for this app.

Emits: pre_start, post_start
Since: 3.0.0

Param Type Description
app Object A fully instantiated app object

Returns: Promise - A Promise.
Example

// Start the app
return lando.app.start(app)

// Catch any errors
catch(function(err) {
  lando.log.error(err);
});

lando.app.stop(app) ⇒ Promise

Stops an app.

This will stop all services/containers that have been defined for this app.

Emits: pre_stop, post_stop
Since: 3.0.0

Param Type Description
app Object A fully instantiated app object

Returns: Promise - A Promise.
Example

// Stop the app
return lando.app.stop(app)

// Catch any errors
catch(function(err) {
  lando.log.error(err);
});

lando.app.restart(app) ⇒ Promise

Stops and then starts an app.

This just runs app.stop and app.start in succession.

Emits: pre_stop, post_stop, pre_start, post_start
Since: 3.0.0

Param Type Description
app Object A fully instantiated app object

Returns: Promise - A Promise.
Example

// Restart the app
return lando.app.restart(app)

// Catch any errors
catch(function(err) {
  lando.log.error(err);
});

lando.app.destroy(app) ⇒ Promise

Hard removes all app services, olumes, networks, etc as well as removes the app from the appRegistry.

This differs from uninstall in that uninstall will only soft remove all app services, while maintaining things like volumes, networks, etc as well as an entry in the appRegistry.

That said this DOES call both stop and uninstall.

Emits: pre_destroy, pre_stop, post_stop, pre_uninstall, post_uninstall, post_destroy
Since: 3.0.0

Param Type Description
app Object A fully instantiated app object

Returns: Promise - A Promise.
Example

// Destroy the app
return lando.app.destroy(app)

// Catch any errors
catch(function(err) {
  lando.log.error(err);
});

lando.app.rebuild(app) ⇒ Promise

Rebuilds an app.

This will stop an app, soft remove its services, rebuild those services and then, finally, start the app back up again. This is useful for developers who might want to tweak Dockerfiles or compose yamls.

Emits: pre_stop, post_stop, pre_uninstall, post_uninstall, pre_start, post_start
Since: 3.0.0

Param Type Description
app Object A fully instantiated app object

Returns: Promise - A Promise.
Example

// Rebuild the app
return lando.app.rebuild(app)

// Catch any errors
catch(function(err) {
  lando.log.error(err);
});

lando.utils.app.appNameExists()

Checks if there is already an app with the same name in an app _registry object

Since: 3.0.0

lando.utils.app.validateFiles()

Validates compose files returns legit ones

Since: 3.0.0

lando.utils.app.compose()

Takes data and spits out a compose object

Since: 3.0.0

lando.utils.app.startTable()

Returns a CLI table with app start metadata info

Since: 3.0.0

lando.utils.app.getUrls()

Takes inspect data and extracts all the exposed ports

Since: 3.0.0

lando.utils.app.getInfoDefaults()

Returns a default info object

Since: 3.0.0

lando.utils.app.metricsParse()

Helper to parse metrics data

Since: 3.0.0

lando.engine.isInstalled() ⇒ Promise

Determines whether the docker engine is installed or not

Since: 3.0.0
Returns: Promise - A Promise with a boolean containing the installed status.

lando.engine.isUp() ⇒ Promise

Determines whether the docker engine is up or not.

Since: 3.0.0
Todo

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

Returns: Promise - A Promise with a boolean containing the engine up status.
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();
  }
});

lando.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.

Emits: pre_engine_up, post_engine_up
Since: 3.0.0
Todo

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

Returns: Promise - A Promise.
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));
 });
});

lando.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.

Emits: pre_engine_down, post_engine_down
Since: 3.0.0
Todo

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

Returns: Promise - A Promise.

lando.engine.isRunning(data) ⇒ Promise

Determines whether a 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.

Returns: Promise - A Promise with a boolean of whether the container is running or not
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);
});

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

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

Since: 3.0.0

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

Returns: Promise - A Promise with an Array of container Objects.
Example

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

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

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

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

Returns: Promise - A Promise with a Boolean of whether the service exists or not.
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);

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

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.

Returns: Promise - A Promise with an Object of service metadata.
Example

// Log scan data using an id
return lando.engine.scan({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']
};

// scan the service
return lando.engine.scan(compose);

lando.engine.start(data) ⇒ Promise

Starts the containers/services for the specified compose object.

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

Emits: pre_engine_start, 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.

Returns: Promise - A Promise.
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);

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.

Emits: pre_engine_run, 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.

Returns: Promise - A Promise with a string containing the command's output.
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);

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

Emits: pre_engine_stop, 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.

Returns: Promise - A Promise.
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);

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

Emits: pre_engine_destroy, 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.

Returns: Promise - A Promise.
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);

lando.engine.logs(data) ⇒ Promise

Returns logs for a given compose object

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

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.

Returns: Promise - A Promise.
Example

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

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

Emits: pre_engine_build, 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.

Returns: Promise - A Promise.
Example

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

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

Gets the docker networks.

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

Returns: Promise - A Promise with an array of network objects.
Example

// Options to filter the networks
 var opts = {
   filters: {
     driver: {bridge: true},
     name: {_default: true}
   }
 };

 // Get the networks
 return lando.engine.getNetworks(opts)

 // Filter out lando_default
 .filter(function(network) {
   return network.Name !== 'lando_default';
 })

 // Map to list of network names
 .map(function(network) {
   return network.Name;
 });

lando.engine.getNetwork(id) ⇒ Object

Gets a Docker network

Since: 3.0.0.

Param Type Description
id String The id of the network

Returns: Object - A Dockerode Network object .
Example

// Get the network
 return lando.engine.getNetwork('mynetwork')

lando.engine.createNetwork(name, [opts]) ⇒ Promise

Creates a Docker network

See: docker api network docs for info on opts.
Since: 3.0.0.

Param Type Description
name String The name of the networks
[opts] Object See API network docs above

Returns: Promise - A Promise with inspect data.
Example

// Create the network
 return ando.engine.createNetwork('mynetwork')

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

Prunes the docker networks.

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

Returns: Promise - A Promise with teh status
Example

// Prune the networks
 return lando.engine.pruneNetworks();

lando.utils.engine.dockerComposify()

Translate a name for use by docker-compose eg strip - and . and

Todo:: Eventually we want to get rid of this since it should only happen once on the appName itself
Since: 3.0.0

lando.utils.engine.getId()

Helper to return a valid id from app data

Since: 3.0.0

lando.utils.engine.normalizer()

We might have datum but we need to wrap in array so Promise.each knows what to do

Since: 3.0.0

lando.utils.engine.moveConfig()

Helper to move config from lando to a mountable directory

Since: 3.0.0

lando.init.get()

Get an init method

Since: 3.0.0

lando.init.add()

Add an init method to the registry

Since: 3.0.0

lando.init.cloneRepo()

Helper to return a performant git clone command

This clones to /tmp and then moves to /app to avoid file sharing performance hits

Since: 3.0.0

lando.init.createKey()

Helper to return a create key command

Since: 3.0.0

lando.init.run()

Run a command during the init process

Since: 3.0.0

lando.init.kill()

Helper to kill any running util processes

Since: 3.0.0

lando.init.build()

The core init method

Since: 3.0.0

lando.init.yaml()

Helper to spit out a .lando.yml file

Since: 3.0.0

lando.recipes.get()

Get a recipe

Since: 3.0.0

lando.recipes.add()

Add a recipe to the registry

Since: 3.0.0

lando.recipes.build()

The core recipe builder

Since: 3.0.0

lando.recipes.webroot()

Helper to let us know whether this app requires a webroot question or not

Since: 3.0.0

lando.recipes.name()

Helper to let us know whether this app requires a name question or not

Since: 3.0.0

lando.services.add()

Add a service to the registry

Since: 3.0.0

lando.services.info()

Delegator to gather info about a service for display to the user

Since: 3.0.0

lando.services.build()

The core service builder

Since: 3.0.0

lando.services.healthcheck()

Does a healthcheck on a service

Since: 3.0.0

lando.utils.services.filterBuildSteps()

Return an object of build steps

Since: 3.0.0

lando.utils.services.setEntrypoint()

Set the entrypoint with a local script

Since: 3.0.0

lando.utils.services.buildVolume()

Helper to build a volumes

Note:: This seems weird, maybe written before we have more generic compose merging?
Since: 3.0.0

lando.utils.services.addConfig()

Helper function to inject config

Since: 3.0.0

lando.utils.services.addScript()

Helper function to inject utility scripts

Since: 3.0.0

lando.tooling.build()

The tooling command builder

Since: 3.0.0

"pre_bootstrap"

Event that allows other things to augment the lando global config.

This is useful so plugins can add additional config settings to the global config.

NOTE: This might only be available in core plugins

Since: 3.0.0
Properties

Name Type Description
config Object The global Lando config

Example

// Add engine settings to the config
lando.events.on('pre-bootstrap', function(config) {

  // Get the docker config
  var engineConfig = daemon.getEngineConfig();

  // Add engine host to the config
  config.engineHost = engineConfig.host;

});

"post_bootstrap"

Event that allows other things to augment the lando object.

This is useful so plugins can add additional modules to lando before the bootstrap is completed.

Since: 3.0.0
Properties

Name Type Description
lando Object The Lando object

Example

// Add the services module to lando
lando.events.on('post-bootstrap', function(lando) {
  lando.services = require('./services')(lando);
});

"task_CMD_answers"

Event that allows altering of argv or inquirer before interactive prompts are run

task-CMD-answers

Since: 3.0.0
Properties

Name Type Description
answers Object argv and inquirer questions

"task_CMD_run"

Event that allows final altering of answers.

You will want to replace CMD with the actual task name eg task-start-run.

Since: 3.0.0
Properties

Name Type Description
answers Object object

"pre_instantiate_app"

Event that allows altering of the config before it is used to instantiate an app object.

Note that this is a global event so it is invoked with lando.events.on not app.events.on See example below:

Since: 3.0.0
Properties

Name Type Description
config Object The config from the app's .lando.yml

Example

// Add in some extra default config to our app, set it to run first
lando.events.on('pre-instantiate-app', 1, function(config) {

  // Add a process env object, this is to inject ENV into the process
  // running the app task so we cna use $ENVARS in our docker compose
  // files
  config.dialedToInfinity = true;

});

"post_instantiate_app"

Event that allows altering of the app object right after it is instantiated.

Note that this is a global event so it is invoked with lando.events.on not app.events.on See example below:

Since: 3.0.0
Properties

Name Type Description
config object The user's app config.

Example

// Add some extra app properties to all apps
lando.events.on('post-instantiate-app', 1, function(app) {

  // Add in some global container envvars
  app.env.LANDO = 'ON';
  app.env.LANDO_HOST_OS = lando.config.os.platform;
  app.env.LANDO_HOST_UID = lando.config.engineId;
  app.env.LANDO_HOST_GID = lando.config.engineGid;

});

"app_ready"

Event that allows altering of the app object right after it has been full instantiated and all its plugins have been loaded.

The difference between this event and post-instantiate-app is that at this point the event has been handed off from the global lando.events.on context to the app.events.on context. This means that post-instantiate-app will run for ALL apps that need to be instantiated while app-ready will run on an app to app basis.

Since: 3.0.0
Example

// Add logging to report on our apps properties after its full dialed
app.events.on('app-ready', function() {

  // Log
  lando.log.verbose('App %s has global env.', app.name, app.env);
  lando.log.verbose('App %s has global labels.', app.name, app.labels);
  lando.log.verbose('App %s adds process env.', app.name, app.processEnv);

});

"pre_info"

Event that allows other things to add useful metadata to the apps services.

Its helpful to use this event to add in information for the end user such as how to access their services, where their code exsts or relevant credential info.

Since: 3.0.0
Example

// Add urls to the app
app.events.on('pre-info', function() {
  return getUrls(app);
});

"post_info"

Event that allows other things to add useful metadata to the apps services.

Its helpful to use this event to add in information for the end user such as how to access their services, where their code exsts or relevant credential info.

Since: 3.0.0

"pre_uninstall"

Event that runs before an app is uninstalled.

This is useful if you want to add or remove parts of the uninstall process. For example, it might be nice to persist a container whose data you do not want to replace in a rebuild and that cannot persist easily with a volume.

Since: 3.0.0
Example

// Do not uninstall the solr service
app.events.on('pre-uninstall', function() {
  delete app.services.solr;
});

"post_uninstall"

Event that runs after an app is uninstalled.

This is useful if you want to do some additional cleanup steps after an app is uninstalled such as invalidating any cached data.

Since: 3.0.0
Example

// Make sure we remove our build cache
app.events.on('post-uninstall', function() {
  lando.cache.remove(app.name + '.last_build');
});

"pre_start"

Event that runs before an app starts up.

This is useful if you want to start up any support services before an app stars.

Since: 3.0.0
Example

// Start up a DNS server before our app starts
app.events.on('pre-start', function() {
  return lando.engine.start(dnsServer);
});

"post_start"

Event that runs after an app is started.

This is useful if you want to perform additional operations after an app starts such as running additional build commands.

Since: 3.0.0
Example

// Go through each service and run additional build commands as needed
app.events.on('post-start', function() {

  // Start up a build collector
  var build = [];

  // Go through each service
  _.forEach(app.config.services, function(service, name) {

    // If the service has run steps let's loop through and run some commands
    if (!_.isEmpty(service.run)) {

      // Normalize data for loopage
      if (!_.isArray(service.run)) {
        service.run = [service.run];
      }

      // Run each command
      _.forEach(service.run, function(cmd) {

        // Build out the compose object
        var compose = {
          id: [service, name, '1'].join('_'),
            cmd: cmd,
            opts: {
            mode: 'attach'
          }
        };

        // Push to the build
        build.push(compose);

      });

    }

  });

  // Only proceed if build is non-empty
  if (!_.isEmpty(build)) {

   // Get the last build cache key
   var key = app.name + ':last_build';

   // Compute the build hash
   var newHash = lando.node.hasher(app.config.services);

   // If our new hash is different then lets build
   if (lando.cache.get(key) !== newHash) {

     // Set the new hash
     lando.cache.set(key, newHash, {persist:true});

     // Run all our post build steps serially
     return lando.engine.run(build);

   }
  }
});

"pre_stop"

Event that runs before an app stops.

Since: 3.0.0
Example

// Stop a DNS server before our app stops.
app.events.on('pre-stop', function() {
  return lando.engine.stop(dnsServer);
});

"post_stop"

Event that runs after an app stop.

Since: 3.0.0
Example

// Stop a DNS server after our app stops.
app.events.on('post-stop', function() {
  return lando.engine.stop(dnsServer);
});

"pre_destroy"

Event that runs before an app is destroyed.

Since: 3.0.0
Example

// Make sure the proxy is down before we destroy
app.events.on('pre-destroy', function() {
  if (fs.existsSync(proxyFile)) {
    return lando.engine.stop(getProxy(proxyFile));
  }
});

"post_destroy"

Event that runs after an app is destroyed.

Since: 3.0.0
Example

// Make sure the proxy is up brought back up after we destroy
app.events.on('post-destroy', function() {
  return startProxy();
});

"pre_rebuild"

Event that runs before an app is rebuilt.

Since: 3.0.0
Example

// Do something
app.events.on('post-rebuild', function() {
  // Do something
});

"post_rebuild"

Event that runs after an app is rebuilt.

Since: 3.0.0
Example

// Do something
app.events.on('post-rebuild', function() {
  // Do something
});

"pre_engine_up"

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

Since: 3.0.0

"post_engine_up"

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

Since: 3.0.0

"pre_engine_down"

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

Since: 3.0.0

"post_engine_down"

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

Since: 3.0.0

"pre_engine_start"

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

Since: 3.0.0

"post_engine_start"

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

Since: 3.0.0

"pre_engine_run"

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

Since: 3.0.0

"post_engine_run"

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

Since: 3.0.0

"pre_engine_stop"

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

Since: 3.0.0

"post_engine_stop"

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

Since: 3.0.0

"pre_engine_destroy"

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

Since: 3.0.0

"post_engine_destroy"

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

Since: 3.0.0

"pre_engine_build"

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

Since: 3.0.0

"post_engine_build"

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

Since: 3.0.0

results matching ""

    No results matching ""