Docker Deployment

LogScale is available a non-core Docker image, that includes Kafka in addition to LogScale. This means that you can start an instance without a complicated installation procedure.

Important

The following section describes running LogScale using the core Docker image, which is suitable for running LogScale locally for development or testing, but is not a recommended or supported model for production deployments.

For production deployments, see Installing LogScale on Kubernetes. For more information on the reference architecture for a Kubernetes deployment, see LogScale Kubernetes Reference Architecture.

Install Docker

The first step to install LogScale using Docker is to install Docker on the machine where you want to run Docker with LogScale. You can Download Docker from their site or by using a package installation program like yum or apt-get.

One you have Docker installed, you'll need to create a LogScale configuration file on the host machine. We recommend using the Launcher Script to configure LogScale. This will automatically set configuration parameters according to the available infrastructure environment.

Note

Docker only loads the environment file when the container is initially created. If you make changes to the settings in your environment file, restarting the container won't work. You'll need to execute docker rm with the container name, and then execute docker run for the changes to take effect.

Now, make two directories on the host machine: one to store data for LogScale in general and one for Kafka data. And then pull the latest LogScale image by executing the following at the command-line:

shell
$ docker pull humio/humio

Separate mount points help isolate Kafka from the other services. Kafka is notorious for consuming large amounts of disk space, so it's important to protect the other services from running out of disk space by using a separate volume in production deployments. Make sure all volumes are being appropriately monitored as well. If your installation does run out of disk space and gets into a bad state, you can find recovery instructions in Switching Kafka.

For information on updating LogScale, see Updating LogScale.

Starting Docker with LogScale

With everything downloaded and in place, you're ready to run the LogScale Docker image as a container. LogScale provides a core container includes only LogScale and relies on an external Kafka service. See Basic Configuration and Configuration Parameters for more information on configuring LogScale. preconfigured Do this by executing something like the following from the command-line:

shell
$ docker run -v $HOST_DATA_DIR:/data  \
   -v $PATH_TO_READONLY_FILES:/etc/humio:ro  \
   --net=host \
   --name=humio \
   --ulimit="nofile=8192:8192"  \
   --stop-timeout 300 \
   --env-file=$PATH_TO_CONFIG_FILE humio/humio

To customise the configuration:

  • Replace $HOST_DATA_DIR with the path to the mounts/data directory for the data on the host machine.

  • Replace $PATH_TO_CONFIG_FILE with the path of the configuration file you created

  • The directory $PATH_TO_READONLY_FILES provides a place to put files that LogScale needs at runtime, such as certificates for SAML authentication.

At this point, LogScale should be running. Using a web browser, navigate to http://localhost:8080 to open the LogScale user interface. However, there are a first of the settings above that you might adjust further based on how you're using LogScale with Docker.

Some additional considerations:

  • If you're running the LogScale containers with a host that's using SElinux in enforcing mode, the container has to be started with the --privileged flag set.

  • In the example above, the LogScale container was started with full access to the network of the host machine (--net=host). Another possibility is to forward explicit ports: -p 8080:8080. By default LogScale only uses port 8080.

  • On a macOS machine, there can be problems with using the host network (i.e., --net=host). If that happens, use -p 8080:8080 to forward port 8080 on the host network to the Docker container.

  • You may also need to allow enough memory for the virtual machine running Docker on Mac. Open the Docker app, go to preferences, and specify 4GB.

Running LogScale as a System Service

The Docker container can be started as a service using the Docker run reference.

To ensure LogScale restarts, add --detach and --restart=always to the above Docker run:

shell
$ docker run ... --detach --restart=always