{:new_window: target="blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:codeblock: .codeblock} {:pre: .pre} {:child: .link .ulchildlink}

Starting the {{site.data.keyword.horizon}} agent in a container on Linux or {{site.data.keyword.macOS_notm}}¶

{: #container-agent}

There are several techniques to start the agent in a container providing different levels of ease and flexibility.

Option 1 - The agent-install instructions provide a }{: .externalLink--container option to download and launch the agent in a container.
Option 2 - If you have already installed the {{site.data.keyword.horizon}} CLI package, it installed a horizon-container script onto your system that can be used to start the anax in container.
Option 3 - Manually start the docker container with custom parameters.

Prerequisites¶

{: #container-prereqs}

Docker or Podman needs to be installed on the host device. Review instructions on installing Docker on Linux or the }{: .externalLinkinstructions on installing Podman on Linux users might require a Docker Desktop license, if necessary, and install Docker on your device. For more information, see the }{: .externalLink}. {{site.data.keyword.macOS_notm}Docker installation for Mac .}{: .externalLink} documentation. Alternatively, Podman can also be used on {{site.data.keyword.macOS_notm}

If your management hub uses Secure Socket Layer (SSL) encryption, the management hub SSL certificate is required.

Option 1 - `agent-install.sh --container`¶

For a simplified process to getting an agent running, see the --container option in agent-install instructions .}{: .externalLink

Option 2 - `horizon-container start`¶

Run the horizon-container start command to start the agent in a container.

$ horizon-container -?
Usage: /usr/bin/horizon-container {start|stop|update} [index-num] [default-file]
  start:  pull the latest horizon docker image and start it
  stop:   unregister the node and stop/remove the horizon docker container
  update: stop the horizon container (w/o unregistering), pull the latest docker image, and start it. Any running services will remain running.

Arguments:
  index-num:      an integer number identifying this instance of horizon when running multiple horizon containers on the same host. Default is 1.
  default-file:   a default file to use to set common environment variables for the horizon agent like HZN_EXCHANGE_URL, HZN_FSS_CSSURL, HZN_AGBOT_URL, HZN_DEVICE_ID, HZN_NODE_ID, HZN_AGENT_PORT and HZN_MGMT_HUB_CERT_PATH. If not specified and /etc/default/horizon exists on the host, that will be used.

Option 3 - Manual `docker run` instructions (Linux only)¶

Use these docker run instructions to start the agent in a container, which provides more control over details than that allowed by the horizon-container script or agent-install.sh script.

Starting the agent¶

{: #container-start}

Before starting the container, create a configuration file for the agent. The configuration file should include the following:
HZN_EXCHANGE_URL=<address of your exchange>
HZN_FSS_CSSURL=<css address>
HZN_ORG_ID=<the org this node should be in>
HZN_EXCHANGE_USER_AUTH=<exchange username:password> (or apikey)
HZN_AGBOT_URL=<agbot api address>
HZN_MGMT_HUB_CERT_PATH=<path to the ssl certificate file on the host machine>

Optional:

HZN_NODE_ID=<a name for your node>
If this parameter is not included, the node will be assigned a random alphanumeric identifier.
(DEPRECATED) HZN_DEVICE_ID=<a name for your node>
Prior to starting the container, export the following variables:
HZN_AGENT_IMAGE=<name of the agent container image in the repo>
- This should include the url for the repository if it is not the default one.
HZN_AGENT_IMAGE_TAG=<version of the agent container to use>
CONFIG_FILE=<Location of the configuration file>
- The configuration file with the contents from step 1.
DOCKER_NAME=<name for the agent container>
HORIZON_AGENT_PORT=<port number>
- The port to expose from the container that hzn will call the agent on. This is typically 8081.
DOCKER_ADD_HOSTS="--add-host=$<host name to add to container hosts file>"
- This is only necessary if the exchange or CSS url will not be resolvable from inside the agent container.
- Use this syntax --add-host=edge-openhorizon.com:169.22.10.179

Example:

HZN_AGENT_IMAGE=openhorizon/amd64_anax
HZN_AGENT_IMAGE_TAG=latest
CONFIG_FILE=/etc/default/horizon
HZN_MGMT_HUB_CERT_PATH=/etc/horizon/agent-install.crt
DOCKER_NAME=horizon1
HORIZON_AGENT_PORT=8081

Prior to starting the container, create several shared volume directory paths:

export fssBasePath=$HOME/tmp/horizon
export fssHostSharePath=${fssBasePath}/${DOCKER_NAME}

# create fss domain socket path, ess auth path and secret path
mkdir -p ${fssHostSharePath}/fss-domain-socket
mkdir -p ${fssHostSharePath}/ess-auth
mkdir -p ${fssHostSharePath}/secrets
mkdir -p ${fssHostSharePath}/nmp

Start the container by running this docker command:

docker run $DOCKER_ADD_HOSTS -d \
--restart always \
--name $DOCKER_NAME \
--privileged -p 127.0.0.1:$HORIZON_AGENT_PORT:8510 \
-e DOCKER_NAME=$DOCKER_NAME \
-e HZN_VAR_RUN_BASE=$fssHostSharePath \
-v /var/run/docker.sock:/var/run/docker.sock \
-v $CONFIG_FILE:/etc/default/horizon:ro \
-v $HZN_MGMT_HUB_CERT_PATH:$HZN_MGMT_HUB_CERT_PATH \
-v ${DOCKER_NAME}_var:/var/horizon/ \
-v ${DOCKER_NAME}_etc:/etc/horizon/ \
-v $fssHostSharePath:$fssHostSharePath \
$HZN_AGENT_IMAGE:$HZN_AGENT_IMAGE_TAG

export HORIZON_URL=http://localhost:$HORIZON_AGENT_PORT

The docker run command uses the following arguments.

"--name $DOCKER_NAME"
- Names the container something meaningful.
"--add-host=$HZN_EXCHANGE_HOSTS"
- This allows you to add the exchange to the containers host list.
"-p 127.0.0.1:$HORIZON_AGENT_PORT:$ANAX_AGENT_PORT"
- This exposes a port where hzn can reach the agent.
"-e HZN_VAR_RUN_BASE"
- Tells the agent where to store edge sync service files.
"-e DOCKER_NAME=$DOCKER_NAME"
- Tells the agent the container name.
"-v /var/run/docker.sock:/var/run/docker.sock"
- Gives the container access to the docker socket so it can control service containers.
- If you are running podman, set up an alias from podman.sock to /var/run/docker.sock or specify /run/podman/podman.sock
"-v $CONFIG_FILE_MOUNT:/etc/default/horizon:ro"
- The configuration file lets you set variables to tell the agent about itself and the exchange it is to work with.
"-v $HZN_MGMT_HUB_CERT_PATH:$HZN_MGMT_HUB_CERT_PATH"
- Maps the ssl certificate for the exchange into the agent container. The agent will look for the certificate wherever HZN_MGMT_HUB_CERT_PATH is set to in the configuration file.
"-v $DOCKER_NAME_var:/var/horizon/"
- This volume will store the database for the agent.
"-v $DOCKER_NAME_etc:/etc/horizon/"
- This volume contains some initial configuration information for the agent.
- This file in the container image is non-empty so mounting it to a non-empty host folder will cause the agent to fail.
"-v ${fssHostSharePath}:${fssHostSharePath}"
- This volume is used by the edge sync service for storing models downloaded by the service.
"$HZN_AGENT_IMAGE:$HZN_AGENT_IMAGE_TAG"
- The agent container image that will be started.
"export HORIZON_URL=http://localhost:$HORIZON_AGENT_PORT"
- This exported variable tells the horizon CLI how to reach the agent on the port exposed from the container.
To register the agent with a policy, run hzn policy new > node_pol.json, then edit the node_pol.json file to match the deployment policy for the service you want to deploy.

source $CONFIG_FILE
hzn register --policy node_pol.json

To register the agent with a pattern:

source $CONFIG_FILE
hzn register -p <pattern name>

Starting the {{site.data.keyword.horizon}} agent in a container on Linux or {{site.data.keyword.macOS_notm}}¶

Prerequisites¶

Option 1 - agent-install.sh --container¶

Option 2 - horizon-container start¶

Option 3 - Manual docker run instructions (Linux only)¶

Starting the agent¶

Option 1 - `agent-install.sh --container`¶

Option 2 - `horizon-container start`¶

Option 3 - Manual `docker run` instructions (Linux only)¶