Microservice Deployment

Dependencies

Before you can deploy Beamable Standalone Microservices, you need to complete the Getting-Started Guide. That means having Dotnet 8 installed, and getting the Beam CLI.

You can confirm you have everything installed checking the versions of the tools.

dotnet --version
beam version # beam --version also works.

To deploy, you also need to have Docker installed. You can verify it is installed correctly by using the --version command.

docker --version

In order to deploy a Microservice, you also need to have a local .beamable workspace with a Beamable Standalone Microservice. As a reminder, you can create one quickly using the commands below.

beam init MyProject
cd MyProject
beam project new service HelloWorld

Deployment

Beamable Standalone Microservices use Dotnet as the core technology to run locally on your development machine. However, when it is time to release your Microservice to production, the service will be built into an OCI compliant image using Docker, and uploaded to the Beamable Cloud. Beamable's internal orchestration platform (sometimes called BeamO ) will deploy containerized instances of the service.

To deploy your local project, use the services deploy command.

beam services deploy

This will validate that your Standalone Microservice can be built, and that it will start accepting HTTPS traffic. Each Standalone Microservice will be built into a Docker image and then run locally as a Docker container. The deploy command will wait for the service to start responding to health check API calls. After the service responds as healthy, the deploy command will upload the Docker image to Beamable.

📘

Docker CPU Architecture

Beamable Cloud requires that all services are built to x64 CPU architectures. Unfortunately, this means that developers with non x86 based computers will need to cross compile services, which causes the deploy process to take longer.

After all the Microservices have uploaded, the deploy command commits a service manifest to the Beamable API, which creates Beamable Cloud resources for your services. The services will be enabled, and you can see them available in the Beamable Portal's Operation/Microservices section.

Now that your service is running on the Beamable Cloud, you can send HTTPS traffic to your service. To help test, you can open the dot-dot-dot menu on the right side of the HelloWorld
card, and select "Docs" to open an Open API page.

Disabling Services

After a Standalone Microservice has been deployed, it will continue to be available on the Beamable Cloud until it is disabled. A service can be temporarily disabled through Portal, but they will be re-activated after a fresh deploy command occurs.

To disable a service through a deploy command, you need to modify the configuration of the Microservice source code itself. In the .csproj file of your service, set the <BeamEnabled> property to false. Then, re-run the deploy command. See the Microservice Configuration Section for more details about project configuration.

📘

Services Cost Money!

Remember, Every service running on Beamable Cloud may increase your Beamable Bill. Disable your services to reduce your monthly bill.

Dockerfiles

Standalone Microservices build custom Docker images that are run on the Beamable Cloud. Each service has a Dockerfile that defines how the Docker image is constructed.

You may modify this file to extend the capabilities of your resulting docker image. However, there are a few restrictions about how you may modify the file. Do not edit anything between the following tags,

• <BEAM-CLI-COPY-ENV>
• <BEAM-CLI-COPY-SRC>

Those tags define special places in the Dockerfile where the Beam CLI will inject custom data about your project structure. Any changes you make between these tags will be overwritten every time the Beam CLI runs.

You may change the dotnet framework version at your own peril. Beamable has validated that dotnet 6 is stable for all supported platforms. However, versions after dotnet 6 may not cross compile CPU architectures correctly. Beamable requires that Docker images are built to x86 architecture. If your developer team has members with non x86 CPU based computers (like a recent Apple Silicon Mac), then those developers will not be able to upload to Beamable Cloud.

Finally, the port 6565 MUST be exposed. The port is used as a health check mechanism within the Beamable Cloud. If you delete that line, your services will fail to pass health checks and cannot be uploaded.

Here is a sample Dockerfile from a service created with Beam CLI 2.0.0.

# use the dotnet sdk as a build stage  
FROM mcr.microsoft.com/dotnet/sdk:6.0-alpine as build-env  
  
# <BEAM-CLI-COPY-ENV> this line signals the start of environment variables copies into the built container. Do not remove it. This will be overwritten every time a variable changes in the execution of the CLI.  
ENV BEAM_CSPROJ_PATH="/subsrc/services/HelloWorld/HelloWorld.csproj"  
# </BEAM-CLI-COPY-ENV> this line signals the end of environment variables copies into the built container. Do not remove it.  
  
# <BEAM-CLI-COPY-SRC> this line signals the start of Beamable Project Src copies into the built container. Do not remove it. The content between here and the closing tag will change anytime the Beam CLI modifies dependencies.  
RUN mkdir -p /subsrc/services/HelloWorld  
COPY services/HelloWorld /subsrc/services/HelloWorld  
# </BEAM-CLI-COPY-SRC> this line signals the end of Beamable Project Src copies. Do not remove it.  
  
# build the dotnet program  
WORKDIR /  
  
RUN dotnet publish ${BEAM_CSPROJ_PATH} -c release -o /beamApp  
  
# use the dotnet runtime as the final stage  
FROM mcr.microsoft.com/dotnet/runtime:6.0-alpine  
WORKDIR /beamApp  
  
# expose the health port  
EXPOSE 6565   
# copy the built program  
COPY --from=build-env /beamApp .  
  
# when starting the container, run dotnet with the built dll  
ENTRYPOINT ["dotnet", "/beamApp/HelloWorld.dll"]  

Local Docker Testing

The recommended developer workflow is to run your micro services using Dotnet. However, because deployments are running within a container, it may be beneficial to validate that your services work in Docker before deploying them.

The services run command will run your services on your local machine with Docker. It will build the Dockerfile into an image, and run a container for you. Remember that the project run command runs services locally as dotnet processes, where-as this command will start a Docker container.

beam services run --ids HelloWorld

You can validate that your services are running in docker using project ps or by using Docker directly.

beam project ps 
docker ps

After you are done testing, you can use Docker directly to stop all the containers, or your can use services stop command.

beam services stop