code-server on AWS User Guide

Overview

This image runs code-server, the open source project that runs full Visual Studio Code on a server and serves it to any modern web browser. You get the complete VS Code editing experience, the integrated terminal, the extension marketplace, source control and debugging, hosted on your own instance, so your development environment lives next to your code and compute instead of on a laptop.

code-server runs as a Node.js service under a dedicated unprivileged coder service account. It binds to 127.0.0.1:8080 on the loopback interface and is fronted by nginx as a reverse proxy on port 80 (and 443 once you add TLS), with the WebSocket upgrade the editor requires already configured. User settings, installed extensions and workspace state live on a dedicated EBS data volume mounted at /var/lib/code-server, independently resizable and separate from the operating system disk.

On the first boot of every deployed instance, a one-shot service generates a per-instance access password, writes it into the editor configuration, and records it in /root/code-server-credentials.txt with mode 0600. code-server has no username; the password alone signs you in. No shared or default credentials ship in the image.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your developers will reach code-server on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for code-server. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger; the image adds a separate data volume for the user-data store automatically.

Select Launch instance. First boot initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg code-server Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=code-server-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Access Password

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/code-server-credentials.txt

You will see a plain text file containing the code-server URL and the per-instance access password. From the same SSH session you can confirm the deployment is healthy; the health endpoint is open and served by nginx:

curl -fsS http://127.0.0.1/healthz

ok

An ok response confirms nginx is fronting the application. You can also confirm the two services that make up the stack are running:

systemctl is-active code-server nginx

active
active

Step 4: First Sign-in

Open a web browser and navigate to http://<public-ip>/. code-server presents its sign-in page and prompts for the access password.

The code-server sign-in page, served on first boot behind nginx. code-server has no username; the password alone signs you in.

Enter the password from /root/code-server-credentials.txt and select Submit. The full Visual Studio Code interface opens in your browser, with the activity bar, file explorer, editor and status bar.

The full Visual Studio Code editor running in the browser, with a workspace folder open in the file explorer.

Step 5: Open a Folder and Edit

Select File → Open Folder (or use the open a folder link on the Welcome page) and choose a directory on the instance, for example your home directory or a project you have cloned. code-server opens the folder in the explorer just like desktop VS Code. Create files, edit across your project, use search and refactoring, and save with the usual keyboard shortcuts. Everything renders in the browser and runs on the instance.

The first time you open a folder VS Code asks whether you trust its authors. Choose Yes, I trust the authors to enable tasks, debugging and all extensions for that folder.

Step 6: Use the Integrated Terminal

Open Terminal → New Terminal (or press Ctrl + `) to get a shell running on the instance, right next to your code. Run builds, package managers, git and any other command-line tooling without leaving the browser.

The integrated terminal open in code-server, running shell commands on the instance as the coder service user.

The terminal runs as the unprivileged coder user. To run commands that need root, connect over SSH as your instance login user (which has sudo) instead.

Step 7: Install Extensions

Select the Extensions icon in the activity bar (or press Ctrl + Shift + X) to browse and install extensions for your languages and frameworks. Search the marketplace, select an extension, and choose Install. Installed extensions live on the dedicated data volume under /var/lib/code-server, so they persist across restarts.

The Extensions view, browsing and installing VS Code extensions directly in the browser IDE.

Step 8: Enable HTTPS with Let's Encrypt

For any production deployment serve code-server over HTTPS so your session and the WebSocket the editor uses cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d code.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

certbot obtains a certificate and rewrites the nginx server block to serve HTTPS and redirect HTTP; the WebSocket upgrade headers already in the site are preserved. Renewal is handled automatically by the certbot systemd timer.

Step 9: Backups and Maintenance

code-server keeps your settings, installed extensions and workspace state under /var/lib/code-server on the dedicated data volume. Because that is a separate EBS volume you can take a coordinated EBS snapshot of it for point-in-time backups, or archive the tree to object storage:

sudo systemctl stop code-server
sudo tar czf <backup-dir>/code-server-$(date +%F).tgz -C /var/lib code-server
sudo systemctl start code-server

Ship the archive to an Amazon S3 bucket or another object store. To rotate the access password, edit password: in /etc/code-server/config.yaml and run sudo systemctl restart code-server. The services run under systemd; check their state at any time:

systemctl is-active code-server nginx

active
active

Step 10: Scaling and Operations

• Put the web tier behind an Application Load Balancer and terminate TLS there; forward the WebSocket upgrade so the editor connects
• Grow the user-data store by extending the EBS data volume and running sudo resize2fs on /var/lib/code-server
• Give each developer their own instance for an isolated, reproducible environment, or share one instance across a small team
• Pin the code-server version for a fleet by controlling which AMI version you launch

The official code-server documentation is available at https://coder.com/docs/code-server.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general code-server questions consult the documentation at https://coder.com/docs/code-server. code-server is a trademark of Coder Technologies, Inc.; use here is nominative and does not imply affiliation or endorsement.