Set up your development environment on macOS X

Article
07/26/2022

You can build Azure Service Fabric applications to run on Linux clusters by using macOS X. This document covers how to set up your Mac for development.

Prerequisites

Azure Service Fabric doesn't run natively on macOS X. To run a local Service Fabric cluster, a pre-configured Docker container image is provided. Before you get started, you'll need:

The system requirements for installing Docker Desktop on Mac
To install and run Docker Desktop on Mac

Tip

To install Docker on your Mac, follow the steps in the Docker documentation. After installing, you can use Docker Desktop to set preferences including resource limits and disk utilization.

Create a local container and set up Service Fabric

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

Update the Docker daemon configuration on your host with the following settings and restart the Docker daemon:
```
{
    "ipv6": true,
    "fixed-cidr-v6": "fd00::/64"
}
```
You can update these settings directly in the daemon.json file in your Docker installation path. You can directly modify the daemon configuration settings in Docker. Select the Docker icon, and then select Preferences > Daemon > Advanced.

Note

Modifying the daemon directly in Docker is recommended because the location of the daemon.json file can vary from machine to machine. For example, ~/Library/Containers/com.docker.docker/Data/database/com.docker.driver.amd64-linux/etc/docker/daemon.json.

Tip

We recommend increasing the resources allocated to Docker when testing large applications. This can be done by selecting the Docker Icon, then selecting Advanced to adjust the number of cores and memory.

Start the cluster.

Latest:

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:latest

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, please visit the Service Fabric Onebox page on Docker Hub.

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 directory 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
The cluster will take a moment to start. When it is running, you can view logs using the following command or jump to the dashboard to view the clusters health: http://localhost:19080
```
docker logs sftestcluster
```
To stop and clean up the container, use the following command. However, we will be using this container in the next step.
```
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.

Set up the Service Fabric CLI (sfctl) on your Mac

Follow the instructions at Service Fabric CLI to install the Service Fabric CLI (sfctl) on your Mac. The CLI commands support interacting with Service Fabric entities, including clusters, applications, and services.

To connect to the cluster before deploying applications run the command below.

sfctl cluster select --endpoint http://localhost:19080

Create your application on your Mac by using Yeoman

Service Fabric provides scaffolding tools that help you to create a Service Fabric application from the terminal by using the Yeoman template generator. Use the following steps to ensure that the Service Fabric Yeoman template generator is working on your machine:

Node.js and Node Package Manager must be installed on your Mac. The software can be installed by using HomeBrew, as follows:
```
brew install node
node -v
npm -v
```
Install the Yeoman template generator on your machine from Node Package Manager:
```
npm install -g yo
```

Install the Yeoman generator that you prefer by following the steps in the getting started documentation. To create Service Fabric applications by using Yeoman, follow these steps:

npm install -g generator-azuresfjava       # for Service Fabric Java Applications
npm install -g generator-azuresfguest      # for Service Fabric Guest executables
npm install -g generator-azuresfcontainer  # for Service Fabric Container Applications

After you install the generators, create guest executable or container services by running yo azuresfguest or yo azuresfcontainer, respectively.
To build a Service Fabric Java application on your Mac, JDK version 1.8 and Gradle must be installed on the host machine. The software can be installed by using HomeBrew, as follows:
```
brew update
brew cask install java
brew install gradle
```
Important

Current versions of brew cask install java may install a more recent version of the JDK. Be sure to install JDK 8.

Deploy your application on your Mac from the terminal

After you create and build your Service Fabric application, you can deploy your application by using the Service Fabric CLI:

Connect to the Service Fabric cluster that is running inside the container instance on your Mac:
```
sfctl cluster select --endpoint http://localhost:19080
```
From inside your project directory, run the install script:
```
cd MyProject
bash install.sh
```

Set up .NET Core 3.1 development

Install the .NET Core 3.1 SDK for Mac to start creating C# Service Fabric applications. Packages for .NET Core Service Fabric applications are hosted on NuGet.org.

Install the Service Fabric plug-in for Eclipse on your Mac

Azure Service Fabric provides a plug-in for Eclipse Neon (or later) for the Java IDE. The plug-in simplifies the process of creating, building, and deploying Java services. To install or update the Service Fabric plug-in for Eclipse to the latest version, follow these steps. The other steps in the Service Fabric for Eclipse documentation are also applicable: build an application, add a service to an application, uninstall an application, and so on.

The last step is to instantiate the container with a path that is shared with your host. The plug-in requires this type of instantiation to work with the Docker container on your Mac. For example:

docker run -itd -p 19080:19080 -v /Users/sayantan/work/workspaces/mySFWorkspace:/tmp/mySFWorkspace --name sfonebox mcr.microsoft.com/service-fabric/onebox:latest

The attributes are defined as follows:

/Users/sayantan/work/workspaces/mySFWorkspace is the fully qualified path of the workspace on your Mac.
/tmp/mySFWorkspace is the path that is inside of the container to where the workspace should be mapped.

Note

If you have a different name/path for your workspace, update these values in the docker run command.

If you start the container with a name other than sfonebox, update the name value in the testclient.sh file in your Service Fabric actor Java application.