docker/README.asciidoc

   1 [[official-check_mk-raw-edition-container]]
   2 Official Check_MK Raw Edition Container
   3 ---------------------------------------
   4
   5 This is the official container of Check_MK. Check_MK is a leading tool
   6 for Infrastructure & Application Monitoring. Simple configuration,
   7 scaleable, flexible. Open Source and Enterprise.
   8
   9 Features of these containers:
  10
  11 * Each container manages a single site
  12 * Containers of all Check_MK Editions can be built
  13 * No internet connection is needed during container creation / update
  14 * No special container privilege level required
  15 * Clean update procedure
  16
  17 [[quick-start]]
  18 Quick start
  19 ~~~~~~~~~~~
  20
  21 You can start a Check_MK container like this:
  22
  23 ....
  24 docker container run -dit -p 8080:5000 -v /omd/sites --name monitoring -v /etc/localtime:/etc/localtime --restart always checkmk/check-mk-raw:1.5.0p5
  25 ....
  26
  27 The Check_MK GUI should now be reachable via
  28 `http://localhost:8080/cmk/check_mk/`.
  29
  30 The initial password of the initial administrative account `cmkadmin`
  31 will be written to the container logs (see
  32 `docker container logs monitoring`). You can customize this during
  33 container creation if you like, see below.
  34
  35 Details about the arguments used above:
  36
  37 [cols="20%,80%",options="header",]
  38 |=======================================================================
  39
  40 |Option
  41 |Description
  42
  43 |`-p 8080:5000`
  44 |The sites web server listens on port 5000 by default. With this
  45 example it is opened at port 8080 of the node. You may also use
  46 port 80 here in case you don't have another process listening on
  47 it. For more flexible options or HTTPS have a look below
  48
  49 |`--tmpfs /omd/sites/cmk/tmp`
  50 |For best performance you should mount a
  51 tmpfs at the sites `tmp` directory. In case you rename your site ID (see
  52 below for details), you will have to change this path. This option seems
  53 to be unstable and not working for some distributions. Therefore it is not included
  54 in our example command, although we recommend it for best performance.
  55
  56 |`-v /omd/sites`
  57 |This makes all site data be persisted even when the container is
  58 destroyed. In case you don't use this you will loose all you
  59 configuration and monitoring data.
  60
  61 |`--name monitoring`
  62 |The name of the container. It must be unique per docker node. All examples below use
  63 this name. In case you change this you will have to use your custom name
  64 e.g. during update.
  65
  66 |`-v /etc/localtime:/etc/localtime`
  67 | Make the container use the same local time (timezone) config as your docker node.
  68
  69 |`--restart always`
  70 | Always restart the container if it stops.
  71
  72 |=======================================================================
  73
  74 [[use-packages-from-our-website]]
  75 Use packages from our Website
  76 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  77
  78 You may want to use the officially released images from your website,
  79 which you can find on the download page of each version as of version
  80 1.5.0p5.
  81
  82 Download the file to your docker node and execute the load command:
  83
  84 ....
  85 docker load -i ~/Downloads/check-mk-enterprise-docker-1.5.0p5.tar.gz
  86 ....
  87
  88 After a successful import you can start creating containers using the
  89 image `checkmk/check-mk-enterprise:1.5.0p5`.
  90
  91 [[listen-on-http-https-standard-ports]]
  92 Listen on HTTP / HTTPS standard ports
  93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94
  95 If you have a simple setup where Check_MK is the only web server on a
  96 node you may use `-p 80:5000` instead of `-p 8080:5000`.
  97
  98 In most cases, where you have multiple web server running in different
  99 containers you should use a reverse proxy which listens on port 80 and
 100 distributes the request to the different containers. This can be done
 101 using a nginx container.
 102
 103 This is also the recommended setup in case you want to serve your GUI
 104 via HTTPS. The HTTPS termination should be done by the reverse proxy
 105 container while the Check_MK containers still speak plain HTTP to the
 106 reverse proxy.
 107
 108 [[set-initial-cmkadmin-password]]
 109 Set initial cmkadmin password
 110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 111
 112 During container creation you may add `-e CMK_PASSWORD='my#secret'` to
 113 the command line to set the initial password of `cmkadmin` to
 114 `my#secret`.
 115
 116 [[customizing-the-check_mk-site-id]]
 117 Customizing the Check_MK site ID
 118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 119
 120 The container normally uses the site ID `cmk`. If you create a
 121 distributed setup you need to use different site IDs for the involved
 122 Check_MK sites. You may also set custom site IDs for other reasons. Add
 123 `-e CMK_SITE_ID=mysite` to change the site ID.
 124
 125 [[sending-mail-notifications]]
 126 Sending mail notifications
 127 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 128
 129 In most cases you want the Check_MK server to send mail notifications.
 130 To make this possible you need to point the containers local MTA to your
 131 mail relay. Add `-e MAIL_RELAY_HOST='mailrelay.mydomain.com'` to the
 132 command line to do so.
 133
 134 In some cases the mail relay only accepts mails from correctly named
 135 hosts. In this case you may also have to set the containers local host
 136 name using the option `--hostname 'monitoring.mydomain.com'`.
 137
 138 If your mail relay requires you to customize the containers mailer
 139 configuration, you may have to mount a postfix configuration file or
 140 directory into the container.
 141
 142 The container is using postfix as local MTA which takes care about
 143 spooling in case the mail relay is currently not reachable.
 144
 145 [[enabling-livestatus-via-tcp]]
 146 Enabling Livestatus via TCP
 147 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 148
 149 When you plan to use your site in a distributed setup or want to access
 150 Livestatus via network for some other reason you can enable it during
 151 container creation by adding `-e CMK_LIVESTATUS_TCP=on -p 6557:6557` to
 152 the create or run command. It will configure the site to open the TCP
 153 port 6557 and tell the host to share the containers port 6557 with the
 154 network.
 155
 156 [[event-console]]
 157 Event Console
 158 ~~~~~~~~~~~~~
 159
 160 The Event Console is enabled by default in the container. In case you
 161 want it to listen for incoming syslog messages or SNMP traps on the
 162 network you will first have to make the Event Console open the network
 163 ports using `omd config`. The you have to forward the hosts port to the
 164 container. Use `-p 162:162/udp` to forward SNMP traps, `-p 514:514/udp`
 165 for syslog UDP and `-p 514:514/tcp` for syslog TCP.
 166
 167 [[interactive-shell-access]]
 168 Interactive shell access
 169 ~~~~~~~~~~~~~~~~~~~~~~~~
 170
 171 Most administrative tasks are done as site user. To get a shell execute
 172 this on the docker node:
 173
 174 ....
 175 docker container exec -it -u cmk monitoring bash
 176 ....
 177
 178 In case you need a root shell remove the `-u cmk` argument from the
 179 command above.
 180
 181 [[updating-check_mk]]
 182 Updating Check_MK
 183 ~~~~~~~~~~~~~~~~~
 184
 185 Updating Check_MK in a container is not as straight forward as you might
 186 expect. The main problem is that the sites configuration and local data
 187 need to be updated to the target version while the original version is
 188 still available. This is normally done by using the `omd update`
 189 command.
 190
 191 The procedure works like this:
 192
 193 1.  Create a backup of the current state
 194 2.  Perform the site update using an intermediate container
 195 3.  Replace the old container with a new one
 196
 197 Now let's go through this process in detail:
 198
 199 [[our-starting-point]]
 200 1. Our starting point
 201 ^^^^^^^^^^^^^^^^^^^^^
 202
 203 Assume you have a container running named container. It uses an Check_MK
 204 Enterprise Edition container with version 1.5.0p2. It may have been
 205 created using this command:
 206
 207 ....
 208 docker container run -dit -p 8080:5000 --tmpfs /omd/sites/cmk/tmp -v /omd/sites --name monitoring -v /etc/localtime:/etc/localtime checkmk/check-mk-enterprise:1.5.0p2
 209 ....
 210
 211 Now you want to update the instance to 1.5.0p3.
 212
 213 [[stop-your-current-container]]
 214 2. Stop your current container
 215 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 216
 217 Before performing the backup stop the current container. If you want to
 218 have less downtime, you may try another approach. We do it like this for
 219 consistency and simplicity.
 220
 221 ....
 222 docker stop monitoring
 223 ....
 224
 225 [[backup-your-current-state]]
 226 2. Backup your current state
 227 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 228
 229 The goal of the update procedure is to update the sites data. As you may
 230 know it is stored on a dedicated docker volume (in case you created the
 231 container with `-v /omd/sites`). This instructs docker to store all data
 232 below this path in a storage area which is independent of the single
 233 container on the node.
 234
 235 For the backup this means it is not enough to backup or snapshot the
 236 container. We need to take a backup of the data volume. This can be done
 237 like this:
 238
 239 ....
 240 docker cp monitoring:/omd/sites - > /path/to/backup.tar
 241 ....
 242
 243 You may have a better backup solution. Use it!
 244
 245 [[update-the-site-using-an-intermediate-container]]
 246 3. Update the site using an intermediate container
 247 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 248
 249 We create the intermediate container to perform the update. It is the
 250 place where we make both, the old and the new version available and
 251 execute `omd update`. The container is created using the new container
 252 version. The container is removed automatically when shutting it down.
 253
 254 ....
 255 docker container run -it --rm --volumes-from monitoring --name monitoring_update checkmk/check-mk-enterprise:1.5.0p3 bash
 256 ....
 257
 258 Now add the origin version to the intermediate container.
 259
 260 ....
 261 docker cp -L monitoring:/omd/versions/default - | docker cp - monitoring_update:/omd/versions
 262 ....
 263
 264 Until now no modification has been made. You could stop the intermediate
 265 container and start the old container again. But now we perform the
 266 `omd update` which will change the sites version.
 267
 268 ....
 269 docker exec -it -u cmk monitoring_update omd update
 270 ....
 271
 272 Once you have finished this step you can stop the intermediate container
 273 `monitoring_update` by terminating the open shell.
 274
 275 [[replace-the-old-container-with-a-new-one]]
 276 4. Replace the old container with a new one
 277 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 278
 279 Move the old container out of the way for the new one:
 280
 281 ....
 282 docker rename monitoring monitoring_old
 283 ....
 284
 285 Now create a new container using the previously updated volume.
 286
 287 ....
 288 docker container run -dit -p 8080:5000 --tmpfs /omd/sites/cmk/tmp --volumes-from monitoring_old --name monitoring checkmk/check-mk-enterprise:1.5.0p3
 289 ....
 290
 291 Have a look at the container logs. It should've been started without
 292 issue:
 293
 294 ....
 295 docker container logs monitoring
 296 ....
 297
 298 [[cleanup]]
 299 5. Cleanup
 300 ^^^^^^^^^^
 301
 302 If everything went fine you can now finalize your update by cleaning up
 303 the old container
 304
 305 ....
 306 docker rm monitoring_old
 307 ....
 308
 309 [[building-your-own-container]]
 310 Building your own container
 311 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 312
 313 Besides the prebuilt containers, which are available through Docker Hub,
 314 you may also create your own container images.
 315
 316 1.  Check out the current Check_MK git
 317 2.  Navigate to the `docker` directory
 318 3.  Imagine you want to build an 1.5.0p3 Enterprise Edition container
 319 image. Do it like this:
 320
 321 ....
 322 docker build \
 323     --build-arg CMK_VERSION=1.5.0p3 \
 324     --build-arg CMK_EDITION=enterprise \
 325     --build-arg CMK_DL_CREDENTIALS='myusername:secretpassword' \
 326     -t mycompany/check-mk-enterprise:1.5.0p3
 327 ....
 328
 329 Doing it like this the build process will download 2 files from our download
 330 server: The Debian stretch package and the GPG public key for verifying the
 331 package signature. To prevent this you may put the files that are needed during
 332 the build into the `docker` directory. For the above call you would have to put
 333 the `check-mk-enterprise-1.5.0p3.stretch_amd64.deb` and `Check_MK-pubkey.gpg`
 334 into this directory.
 335
 336 We'll offer prebuilt images for the Enterprise and Managed Services
 337 Edition in the future. For the moment you'll have to build them on your
 338 own (e.g. using the command above).