github.com/cloud-foundations/dominator@v0.0.0-20221004181915-6e4fee580046/cmd/imaginator/README.md (about)

     1  # imaginator
     2  The *imaginator* daemon builds OS and OS+application images which are specified
     3  by *[image manifests](../../user-guide/image-manifest.md)*.
     4  
     5  ## Status page
     6  The *imaginator* provides a web interface on port `6975` which shows a status
     7  page, links to built-in dashboards and access to performance metrics and logs.
     8  If *imaginator* is running on host `myhost` then the URL of the main status page
     9  is `http://myhost:6975/`. An RPC over HTTP interface is also provided over the
    10  same port.
    11  
    12  
    13  ## Startup
    14  *Imaginator* is started at boot time, usually by one of the provided
    15  [init scripts](../../init.d/). The *imaginator* process is baby-sat by the init
    16  script; if the process dies the init script will re-start it. It may be stopped
    17  with the command:
    18  
    19  ```
    20  service imaginator stop
    21  ```
    22  
    23  which also kills the baby-sitting init script. It may be started with the
    24  comand:
    25  
    26  ```
    27  service imaginator start
    28  ```
    29  
    30  There are many command-line flags which may change the behaviour of
    31  *imaginator*, generally with defaults which should be adequate for most
    32  deployments. Built-in help is available with the command:
    33  
    34  ```
    35  imaginator -h
    36  ```
    37  
    38  ### Key configuration parameters
    39  The init script reads configuration parameters from the
    40  `/etc/default/imaginator` file. The following is the minimum likely set of
    41  parameters that will need to be configured.
    42  
    43  The `CONFIGURATION_URL` variable specifies the main configuration URL, which may
    44  be a local file or a HTTP URL. It is recommended to specify a HTTP URL which
    45  references a file in a Git repository.
    46  
    47  The `IMAGE_SERVER_HOSTNAME` variable specifies the hostname where the
    48  *[imageserver](../imageserver/README.md)* is running. This hostname must be
    49  resolvable by the *imaginator*.
    50  
    51  The `VARIABLES_FILE` variable specifies an optional filename from which to read
    52  special variables which may be used for variable expansion. These are typically
    53  used to store secrets for accessing Git repositories which require
    54  authentication. Each line should contain a single `NAME=Value` entry.
    55  
    56  ## Security
    57  RPC access is restricted using TLS client authentication. *Imaginator* expects
    58  a root certificate in the file `/etc/ssl/CA.pem` which it trusts to sign
    59  certificates which grant access. It also requires a certificate and key which
    60  grant it the ability to add and get images and objects from the *imageserver*.
    61  These should be in the files `/etc/ssl/imaginator/cert.pem` and
    62  `/etc/ssl/imaginator/key.pem`, respectively.
    63  
    64  ## Control
    65  The *[builder-tool](../builder-tool/README.md)* utility may be used to request
    66  the *imaginator* to build an image.
    67  
    68  ## Main Configuration URL
    69  The main configuration URL points to a JSON encoded file that describes all the
    70  *image streams* and how to build them. The top-level JSON object should contain
    71  the following fields:
    72  - `BootstrapStreams`: a table of *bootstrap image* stream names and their
    73    		      respective configurations
    74  - `ImageStreamsToAutoRebuild`: an array of *image stream* names that should be
    75    			       rebuilt periodically, in addition to *bootstrap
    76  			       streams* that are always rebuilt automatically
    77  - `ImageStreamsUrl`: the URL of a configuration file containing a list of all
    78    		     the user-defined *image streams*
    79  - `PackagerTypes`: a table of *packager type* names (i.e. `deb` and `rpm`) and
    80    		   their respective configurations
    81  
    82  A [sample configuration file](conf.json) is provided which may be modified to
    83  suit your environment. This is a fully working configuration and only requires
    84  modification of the location of the package repositories and the
    85  `ImageStreamsUrl` for your custom *image streams*.
    86  
    87  ### Bootstrap Streams configuration
    88  Each *bootstrap stream* is configured by a JSON object with the following
    89  fields:
    90  - `BootstrapCommand`: an array of strings containing the bootstrap script to run
    91    		      to generate the image contents (typically `debootstrap`
    92  		      and `yumbootstrap`). The `$dir` variable expands to the
    93  		      root directory of the image to build
    94  - `FilterLines`: an array of regular expressions matching files which should not
    95    		 be included in the image
    96  - `PackagerType`: the name of the packager type to use
    97  
    98  ### Image Streams URL
    99  This is a JSON encoded configuration file listing all the user-defined *image
   100  streams*. It contains a top-level `Streams` field which in turn contains a table
   101  of *image stream* names and their respective configurations. The configuration
   102  for an *image stream* is a JSON object with the following fields:
   103  - `ManifestUrl`: the URL of a Git repository containing the
   104    		 *[image manifest](../../user-guide/image-manifest.md)* for the
   105  		 image. The special URL scheme `dir` points to a local directory
   106  		 tree. Variables specified in the `VARIABLES_FILE` will be
   107  		 expanded here
   108  - `ManifestDirectory`: the directory within the Git repository containing the
   109    		 *[image manifest](../../user-guide/image-manifest.md)* for the
   110  		 image. If unspecified, the top-level directory in the
   111  		 repository is used. The `$IMAGE_STREAM` variable expands to the
   112  		 name of the *image stream*
   113  
   114  An [example configuration file](streams.json) is provided. Note the use of
   115  variables in different places.
   116  
   117  ### Packager Types
   118  Each *packager type* is configured by a JSON object with the following fields:
   119  - `CleanCommand`: an array of strings containing the command to run when
   120    		  cleaning up packager debris
   121  - `InstallCommand`: an array of strings containing the command to run when
   122    		    installing packages. The name of the package to be installed
   123  		    is appended to the command-line
   124  - `ListCommand`: a JSON object defining how to list packages which are
   125    		 installed. This JSON object contains the following fields:
   126    - `ArgList`: an array of strings containing the command to run when listing
   127      	       installed packages
   128    - `SizeMultiplier`: an optional multiplier to apply to the output of the
   129      		      listing command to convert the size result to Bytes
   130  - `UpdateCommand`: an array of strings containing the command to run when
   131    		   updating the package database
   132  - `UpgradeCommand`: an array of strings containing the command to run when
   133    		    upgrading the already installed packages
   134  - `Verbatim`: an array of strings containing commands to run before any of the
   135    	      above defined commands
   136  
   137  These parameters are used to generate a `/bin/generic-packager` script which is
   138  used as an interface to the native OS packaging tools.