Docker Sample for Orleans

This repository contains an example project and guide demonstrating an Orleans cluster in Docker containers.

The guide is currently provided only for Windows, and it has only been tested on Windows 10. However, this project and demonstration should work on any platform supporting Linux containers in Docker and .NET Core.

Overview

This project provides executables for both an Orleans silo and client. The project provides a single grain type that manages an incrementing counter.

The client connects to a "singleton" grain instance and requests the incrementing of the counter. There may be multiple, simultaneous clients, but the requests will be interleaved and processed single-threaded by the "singleton" grain instance.

The silo may be run with development clustering or Azure Table Storage clustering. If using development clustering, only a single silo is supported in the cluster. If using Azure Table Storage clustering, multiple silos may be in the cluster. However, given the client implementation, only a single grain instance will ever be active.

Guide for Windows

This guide demonstrates running an Orleans cluster with a single silo using Linux containers and Docker Desktop for Windows.

Prerequisites

• Clone this repository to a convenient location.
• Download and install Docker Desktop for Windows (latest version recommended). Configure the service to run Linux containers.
• Download and install the .NET Core SDK (version 2.2, latest patch version recommended).
• An Azure Table Storage resource. This is only needed if testing the Azure Table Storage clustering.

Build the silo image

In this section, we'll build the silo image used in the following sections.

First, open a command prompt and change to the directory containing the cloned repository.

Finally, build the silo image by executing the following command:

docker build -f src\OrleansDockerSample.Silo\Dockerfile --pull -t orleans-docker-sample:latest .

Run the project with development clustering

In this section, we'll start a single silo container using development clustering (a hardcoded connection to localhost). The container will run with the default "bridge" network, and the network ports will be exposed on the host machine. We'll start a single client, and it will connect to the network ports exposed on the host machine. Because development clustering uses localhost, the client must be run on the host machine.

First, open a command prompt.

Next, start a single silo container by executing the following command:

docker run -d --name silo -p 11111:11111 -p 30000:30000 --rm orleans-docker-sample:latest

Next, change to the directory containing the cloned repository.

Next, start a single client by executing the following commands:

cd src\OrleansDockerSample.Client
dotnet run

The container logs of the silo and the console logs of the client should confirm the progress of the incrementing counter.

Next, stop the client by pressing Ctrl+C in the command prompt that was used to run the client.

Finally, stop the silo container by executing the following command:

docker stop silo

Run the project with Azure Table Storage clustering

In this section, we'll start a single silo container using Azure Table Storage clustering. The container will run with the default "bridge" network, and the network ports will be exposed on the host machine. We'll start a single client, and it will connect to the network ports exposed on the host machine. Because Azure Table Storage clustering publishes the IP address in an external service, the client may be run on any machine with network access to the published IP address.

First, obtain the connection string to the Azure Table Storage resource.

Next, open a command prompt.

Next, start a single silo container by executing the following command (replacing "" with the connection string to the Azure Table Storage resource):

docker run -d -e ConnectionString=<MyConnectionString> --name silo -p 11111:11111 -p 30000:30000 --rm orleans-docker-sample:latest

Next, change to the directory containing the cloned repository.

Next, start a single client by executing the following commands (replacing "" with the connection string to the Azure Table Storage resource):

set ConnectionString=<MyConnectionString>
cd src\OrleansDockerSample.Client
dotnet run

The container logs of the silo and the console logs of the client should confirm the progress of the incrementing counter.

Next, stop the client by pressing Ctrl+C in the command prompt that was used to run the client.

Finally, stop the silo container by executing the following command:

docker stop silo