Set up a Linux Service Fabric cluster on your Windows developer machine

  • Article

This document covers how to set up a local Linux Service Fabric cluster on a Windows development machine. Setting up a local Linux cluster is useful to quickly test applications targeted for Linux clusters but are developed on a Windows machine.

Prerequisites

Linux-based Service Fabric clusters do not run on Windows, but to enable cross-platform prototyping we have provided a Linux Service Fabric one box cluster docker container, which may be deployed via Docker for Windows.

Before you get started, you need:

  • At least 4-GB RAM
  • Latest version of Docker for Windows
  • Docker must be running in Linux containers mode

Tip

To install Docker on your Windows machine, follow the steps in the Docker documentation. After installing, verify your installation.

Create a local container and setup Service Fabric

To set up a local Docker container and have a Service Fabric cluster running on it, run the following steps:

  1. Update the Docker daemon configuration on your host with the following and restart the Docker daemon:

    {
  "ipv6": true,
  "fixed-cidr-v6": "2001:db8:1::/64"
}

    The advised way to update is to go to:

    • Docker Icon > Settings > Docker Engine
    • Add the new fields listed above
    • Apply & Restart - restart the Docker daemon for the changes to take effect.

  2. Start the cluster via PowerShell.
    Ubuntu 20.04 LTS:

    docker run --name sftestcluster -d -v /var/run/docker.sock:/var/run/docker.sock -p 19080:19080 -p 19000:19000 -p 25100-25200:25100-25200 mcr.microsoft.com/service-fabric/onebox:u20

    Ubuntu 18.04 LTS:

    docker run --name sftestcluster -d -v /var/run/docker.sock:/var/run/docker.sock -p 19080:19080 -p 19000:19000 -p 25100-25200:25100-25200 mcr.microsoft.com/service-fabric/onebox:u18

    Tip

    By default, this will pull the image with the latest version of Service Fabric. For particular revisions, see the Service Fabric Onebox page on Docker Hub.

  3. Optional: Build your extended Service Fabric image.

    In a new directory, create a file called Dockerfile to build your customized image:

    Note

    You can adapt the image above with a Dockerfile to add additional programs or dependencies into your container. For example, adding RUN apt-get install nodejs -y will allow support for nodejs applications as guest executables.

    FROM mcr.microsoft.com/service-fabric/onebox:u18
RUN apt-get install nodejs -y
EXPOSE 19080 19000 80 443
WORKDIR /home/ClusterDeployer
CMD ["./ClusterDeployer.sh"]

    Tip

    By default, this will pull the image with the latest version of Service Fabric. For particular revisions, please visit the Docker Hub page.

    To build your reusable image from the Dockerfile, open a terminal and cd to the directly holding your Dockerfile then run:

    docker build -t mysfcluster .

    Note

    This operation will take some time but is only needed once.

    Now you can quickly start a local copy of Service Fabric whenever you need it by running:

    docker run --name sftestcluster -d -v /var/run/docker.sock:/var/run/docker.sock -p 19080:19080 -p 19000:19000 -p 25100-25200:25100-25200 mysfcluster

    Tip

    Provide a name for your container instance so it can be handled in a more readable manner.

    If your application is listening on certain ports, the ports must be specified by using additional -p tags. For example, if your application is listening on port 8080, add the following -p tag:

    docker run -itd -p 19000:19000 -p 19080:19080 -p 8080:8080 --name sfonebox mcr.microsoft.com/service-fabric/onebox:u18

  4. The cluster will take a short amount of time to start, you can view logs using the following command or jump to the dashboard to view the clusters health http://localhost:19080:

    docker logs sftestcluster

  5. After the cluster is deployed successfully as observed in step 4, you can go to http://localhost:19080 from your Windows machine to find the Service Fabric Explorer dashboard. At this point, you can connect to this cluster using tools from your Windows developer machine and deploy applications targeted for Linux Service Fabric clusters.

    Note

    The Eclipse plugin is currently not supported on Windows.

  6. When you are done, stop and clean up the container with this command:

    docker rm -f sftestcluster

Known Limitations

The following are known limitations of the local cluster running in a container for Mac's:

  • DNS service does not run and is currently not supported within the container. Issue #132
  • Running container-based apps requires running SF on a Linux host. Nested container applications are currently not supported.

Next steps