Cased Documentation
Search…
⌃K

Deploying Cased Shell to AWS using Terraform

Get Cased Shell up and running onto your cloud environment in minutes using our Terraform module.

Terraform module

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.