Footprintless::Overlay

- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
- ENTITIES
- CONSTRUCTORS
  - new($entity, $coordinate, %options)
- METHODS
  - clean()
  - initialize()
  - update()
- AUTHOR
- COPYRIGHT AND LICENSE
- SEE ALSO

# NAME

Footprintless::Overlay - An overlay manager

# VERSION

version 1.01

# SYNOPSIS

        # Standard way of getting an overlay
        use Footprintless;
        my $overlay = Footprintless->new()->overlay('overlay');

        $overlay->clean();

        $overlay->initialize();

        $overlay->update();

# DESCRIPTION

Overlays are a combination of a directory of static files and a directory of templated files that will be merged to an output directory. This is implemented in Template::Overlay. If the overlay entity contains a `deployment_coordinate` entity, then any calls to `initialize` will also create a Footprintless::Deployment for the indicated entity and call `deploy` on it.

# ENTITIES

A simple overlay:

        overlay => {
            base_dir => "/home/me/foo/base",
            clean => [
                "/opt/tomcat/"
            ],
            hostname => 'localhost',
            key => 'T',
            os => 'linux',
            template_dir => "/home/me/foo/template",
            to_dir => '/opt/foo/tomcat'
        }

A more complex example:

        foo => {
            deployment => {
                'Config::Entities::inherit' => ['hostname', 'sudo_username'],
                clean => [
                    '/opt/foo/tomcat/conf/Catalina/localhost/',
                    '/opt/foo/tomcat/temp/',
                    '/opt/foo/tomcat/webapps/',
                    '/opt/foo/tomcat/work/'
                ],
                resources => {
                    bar => '/home/me/.m2/repository/com/pastdev/bar/1.2/bar-1.2.war',
                    baz => {
                        coordinate => 'com.pastdev:baz:war:1.0',
                        'as' => 'foo.war',
                        type => 'maven'
                    }
                },
                to_dir => '/opt/foo/tomcat/webapps'
            },
            hostname => 'test.pastdev.com',
            overlay => {
                'Config::Entities::inherit' => ['hostname', 'sudo_username'],
                base_dir => '/home/me/foo/base',
                clean => [
                    '/opt/foo/tomcat/'
                ],
                deployment_coordinate => 'foo.deployment',
                key => 'T',
                os => 'linux',
                resolver_coordinate => 'foo',
                template_dir => '/home/me/foo/template',
                to_dir => '/opt/foo/tomcat'
            },
            sudo_username => 'developer',
            tomcat => {
                'Config::Entities::inherit' => ['hostname', 'sudo_username'],
                catalina_base => '/opt/foo/tomcat',
                http => {
                    port => 20080
                },
                service => {
                    action => {
                        'kill' => { command_args => 'stop -force' },
                        'status' => { use_pid => 1 }
                    },
                    command => '/opt/foo/tomcat/bin/catalina.sh',
                    pid_file => '/opt/foo/tomcat/bin/.catalina.pid',
                },
                shutdown => {
                    port => 8505,
                    password => $properties->{'foo.tomcat.shutdown.password'},
                },
                trust_store => {
                    'Config::Entities::inherit' => ['hostname', 'sudo_username'],
                    file => '/opt/foo/tomcat/certs/truststore.jks',
                    include_java_home_cacerts => 1,
                    password => $properties->{'foo.tomcat.trust_store.password'},
                }
            }
        }

# CONSTRUCTORS

## new($entity, $coordinate, %options)

Constructs a new overlay configured by `$entities` at `$coordinate`. The supported options are:

agent

  If no `resource_manager` is provided, then this value is used when constructing the default provider(s) for the default resource manager.

command_options_factory

  The command options factory to use. Defaults to an instance of Footprintless::CommandOptionsFactory using the `localhost` instance of this object.

command_runner

  The command runner to use. Defaults to an instance of Footprintless::CommandRunner::IPCRun.

localhost

  The localhost alias resolver to use. Defaults to an instance of Footprintless::Localhost configured with `load_all()`.

resource_manager

  The resource manager to use. Only used by the deployment if any is specified. Defaults to an instance of Footprintless::ResourceManager configured to use a Footprintless::MavenProvider if Maven::Agent is available, and a Footprintless::UrlProvider in that order.

# METHODS

## clean()

Cleans the overlay. Each path in the `clean` entity, will be removed from the destination. If the path ends in a `/`, then after being removed, the directory will be recreated.

## initialize()

Will call `clean`, then `overlay` on an instance of Template::Overlay configured to this entity. Then, if this entity contains a `deployment_coordinate`, an instance of Footprintless::Deployment will be created for the indicated entity, and its `deploy` method will be called.

## update()

Will overlay ONLY the templated files. It will not `clean`, copy any files from `base_dir`, or `deploy` like `initialize` does.

# AUTHOR

Lucas Theisen <lucastheisen@pastdev.com>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Lucas Theisen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

# SEE ALSO

Please see those modules/websites for more information related to this module.

- Footprintless
- Config::Entities
- Footprintless
- Footprintless::CommandOptionsFactory
- Footprintless::CommandRunner
- Footprintless::Deployment
- Footprintless::Localhost
- Footprintless::ResourceManager