:docker-version-tag: bleeding
ifeval::["{prerelease}" == "false"]
:docker-version-tag: {full-display-version}
endif::[]

.Create a project directory for {page-component-title} core and create a `docker-compose.yml` file.
[source, console]
----
mkdir minion
cd minion
vi docker-compose.yml
----

[source, docker-compose.yml]
[subs="verbatim,attributes"]
----
---
version: '3'

services:
  minion:
ifeval::["{page-component-title}" == "Horizon"]
    image: opennms/minion:{full-display-version}
endif::[]
ifeval::["{page-component-title}" == "Meridian"]
    image: opennms/meridian-minion:{full-display-version}
endif::[]
    container_name: minion<1>
    environment:
      TZ: 'America/New_York'<2>
      JAVA_MIN_MEM: 512M<3>
      JAVA_MAX_MEM: 2048M<4>
    command: ["-c"]
    volumes:
      - ./minion-config.yaml:/opt/minion/minion-config.yaml<5>
      #- ./keystore/scv.jce:/opt/minion/etc/scv.jce<6>
    healthcheck:
      test: "/health.sh"<7>
      interval: 30s
      timeout: 6s
      retries: 3
    ports:<8>
      - '514:1514/udp'
      - '162:1162/udp'
      - '8201:8201/tcp'
----
<1> Friendly container name
<2> Set the time zone and the Minion configuration via environment variables. To list all available time zones, use `timedatectl list-timezones`.
<3> Optional. Use to control the minimal Java heap size.
<4> Optional. Use to control the maximum Java heap size.
<5> Configuration file for connectivity and features
<6> Keystore file with encrypted credentials for authenticating broker endpoints.
Initially this line should be commented out, and will need to be activated after the file has been created on the local system.
<7> Run our health check to indicate the Minion is ready. It uses the `opennms:health-check` internally running in Karaf.
<8> Publish ports for Syslog, SNMP trap listener, and the SSH access to the xref:reference:karaf-shell/karaf-shell.adoc[Karaf shell].

The Minion process in the container runs as a non-root user and can't open privileged ports < 1024.
We open the listener for privileged (514/udp, 162/udp) and don't have to give additional permissions to the Minion process in the container.

CAUTION: Some environments do not allow the use of ICMP (ping) for non-root users.
         {page-component-title} Minion runs as a non-privileged user in the container with `userid=10001, groupid=10001`.
         You can verify with `sysctl -n net.ipv4.ping_group_range` if the group id `10001` is in the allowed group range.
         If not, add the following lines in your service definition in the `docker-compose.yml` file.

[source, docker-compose.yml]
----
sysctls:
  net.ipv4.ping_group_range: "10001 10001"
----

.Create a file with the configuration for connectivity and features
[source, minion-config.yaml]
----
---
broker-url: 'failover:tcp://core-instance-ip:61616'<1>
id: 'my-minion'<2>
location: 'my-location'<3>

netmgt:
  syslog:<4>
    syslog.listen.interface: "0.0.0.0"
    syslog.listen.port: 1514

  traps:<5>
    trapd.listen.interface: "0.0.0.0"
    trapd.listen.port: 1162
----

<1> Replace the broker endpoint URL that goes to your {page-component-title} Core instance. If you have ActiveMQ with SSL running, replace `tcp` with `ssl`.
<2> Replace `my-location` with a location name that represents the remote location where the Minion is running.
<3> Optional. You can set a unique human-readable Minion identifier; if not set, a unique identifier is generated.
<4> Enable the Syslog listener on the Minion on port 1514/udp.
<5> Enable the SNMP trap listener on the Minion on port 1162/udp.

TIP: To run with Apache Kafka or configure flow listeners, see the xref:reference:configuration/minion-confd/minion-confd.adoc#minion-confd[Minion configuration reference].

Next, we need to create the keystore file and add the credentials for connecting to the core {page-component-title} server.

.Initialize the keystore with credentials
[source, console]
----
mkdir keystore
chown -R 10001:10001 keystore<1>
docker compose run --rm -v $(pwd)/keystore:/keystore minion -s<2>
----
<1> Assign ownership so the container user account can write within the directory.
<2> When prompted, enter the username and password for a `ROLE_MINION` user account on the {page-component-title} server.
You may be prompted for the same username and password twice.

.Edit the `docker-compose.yml` file to uncomment the keystore file
[source, diff]
----
-      #- ./keystore/scv.jce:/opt/minion/etc/scv.jce
+      - ./keystore/scv.jce:/opt/minion/etc/scv.jce
----

.Validate your Docker Compose file
[source, console]
----
docker compose config -q
----

.Start the service in background
[source, console]
----
docker compose up -d
----

.Verify the connectivity and the configuration with the health check
[source, console]
----
docker compose exec minion bin/client opennms:health-check
----

.The endpoints should be reachable and the bundles should be installed successful
[source, output]
----
Verifying installed bundles      [ Success  ]
Connecting to JMS Broker         [ Success  ]
=> Everything is awesome
----
