lando([options]) ⇒ 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 new 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
const bootstrap = require('./lib/bootstrap');
const options = {
  logLevelConsole: LOGLEVELCONSOLE,
  userConfRoot: USERCONFROOT,
  envPrefix: ENVPREFIX,
  configSources: configSources,
  pluginDirs: [USERCONFROOT],
  mode: 'cli'
};

// Initialize Lando with some options
bootstrap(options).then(lando => cli.init(lando));

"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', config => {
  const engineConfig = daemon.getEngineConfig();
  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', lando => {
  lando.services = require('./services')(lando);
});

"task_CMD_answers"

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

You will want to replace CMD with the actual task name eg task-start-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 before the task runs

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

lando.node._()

Get lodash

Since: 3.0.0
Example

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

lando.node.chalk()

Get chalk

Since: 3.0.0
Example

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

lando.node.fs()

Get fs-extra

Since: 3.0.0
Example

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

lando.node.hasher()

Get object-hash

Since: 3.0.0
Example

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

lando.node.ip()

Get ip utils

Since: 3.0.0
Example

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

lando.node.jsonfile()

Get jsonfile

Since: 3.0.0
Example

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

lando.node.axios()

Get axios

Since: 3.0.0
Example

// Get the axios module
const rest = lando.node.axios;

// Get it via the legacy hostname
const rest = lando.node.rest

lando.node.semver()

Get semver

Since: 3.0.0
Example

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

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

// And then retry 25 times until we've connected, increase delay between retries by 1 second
Promise.retry(someFunction, {max: 25, backoff: 1000});

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
const task = lando.tasks.tasks;

lando.Promise()

Extends bluebird so that our promises have some retry functionality.

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

Note that bluebird currently wants you to use scoped prototypes to extend it rather than the normal extend syntax so that is why this is using the "old" way

See

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
const 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.cli.argv() ⇒ Object

Returns a parsed array of CLI arguments and options

Since: 3.0.0
Todo

  • [ ] make this static and then fix all call sites

Returns: Object - Yarg parsed options
Example

const argv = lando.cli.argv();

lando.cli.checkPerms()

Checks to see if lando is running with sudo. If it is it will exit the process with a stern warning

Since: 3.0.0
Example

lando.cli.checkPerms()

lando.cli.largv([args]) ⇒ Object

Returns a parsed object of all global options.

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

Since: 3.0.0

Param Type Default Description
[args] Object process.argv.slice(2) Options

Returns: Object - Yarg parsed options
Example

const largv = lando.cli.largv();

lando.cli.defaultConfig() ⇒ Object

Returns a config object with some good default settings for bootstrapping lando as a command line interface

Since: 3.0.0
Returns: Object - Config that can be used in a Lando CLI bootstrap
Example

const config = lando.cli.defaultConfig();
// Kick off our bootstrap
bootstrap(config).then(lando => console.log(lando));

lando.cli.makeArt([header], [opts]) ⇒ Object

Returns some cli "art"

Since: 3.0.0

Param Type Default Description
[header] String 'start' The type of header you want to get
[opts] Object Padding options
[opts.paddingTop] Object 1 Lines to pad on top of the art
[opts.paddingBottom] Object 1 Lines to pad below the art

Returns: Object - Yarg parsed options
Example

console.log(lando.cli.makeArt('init', {paddingTop: 100});

lando.cli.makeTable([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
const table = new lando.cli.makeTable();

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

See

Since: 3.0.0

Param Type Default Description
task Object A Lando task object (@see add for definition)
[events] Object new AsyncEvents() An AsyncEvents

Returns: Object - A yargs command object
Example

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

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

Uses _.mergeWith to concat arrays, this helps replicate how Docker Compose merges its things

See: https://lodash.com/docs#mergeWith
Since: 3.0.0

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

Returns: Object - The new object
Example

// Take an object and write a docker compose file
const 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.error.handle() ⇒ Object

Returns the lando options

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

Since: 3.0.0
Todo

  • [ ] make this static and then fix all call sites

Returns: Object - Yarg parsed options
Example

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

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, 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', () => {
  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 %s', 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, [injected]) ⇒ 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.
[injected] Object An object to inject into the plugin.

Returns: Promise - A Promise.
Example

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

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, 404] 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

See

Since: 3.0.0

Param Type Default Description
cmd Array The command to run as elements in an array.
[opts] Object Options to help determine how the exec is run.
[opts.mode] Boolean 'exec' The mode to run in
[opts.detached] Boolean false Whether we are running in detached mode or not (deprecated)
[opts.app] Boolean {} A Lando app object
[opts.cwd] Boolean process.cwd() The directory to run the command from

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(err => {
  lando.log.error(err);
})

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

lando.shell.escSpaces(s, platform) ⇒ String

Escapes any spaces in a command.

Since: 3.0.0

Param Type Description
s Array \ String A command as elements of an Array or a String.
platform String Specify a platform to escape for

Returns: String - The space escaped cmd.
Example

// Escape the spaces in the cmd
const 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.

Returns: String - The escaped cmd.
Example

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

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

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 | null - The path to the command or null.
Example

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

lando.tasks.add(name, task) ⇒ Array

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.

Returns: Array - The task object
Example

// Define a task
const 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: 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?
const updateAvailable = lando.updates.updateAvailable('1.0.0', '1.0.1');

lando.updates.fetch(data) ⇒ Boolean

Determines whether we need to fetch updatest or not

Since: 3.0.0

Param Type Description
data Object Cached update data

Returns: Boolean - Whether we need to ping GitHub for new data or not

lando.updates.refresh(version) ⇒ Object

Get latest version info from github

Since: 3.0.0

Param Type Description
version String Lando version to use as a fallback

Returns: Object - Update data

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.
const 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.
const 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
const thing = lando.yaml.load('/tmp/myfile.yml');

lando.yaml.dump(file, data) ⇒ String

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: String - Flename

results matching ""

    No results matching ""