FluidFramework/server/README.md

Fluid Reference Server Implementation

This directory contains our reference server implementation. Routerlicious is the main composed server definition that pulls together multiple micro-services that provide the ordering and storage requirement of Fluid runtime.

Directories

Admin provides tenant management for Routerlicious

Charts Kubernetes charts for some micro-services

Gateway Internal landing page for the Fluid server

Gitrest provides a REST API to a GitHub repository. Its API is based off of GitHub's REST APIs.

Gitssh is a git ssh server client container.

Historian provides a REST API to git repositories. The API is similar to that exposed by GitHub but can be used in local development.

Lambdas reusable lambdas for serverless implementation, Routerlicious, and Tinylicious.

Routerlicious composed reference server implementation

Tinylicious Light-weight monolithic server implementation

Running the Reference Server

To get started with Routerlicious and the Fluid reference implementation, you must install docker and allocate at least 4gb of RAM. We suggest you use our docker images, as outlined by the docker compose to start. You can run npm run start:docker from the root directory to try this.

1. Download and install Docker
2. Configure Docker to have 4gb of RAM
3. Start the docker container with npm run start:docker from the repo root, which does this:

"start:docker": "docker-compose -f server/docker-compose.yml up"

In order to quickly change the specific docker images that are used for each component, you can set (export VARIABLE_NAME=value) the following environment variables before running the command above:

• REGISTRY_URL: base URL for the docker registry where the images should be pulled from
• ALFRED_IMAGE_TAG: tag for the docker image for the Alfred components.
• HISTORIAN_IMAGE_TAG: tag for the docker image for the Historian components.

If they're not set in the environment, defaults will be used for the latest stable published images.

Developing the Reference Server

For development, you'll also need to give docker access to your drive (Shared Drives). The instructions for local development are available in Routerlicious.

To locally test changes across GitRest, Historian, and Routerlicious, run docker compose -f docker-compose.dev.yml up from server/ instead of server/routerlicious. Then, when making a change, rebuild the relevant service and restart it. For example,

cd server/gitrest
npm run build
cd ..
docker compose restart gitrest

Common Issues

• Port already allocated
  • This can happen if you have a process already running on a port the docker-compose file expects to have available
  • On MacOS, Disable AirPlay Receiver to free port 5000 (System Settings -> General -> AirDrop & Handoff -> AirPlay Receiver)
• Drive Share Failure
  • An intermittent failure most frequent on Windows, best solved by reinstalling
• Not Enough RAM
  • Allocate more RAM

Using older version of published docker images

By default the docker compose file pulls the latest published images. If you want to use a specific version for testing, you can make a copy of docker-compose.yml and change the tag from latest to a specific version number.

Routerlicious for Local Development

With Webpack Dev Server && the Webpack Fluid Loader (Yo-Fluid Output)

To use Routerlicious with a Yo-Fluid container, you should start the Routerlicious docker containers, and then start the webpack dev server with the docker env command.

    "start:docker": "webpack serve --config webpack.config.js --package package.json --env mode=docker",

Using the Gateway Host

Gateway is an example of a service providing its own Fluid Container host. Gateway serves a Fluid Loader.

You can access this loader by using the following URL Schema

https://localhost:3000/loader/fluid/${container-identifier}?chaincode=${data-store-package-name}@${version}