TX Text Control .NET Server

AWS

Topic

Text Control names AWS Elastic Beanstalk and AWS Fargate as environments for applications built with TX Text Control .NET Server. Both run the application that the Linux and Docker pages produce, and both need the same three things: x86_64 instances, a proxy that lets the Document Editor's WebSocket connection through and a load balancer that keeps a browser on one instance.

What AWS Has to Provide

  • x86_64 Linux. The Core engine has native libraries for linux-x64 only. Fargate tasks therefore use the CPU architecture X86_64 with the operating system family LINUX, and EC2 instance types are x86_64. ARM64 instances with AWS Graviton processors can't run TX Text Control.
  • The .NET runtime, from the Elastic Beanstalk platform or from the container image.
  • An Application Load Balancer for applications with the Document Editor. It forwards WebSocket connections, and its stickiness keeps a browser on one target.
  • Windows instances take the Windows route. On EC2 instances with Windows, the application is hosted as described in IIS or Windows Service.
  • A runtime license per instance. In Text Control's words about AWS Fargate, each container instance that is created as demand increases runs its own instance of TX Text Control. See Runtime Licenses.

Elastic Beanstalk on Linux

The .NET Core on Linux platform runs the published application on EC2 instances.

  1. Publish the application for Linux, as CI/CD describes:

    dotnet publish MyApp/MyApp.csproj -c Release -r linux-x64 --self-contained false -o publish

    The platform runs applications that use its .NET runtime as well as self-contained ones.

  2. Add a Procfile to the source bundle, so that the platform starts the right process. AWS recommends one in every bundle:

    web: dotnet MyApp.dll

  3. Create the environment with an Application Load Balancer, and select an x86_64 instance type.

  4. Let the proxy through to the editor. The platform puts nginx in front of the application and forwards requests from port 80 to port 5000, the port Kestrel listens on by default. The WebSocket connection of the Document Editor needs the Upgrade and Connection headers, as Host the Connection describes. Add them to the proxy configuration in the source bundle, in a .conf file under .platform/nginx/conf.d/, or replace the configuration completely with .platform/nginx/nginx.conf, which then has to contain include conf.d/elasticbeanstalk/*.conf;. As an alternative, the .NET Core on Linux platform runs without a proxy at all:

    option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: none

  5. Set the configuration of the application with environment properties of the environment. They reach the application as environment variables, so DocumentEditorWorker__ListenAddress and DocumentEditorWorker__Port configure the Document Editor backend as in Prepare the Application.

AWS Fargate

Fargate runs the container image from Dockerfile without EC2 instances of your own.

  1. Push the image to Amazon ECR:

    aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com
docker tag myapp <account-id>.dkr.ecr.<region>.amazonaws.com/myapp:1.0.0
docker push <account-id>.dkr.ecr.<region>.amazonaws.com/myapp:1.0.0

  2. Write the task definition with the operating system family LINUX and the CPU architecture X86_64, the CPU and memory of the task and the container port 8080, which the .NET images listen on. Size the memory for the editing sessions the task is to hold; Document Editor Architecture gives Text Control's guidance of 50 to 150 MB per session.

  3. Run the service behind an Application Load Balancer. Tasks with the awsvpc network mode register in a target group of the type ip.

Each running task counts as an instance for licensing, and a task that stops takes its editing sessions with it.

Settings of the Application Load Balancer

The Document Viewer and your document processing endpoints work behind a load balancer without further settings. The Document Editor needs three of them.

Stickiness

A WebSocket connection stays on the target that accepted it: the target that answers the upgrade request with status 101 serves the whole connection, and cookie-based stickiness isn't used afterward. What has to stay together are the page, the upgrade request and later reconnects, and those are ordinary HTTP requests. Turn on duration-based stickiness in the target group:

aws elbv2 modify-target-group-attributes \
    --target-group-arn <target-group-arn> \
    --attributes "Key=stickiness.enabled,Value=true" "Key=stickiness.lb_cookie.duration_seconds,Value=28800"

The load balancer then sets its AWSALB cookie, and browsers that accept cookies return to the same target. The duration can be 1 second to 7 days. Sticky sessions don't work when cross-zone load balancing is switched off for the target group, and they can't be combined with the weighted random routing algorithm.

Idle Timeout

The load balancer closes a connection on which nothing is sent or received for the length of its idle timeout, which is 60 seconds by default. An open editor that a user only reads sends nothing in the meantime, and ASP.NET Core sends its WebSocket ping frames every two minutes by default. Raise the idle timeout above that interval:

aws elbv2 modify-load-balancer-attributes \
    --load-balancer-arn <load-balancer-arn> \
    --attributes "Key=idle_timeout.timeout_seconds,Value=300"

The valid range is 1 to 4000 seconds. WebSocketOptions.KeepAliveInterval in your application is the other side of the same setting; Add the Middleware to the Pipeline shows where it is set.

Deregistration Delay

When a target is removed, for example during a deployment, the load balancer waits 300 seconds by default before the deregistration completes, so that requests in flight can finish. Editors on that target keep working during this time, and their sessions end when the task or instance stops. Save documents regularly, as Scaling Containers describes.

Next Steps