github.com/Cloud-Foundations/Dominator@v0.3.4/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 defines the 71 following fields: 72 - `BindMounts`: a list of directories that will be bind-mounted into the build 73 environments 74 - `BootstrapStreams`: a table of *bootstrap image* stream names and their 75 respective configurations 76 - `ImageStreamsCheckInterval`: the interval between checks for updated image 77 streams 78 - `ImageStreamsToAutoRebuild`: an array of *image stream* names that should be 79 rebuilt periodically, in addition to *bootstrap 80 streams* that are always rebuilt automatically 81 - `ImageStreamsUrl`: the URL of a configuration file containing a list of all 82 the user-defined *image streams* 83 - `MtimesCopyFilterLines`: an array of regular expressions matching files which 84 should be excluded from copying mtimes from older 85 images (when only the mtime is different). Python 86 files should probably be specified here 87 - `PackagerTypes`: a table of *packager type* names (i.e. `deb` and `rpm`) and 88 their respective configurations 89 - `RelationshipsQuickLinks`: a list of `Name`,`URL` tuples to display on the 90 image streams relationships dashboard. Useful for 91 customisation 92 93 A [sample configuration file](conf.json) is provided which may be modified to 94 suit your environment. This is a fully working configuration and only requires 95 modification of the location of the package repositories and the 96 `ImageStreamsUrl` for your custom *image streams*. 97 98 ### Bootstrap Streams configuration 99 Each *bootstrap stream* is configured by a JSON object with the following 100 fields: 101 - `BootstrapCommand`: an array of strings containing the bootstrap script to run 102 to generate the image contents (typically `debootstrap` 103 and `yumbootstrap`). The `$dir` variable expands to the 104 root directory of the image to build 105 - `FilterLines`: an array of regular expressions matching files which should not 106 be included in the image 107 - `ImageFilterUrl`: a URL from which a filter lines can be read. The filter will 108 be attached to the image 109 - `ImageTagsUrl`: a URL from which JSON-encoded key:value tags can be read. The 110 tags will be attached to the image 111 - `ImageTriggersUrl`: a URL from which JSON-encoded triggers can be read. The 112 triggers will be attached to the image 113 - `PackagerType`: the name of the packager type to use 114 115 ### Image Streams URL 116 This is a JSON encoded configuration file listing all the user-defined *image 117 streams*. It contains a top-level `Streams` field which in turn contains a table 118 of *image stream* names and their respective configurations. The configuration 119 for an *image stream* is a JSON object with the following fields: 120 - `BuilderGroups`: a list of groups. Members of these groups are permitted to 121 build images for this stream 122 - `BuilderUsers`: a list of users who are permitted to build images for this 123 stream 124 - `ManifestUrl`: the URL of a Git repository containing the 125 *[image manifest](../../user-guide/image-manifest.md)* for the 126 image. The special URL scheme `dir` points to a local directory 127 tree. Variables specified in the `VARIABLES_FILE` will be 128 expanded here 129 - `ManifestDirectory`: the directory within the Git repository containing the 130 *[image manifest](../../user-guide/image-manifest.md)* for the 131 image. If unspecified, the top-level directory in the 132 repository is used. The `$IMAGE_STREAM` variable expands to the 133 name of the *image stream* 134 - `Variables`: key:value variables which may be referred to in the `manifest` 135 file. The values undergo variable expansion 136 137 An [example configuration file](streams.json) is provided. Note the use of 138 variables in different places. 139 140 ### Packager Types 141 Each *packager type* is configured by a JSON object with the following fields: 142 - `CleanCommand`: an array of strings containing the command to run when 143 cleaning up packager debris 144 - `InstallCommand`: an array of strings containing the command to run when 145 installing packages. The name of the package to be installed 146 is appended to the command-line 147 - `ListCommand`: a JSON object defining how to list packages which are 148 installed. This JSON object contains the following fields: 149 - `ArgList`: an array of strings containing the command to run when listing 150 installed packages 151 - `SizeMultiplier`: an optional multiplier to apply to the output of the 152 listing command to convert the size result to Bytes 153 - `UpdateCommand`: an array of strings containing the command to run when 154 updating the package database 155 - `UpgradeCommand`: an array of strings containing the command to run when 156 upgrading the already installed packages 157 - `Verbatim`: an array of strings containing commands to run before any of the 158 above defined commands 159 160 These parameters are used to generate a `/bin/generic-packager` script which is 161 used as an interface to the native OS packaging tools.