Welcome to Kepware Edge > Installation > Installation — Deploying the Container
Installation — Deploying the Container
Installation — Deploying the Container
Kepware Edge is designed as a container application that can be deployer in various container runtime environments. The image contains all prerequisites to allow the runtime to operate and can be deployed using container runtime management solutions (Docker, Podman, etc) or orchestration tools built on Kubernetes.
Tip: Two templates are provided to help with the initial deployment of Kepware Edge; a Docker Compose file and a Kubernetes Manifest file.
Note: Update the variables in these templates before deploying.
 
Import the container images .tar files into the container runtime environments local repository or your own image repository.
Tips: 
If using a remote repository, it must be accessible by the runtime environment to be used.
For Docker or container runtimes like Podman or Rancher, use the Docker load command.
For Kubernetes variants, there often use container as the container runtime. Use the crictl commands to import into the local k8s clusters environment.
 
Starting a Kepware Edge Container Instance – Docker Run Command
To run an instance of the Kepware Edge Docker image using Docker Run, execute the following command:
docker run -d -e USE_SAMPLE_PROJECT=<Use sample project flag> -p 57513:57513 -p 49330:49330 --init --name <Container name> --mount type=bind,source=<Admin password source directory>,target=/opt/kepedge/v1/secrets --mount type=bind,source=<user data source directory>, target=/opt/kepedge/v1/user_data --mount type=bind,source=<.config source directory>, target=/opt/kepedge/v1/.config <Image name>
where:
• <Use sample project flag> (optional). Creates an environmental variable to initialize with the default sample project. Set to ‘TRUE’ to start with a sample project.
• <Admin password source directory> is on the host machine that contains the password.txt file.
See the "Administrator Password" section for more information.
• <user data source directory> is on the host machine that is used to share files with the container.
See the Sharing Files with the Container for more information.
• <.config source directory> is on the host machine that is used to persist the configuration files from the container.
See the “Persisting Data to the Host” for more information
• <Container name> is the name of the container instance
• <Image name> is the name of the container image.
For additional details about Docker run command options, see Docker Run documentation.
 
Starting a Kepware Edge Container Instance – Docker Compose
Docker Compose provides users with the ability to manage multiple services and containers through a single deployment method. Parameters in a Docker Compose .yaml file use the same parameters as the Docker run command above.
Tip: An example Docker Compose file is available to show the basic configuration necessary to deploy and persist configuration data.
 
Starting a Kepware Edge Container Instance – Kubernetes Manifest
Kubernetes manages workloads where Pods are the smallest deployable units and are typically container instances of the workload. Manifest yaml files can be used to deploy pods and services as needed.
Tip: An example Kubernetes manifest file is available to show the basic configuration necessary to deploy and persist configuration data.
 
Required Port Binding
The -p option in the Docker run command specifies the port or range of ports to publish from container to host using the format:
<Host Port>:<Container Port>
 
The ports in the example above are configured by default:
1. The default https port for the Configuration API is 57513.
2. The default port for UA endpoints is 49330.
 
Tip: Other ports can be configured as needed. For example, http port for Configuration API could be used or additional OPC UA endpoints can be configured. If a port other than the defaults listed above is required, include additional ports when executing the Docker run command. Alternatively, a range of ports can be specified.
See the Docker Links User Guide for information on how to manipulate ports in Docker.
See the Docker Networking Overview for information on all networking options.
 
Additional options can be included in the Docker run command to enable data sharing between the host and container.
See Sharing Project Files with the Container section for an example.
 
Administrator Password
A password for the administrator account must be set at container runtime. During the container initialization, Kepware Edge searches for a password.txt file that contains the administrator account password or looks for an environmental variable (non-production/insecure). The password must be between 14 and 512 characters. Set the permissions on this file such that the Docker container user has read and write permissions. Place this file in a directory accessible to the container via a bind mount, as described in the Starting a Kepware Edge container instance section.
Note: When the Kepware Edge container instance starts, it deletes the password.txt file.
Caution: An insecure and non-production option is to pass the password as an environmental variable named “EDGEADMINPW” when deploying the container. The password still needs to follow all character and length requirements.
 
Sharing Files with the Container
Various configuration and files are necessary to share with the Kepware Edge instance running in the container. For example, project files can be loaded using the Configuration API projectLoad service. This service requires files to be located in a specific directory created at container run time:
/opt/kepedge/v1/user_data
 
To move any files to the container, a method of file sharing between the host and container must be implemented. Binding a volume as shown in the Docker Run command example can allow the folder to be accessible in the host running the container runtime. This allows the data in this folder to also persist to the host.
 
A non-binding option to share data with the container is to directly copy files into the container file system using the docker cp command:
docker cp <source file> <container name>:/opt/kepedge/v1/user_data
 
Persisting Data to the Host
Persisting configuration data is strongly recommended while using Kepware Edge in a container. Configuration data, such as the project file, OPC UA certificates and endpoints, user management configuration, and other data are stored in the /opt/kepedge/v1/.config folder in the container file system. Persisting this folder allows for a container to be redeployed due to failure or planned updates while keeping all configuration data from the previous running state.
 
It is also critical to ensure that the location for the configuration data will be accessible to the container instance. Hosting configuration data location in file storage locations that may not be always accessible is highly discouraged to ensure proper configuration persistence and storage by Kepware Edge.
 
Volumes can be used to share and persist data used by Kepware Edge with the host machine. There are multiple options depending on whether a container runtime like Docker is used or a variant of Kubernetes.
 
For container runtimes like Docker or Podman, common approaches are to use volumes managed by the runtime or bind mounts. The Docker run command above provides an example that is using binds that require the host folder location to bind to in the configuration.
Note: The target parameters must not be modified from this example. These directories are created at container run time for the purpose of storing application data and are not configurable.
See the Docker Volumes User Guide for information on volume mounting options.
 
For Kubernetes environments, Persistent Volume Claims need to be created to ensure that configuration data persists through pod redeployments and updates.
See the Kubernetes Persistent Volume Claims User Guide for information on persistent volume claims options.
Note: Do not mount more than one container to a shared .config directory. Each unique instance of Kepware Edge needs its own data store for configuration. This is not supported and can result in undefined behavior.
 
Permissions
To access the specified data source directory on the host, user and group entities identical to those created for Kepware Edge at container run time must exist on the host and be granted the appropriate permission on that directory, where group: kepedge and user: kepedge.
Note: The host and container user and group entities must have matching UID and GID.
 
Configuring a Kepware Edge Container Instance
The Kepware Edge instance is operational after executing the above "docker run" command. To manage certificates for northbound interfaces or configure other administrative options, connect to a command shell on the container with the following command:
docker exec -it <Container Name> /bin/bash
 
From the command shell, the "edge_admin" command-line tool can be used to perform these actions.
See the Command-Line Edge Admin for more information on this tool.
Note: The Kepware Edge runtime must be reinitialized through the Configuration API or restarted after making changes to the UA Endpoint configuration. Restarting the container can be accomplished by running the "docker stop" followed by "docker start" command.
 
Managing OPC UA Certificates
The preferred method for managing OPC UA certificates is to share the trusted certificates through the mounted .config folder. This allows trusted client certificates to be added or updated in the trust store without connecting to the container with a command shell.
 
UA servers require a certificate to establish a trusted connection with each UA client. For the server to accept secure connections from a client, the client's certificate must be imported into the trusted certificate store used by the OPC UA server interface. Management of the UA certificates can be done either using the edge_admin CLI application or by saving the certificates to the configuration data folder.
 
Using the edge_admin CLI
To import an OPC UA certificate into the trust store:
./edge_admin manage-truststore -i MyCertificateName.der uaserver
 
To view the UA server trust store and the thumbprints of the certificates:
./edge_admin manage-truststore --list uaserver
 
Using the .config Data Folder
UA certificates can also be managed directly through .config data folder. Certificates for the UA server to use are maintained in the following directory: <installation_directory>/.config/UA/Server
 
Trusted certificates are located in the following directory:
<installation_directory>/.config/UA/Server/cert
 
Rejected certificates are located in the following directory:
<installation_directory>/.config/UA/Server/RejectedCertificates
 
To trust a certificate, copy the client instance certificate file into the trusted certificates directory. If a rejected certificate needs to be trusted, move the client instance certificate in the rejected certificate directory to the trusted certificates directory.
Note: The certificate files need to have read access by the installed user account, kepedge by default, for the server application to access the certificate for validation.
 
Event Log
In a container environment, log services, such as Docker log service, are used to monitor information about the running container. Kepware Edge can be configured to send all event log messages to *STDOUT* to make the messages accessible through the container runtime or kubernetes log services.
To enable this, use the Configuration API and set the Log to Console properties in the Admin properties as shown below.
 
Endpoint (PUT):
https://<hostname_or_ip>:<port>/config/v1/admin
 
Body:
{ "libadminsettings.EVENT_LOG_LOG_TO_CONSOLE": true }
For additional details about monitoring the Docker log service, see the Docker log documentation.
 
 
Configure the Container
The license server connection can be configured using either the edge_admin command line tool or the Configuration API. To access the edge_admin, you will need to Docker Exec into the container.
 
Using the edge_admin CLI:
1.3. Set the IP address or host name of the server where the license server is running:
./edge_admin manage-licensing -l <server_address>
2.4. Set the licensing “client alias” for the Kepware Edge instance. This is used by the Edge License Server to provide a user configured identification alias for reports and summary of licensing status:
./edge_admin manage-licensing -a “"Kepware Edge Instance 1"”
3.5. For the Private Preview enable “Allow self-signed certificates” to eliminate the need to manage certificates. This wouldn’t be recommended in production but additional details can be provided to test if desired:
./edge_admin manage-licensing -o
4.6. Enable the license server connection:
./edge_admin manage-licensing --lls-enable
Using the Configuration API:
1. Set the IP address or host name of the server where the license server is running, enable “Allow self-signed certificates”, and the alias for identification in the Edge License Server:
Endpoint: (PUT)
https://<hostname_or_ip>:<port>/config/v1/admin
Body:
{
"libadminsettings.LICENSING_SERVER_NAME": "192.168.1.1",
“libadminsettings.LICENSING_SERVER_ALLOW_SELF_SIGNED_CERTS”: true,
“libadminsettings.LICENSING_CLIENT_ALIAS”: “Kepware Edge Instance 1”
}
2. Once configured, enable the license server connection:
Endpoint: (PUT)
https://<hostname_or_ip>:<port>/config/v1/admin
Body:
{
"libadminsettings.LICENSING_SERVER_ENABLE": true
}
 
 
Was this helpful?