Deploying Cased Shell to Amazon ECS

Introduction
This is a detailed how-to for setting up and using Cased Shell on AWS.
Cased Shell is deployed as a standalone application on your own infrastructure. It runs with a single Docker container, available on Docker Hub. It features automatic SSL setup, allowing for encryption all the way to the application.
Cased Shell is designed to be extremely lightweight, and does not require any data storage beyond setting a few environmental variables when you run the service. The app requires minimal configuration itself, and some light operations work (outlined here) to get the app running on your infrastructure.
Easiest Option (start here!)
If you're running on ECS, you can use follow these steps with our Terraform module to do everything. Check it out on GitHub and in the Docker Registry.​
We will add additional automated Kubernetes/EKS support soon.
Setting up your Cased Shell instance on AWS
Besides the Terraform module, what follows is the recommended and tested approach to getting a single Cased Shell instance running on AWS.
There are of course other ways to deploy Cased Shell (it's just a single Docker image that you need to get running and accessible) — but this process is quick and straight-forward, and should work well with existing infrastructure setups.
Cased Shell runs as a single Docker image and at ghcr.io/cased/shell. You can use the latest tag as we are rapidly adding features, but also releasing versioned images.
Set up a subdomain (e.g., shell.mydomain.net). Cased Shell takes care of SSL entirely for you, and the application runs on 443. The container does need both port 80 and port 443 open. The application itself runs on 443.
Setup a Network Load Balancer that just forwards raw TCP traffic on both 443 and 80 to a single container. For fast and effective startup and updating:
Set a high health check grace time number (figure 800-1000 seconds to be safe), since you're just using a single container.
Set your NLB health check interval to 10 seconds.
Set your healthy/unhealthy threshold to 2.
Set your ECS deregistration_delay to 60 seconds.
Set the target group's preserve_client_ip value to true, so you get accurate logging of client IP addresses.
Remember that when using an NLB, you set access control at the container level, not the load balancer. So if you want your app on 443 to be accessible to only some IPs, you need to set the correct security groups at the container/ECS level. Port 80 can be safely left open to the world, and is necessary to do so for automatic https setup.
The application exposes a /_ping route that you should use for your load balancer health checks. It returns a 200, the current epoch time, and version.
Deploy the pre-built Docker container with an ECS service. We use terraform to do this at Cased, but obviously CloudFormation or other config management software works. You will only need a single task, running the shell image.
There are a few environmental variables/secrets you'll need to set into your container. You can find the first two values on your Shell settings page.
CASED_SHELL_HOSTNAME
The hostname of your installation (e.g. myshell.mydomain.net). Don't include the protocol.
CASED_SHELL_SECRET
A secret used for verifying API requests for Shell.
Additional optional env vars. You can include any of these, or none. For example, you can include the private key, but not the passphrase. The application will prompt you during use for whatever data is not yet stored.
CASED_SHELL_KEEPALIVE_INTERVAL
How often (in seconds) to send keep-alives. Defaults to 30.
CASED_SHELL_SSH_PRIVATE_KEY
The text of an SSH private key to store in the container. If SSH certificates are not enabled, this key be used for all SSH access.
CASED_SHELL_SSH_USERNAME
The username associated with the key.
CASED_SHELL_SSH_PASSPHRASE
An passphrase for the SSH key.
You can read more about the application's required and optional environmental variables.
Make sure the SSH ports on your hosts will accept connections from the Cased Shell service. If you use a NAT, make sure your NAT IPs are in the relevant security group, for example.
Cased Shell logs to stdout in its container, so log messages should automatically get picked up by most Docker loggers (e.g., Datadog's logger).
After these best practices, Cased Shell will now be deployed onto your AWS infrastructure and ready to expedite production work.

Web Shell - Previous

Getting started

Next - Web Shell

Deploying Cased Shell on Google Cloud Run

Last modified 1mo ago

Copy link

Contents

Introduction

Easiest Option (start here!)

Setting up your Cased Shell instance on AWS