Visual Studio Code Remote Dev Containers on AWS Set Up Guide

This guide will provide a list of system requirements and links to resources to get you set up and ready for remote development on AWS using Visual Studio Code Dev Containers.

While the remote Ubuntu configuration steps are AWS-specific, the process will be almost identical for other cloud providers.

This guide assumes you’re familiar with the Terminal, SSH, Docker, Linux (Ubuntu more specifically), and AWS, so if you’re not experienced using these technologies, be prepared to spend more time getting things set up.

If you’re entirely new to Dev Containers, I’d recommend watching my webinar on Visual Studio Dev Containers for Node.js apps on AWS to give you a solid overview of what’s involved.

The Visual Studio Code Remote Development in Containers guide and tutorial are also great resources to help you get started.

Let’s get to it!

Example Repository

If you’re looking for an actual Node.js application using Dev Containers, check out the Mandalorion Gifs Node.js repository, including an example devcontainer.json file and launch configuration for step-debugging.

Alternatively, you can use one of Microsoft’s sample repositories with examples in Go, Python, Rust, NET core, and other popular languages.

Step 1. AWS Credentials

Your AWS credentials must have permissions required for managing a Lightsail instance and SSH keys, or if using EC2, you’ll need permissions for SSH Key Pairs, Security Groups, and EC2 instances.

If using EC2, I’d recommend checking if your organization has a base AMI you should be using.

Step 2. Install Visual Studio Code Remote Container Extensions

The following extensions are required for remote container-based development with Visual Studio Code:

Step 3. Install Docker Locally

A local installation of Docker is required for Visual Studio Code to manage containers on the AWS instance from your local machine.

Mac and Windows users should install Docker Desktop 2.0+, and Linux users will need a distribution of Docker CE/EE 18.06 or newer.

Step 4. Install OpenSSH Compatible SSH Client

You will need a Visual Studio Code supported OpenSSH compatible SSH client installed locally to create an SSH tunnel that Visual Studio Code will use to control Docker on the remote host.

For Windows 10 users, if you’re currently using Putty, I strongly encourage you to use Open SSH instead, as it will save you from frustrating troubleshooting experiences now and in the future.

Step 5. Create SSH Key

If you haven’t already, you’ll need to generate an SSH key and add it to the list of known identities for your SSH client.

Step 6. Create Ubuntu 20.04 AWS instance

Configuring your AWS Ubuntu instance consists of two steps: Uploading or importing your SSH key, then creating the instance.

Step 6.1: Upload Local SSH Public Key to AWS

AWS Lightsail is recommended as it’s the easiest option for creating an Ubuntu 20.04 instance running Docker, but an EC2 instance works just as well if that’s your preference.

Before creating your virtual machine, upload or import your local SSH public key (usually at ~/.ssh/id_rsa.pub) to either Lightsail or EC2.

You can optionally use an SSH key created by AWS, but I recommend using your own if possible.

Step 6.2: Create Ubuntu Instance

The most crucial step is to select your uploaded public key when choosing the SSH key for your instance. If you have an issue connecting via SSH later, it’s almost certainly because you didn’t upload or select your SSH key when creating the instance.

Next, you can use the following code as the launch script that will be run as part of initializing the instance, but you can always run these commands later once logged in via SSH.

Step 7. SSH to the Ubuntu Instance

Once the instance has been initialized, get the IP address from the AWS console, then log in using the following SSH command:

If you’re having trouble connecting, check that the public key you imported into AWS is attached to your instance, and if not, the easiest path forward is to delete, then recreate the instance with your SSH key selected.

If you’re still having connection issues, re-run the ssh command with the `-v` flag to enable the SSH client’s debug mode.

If the debug output still isn’t helping, check out DigitalOcean’s SSH troubleshooting guide, which will hopefully offer additional solutions to try.

Once logged in, you’ll need to install and configure Docker if you haven’t already.

Start by switching to the root user (sudo su), then copy and paste the commands from our Ubuntu installation script.

Step 8. Check Docker Works on AWS

Once the installation commands have been run, log out, then SSH back in and try running a container:

f this doesn’t work, try switching to the root user (`sudo su`), and try running the container.

If you can run the container as the root user, it’s likely a permissions issue with the ubuntu user. In this case, I recommend reading Docker’s documentation on managing Docker as a non-root user, which should fix it.

If all else fails, try rebooting the instance, SSH in again and try running the container as ubuntu again, and if still having trouble, check out Visual Studio Code’s Troubleshooting Guide.

Step 9. Create a Docker Context Locally

It’s time to start putting the pieces together!

Now create a new Docker context locally that will communicate with Docker running remotely via an SSH tunnel.

Open a terminal locally, then run the following command to create a devcontainers context:

Next, you’ll switch from the default context (Docker locally) to devcontainers by running:

Then in the same terminal window, check that the Docker CLI can communicate with Docker on the remote machine by running:

If you could not run the container, check out Visual Studio Code’s SSH Tunneling for Docker guide to help you troubleshoot connection issues.

If you want to switch back to using the default context, run:

Step 10. Try Running a Dev Container

Phew! If you’ve made it this far, you’re now ready to try running a Dev Container remotely!

Open Visual Studio Code, then run the command:

Remote-Containers: Try a Development Container Sample...

Then select one of the available options.

This time you run a Dev Container, it can take anywhere from 5-10 minutes. Visual Studio Code needs first to set up the extension host and Visual Studio Code server before building the Dev Container environment.

Presuming all goes well, you’ll eventually see the files in the container in the Explorer panel, and clicking on Terminal will open a command-line prompt inside the container.

Awesome work!

You’re running Dev Container remotely in the cloud with the experience of coding locally in Visual Studio Code!

Now Bring the Dev Container Workflow to Your Application

This guide has covered the required steps to set up and run Dev Containers remotely on AWS, although the same process applies regardless of which cloud provider you’re using.

Below is a list of additional resources you'll need if implementing at a team level, such as configuring Git credentials so you can push commits from your Dev Container environment.

If you’re new to Dev Containers, I recommend starting with the following videos from Microsoft, then progress to the documentation, as understanding the big picture helps before diving into the documentation.

Feedback is welcome, and you can reach us on Twitter, our Community forum.