Deploying your App
Deploying on AWS ECS

Deploying on Amazon ECS

Moose can be deployed to Amazon's Elastic Container Service (ECS). ECS offers a managed container orchestrator at a fraction of the complexity of managing a Kubernetes cluster.

If you're relatively new to ECS we recommend the following resources:

  • Amazon Elastic Container Service (ECS) with a Load Balancer | AWS Tutorial with New ECS Experience (opens in a new tab)
  • Tutorial: Deploy NGINX Containers On ECS Fargate with Load Balancer (opens in a new tab)
  • How to configure target groups ports with listeners and tasks (opens in a new tab)
  • The first step is deciding whether you'll host your Moose container on Docker Hub or Amazon's Elastic Container Registry (ECR). Amazon ECR is straightforward and is designed to work out of the box with ECS. Using Docker Hub works if your moose container is publicly available; however, if your container is private, you'll need to do a bit more work to provide ECS with your Docker credentials.

    See: Authenticating with Docker Hub for AWS Container Services (opens in a new tab)

    Here is an overview of the steps required:

  • You'll first need to create or use an existing ECS cluster.
  • Then, you'll need to create an ECS Task definition. This is where you'll specify whether you want to use AWS Fargate or AWS EC2 instances. You'll also have options for selecting your OS and Architecture. Specify Linux/X86-64 or Linux/ARM-64. This is important as you'll also need to specify a matching moose container image, such as moose-df-deployment-x86_64-unknown-linux-gnu:0.3.175 or moose-df-deployment-aarch64-unknown-linux-gnu:0.3.175
  • As with all AWS services, if you're using secrets to store credentials, you will need to specify an IAM role with an AmazonECSTaskExecutionRolePolicy and SecretsManagerReadWrite policy.
  • Under the Container section, specify the name of your moose deployment and provide the container image name you're using.
  • Next, specify the Container Port as 4000.
  • Configuring container environment variables

    While still in the Amazon ECS Task definition section, you'll need to provide the environment variables on which your Moose application depends. Scroll down to the Environment variables section and fill in each of the following variables.

    Note: if you prefer, you can provide the environment variables below via an env file hosted on S3.

    Moose Server KeysUsage
    MOOSE_HTTP_SERVER_CONFIG__HOSTYour moose network binding address. This needs to be
    MOOSE_HTTP_SERVER_CONFIG__PORTThe network port your moose server is using. This defaults to 4000
    Moose Clickhouse KeysUsage
    MOOSE_CLICKHOUSE_CONFIG__DB_NAMEThe name of your Clickhouse database
    MOOSE_CLICKHOUSE_CONFIG__HOSTThe hostname for your Clickhouse database
    MOOSE_CLICKHOUSE_CONFIG__HOST_PORTThe port address for your Clickhouse database
    MOOSE_CLICKHOUSE_CONFIG__PASSWORDThe password to your Clickhouse database
    MOOSE_CLICKHOUSE_CONFIG__USERThe database user name
    MOOSE_CLICKHOUSE_CONFIG__USE_SSLWhether your database connection requires SSL. A value of 0 (not using SSL) or 1 (using SSL)
    Moose Redpanda KeysUsage
    MOOSE_REDPANDA_CONFIG__BROKERThe hostname for your Redpanda instance
    MOOSE_REDPANDA_CONFIG__MESSAGE_TIMEOUT_MSThe message timeout delay in milliseconds*
    MOOSE_REDPANDA_CONFIG__SECURITY_PROTOCOLThe Redpanda security protocol such as SASL_SSL

    If you're using a hosted Redpanda cloud service, consider using a value of greater than one 1000ms (1 second) for the Redpanda message timeout delay.

    Consider other options on the Task Creation page and press the Create button when ready.

    Building an ECS Service

    Once you've completed creating an ECS Task, you're ready to create an ECS Service. An ECS Service is a definition that allows you to specify how your cluster will be managed. Navigate to your cluster's Service page and press the Create button to create your new Moose service. The section we're interested in is the Deployment configuration section. There, you'll specify the Task Definition you created earlier. You can also specify the name of your service—perhaps something creative like moose-service—and the number of tasks to launch.


    Note at this time, we recommend that you only launch a single instance of Moose in your cluster. We're currently developing for multi-instance concurrent usage.

    The remaining sections on the create service page allow you to specify networking considerations and whether you'll use a load balancer.

    You can press the Create button to launch an instance of your new ECS Moose service.

    Setting up a health check

    Your generated moose docker containers feature an internal health check:

      # Setup health check
      HEALTHCHECK --interval=30s --timeout=3s \
        CMD curl -f http://localhost:4000/health || exit 1

    You'll need to use that health check endpoint when setting up your ECS service load balancer.
    Simply specify the /health endpoint.