Self-hosting a cloud development environment

Customizing the docker image

Setting up code-server is straightforward; we rely on the reputable linuxserver.io community, which offers a mature linuxserver-code-server image that is perfect for our case. We simply follow the provided instructions by creating and tweaking the compose.yaml file, running the container, and making sure all is working correctly.

Next up, we need to customize the image to add SSH functionality to it, since basically no image comes with an SSH server built-in. Fortunately, linuxserver images provide nice options of adding custom scripts and services to the container on startup. That means we can smuggle in a script that installs openssh-server on startup (if not yet installed).

#!/usr/bin/with-contenv bash

set -euo pipefail

# install openssh-server if not there yet
if ! command -v sshd &>/dev/null; then
    apt-get update -qq
    apt-get install -y --no-install-recommends openssh-server
fi

# create basic SSH server configuration in persisted directory
mkdir -p /config/ssh

# generate hosts SSH key, if not yet there
for type in rsa ecdsa ed25519; do
    if [ ! -f "/config/ssh/ssh_host_${type}_key" ]; then
        ssh-keygen -t "${type}" -f "/config/ssh/ssh_host_${type}_key" -N "" -q
    fi
done

# create sshd config, if not there yet
if [ ! -f /config/ssh/sshd_config ]; then
    cat > /config/ssh/sshd_config <<EOF
Port 22
HostKey /config/ssh/ssh_host_rsa_key
HostKey /config/ssh/ssh_host_ecdsa_key
HostKey /config/ssh/ssh_host_ed25519_key
AuthorizedKeysFile .ssh/authorized_keys
EOF
fi

# create runtime dir for SSH daemon
mkdir -p /run/sshd

Easy to forget, but we also need to start this daemon in a separate script on startup.

#!/usr/bin/with-contenv bash
set -euo pipefail

exec /usr/sbin/sshd -D -e -f /config/ssh/sshd_config

The two scripts are fairly thin, but are indeed all we need! The big clue is that the container’s user (usually named abc in linuxserver.io images) has its /config directory as its home directory. When we persist that through a docker volume, we don’t lose any of the files we create or copy there. Our personal SSH key to connect with, git credentials or GPG signing keys, all live in that directory and will still be there when the container gets re-created (for example after an image update).

Having these scripts ready, we now need to add them to the container through docker volumes. Also, to avoid conflicting with the default SSH daemon running already on the server, we most likely want to map the container’s SSH port to something different.

services:
  code-server:
    image: lscr.io/linuxserver/code-server:latest
    volumes:
      - ./config:/config

      # with these volumes, the image will automatically pick up scripts
      - ./init:/custom-cont-init.d:ro
      - ./services:/custom-services.d:ro
    ports:
      # map SSH port to something other than 22
      - 2222:22

And we are (kinda) done! With this setup we should be able to ssh into the container directly from VSCode! When starting the container, it should show some indication that our supplied scripts were run and we should be able to access the code-server instance from the browser. The SSH server should also be running in the background, and we are ready to connect from our client.

SSHing into the container

Accessing VSCode in the browser is straightforward and easy to verify, so it’s time to test the SSH connection. After installing the appropriate remote development extension in VSCode, we can connect to the container from there.

First, we click on the little icon in the bottom left corner of VSCode, which will open a popup asking us to select or enter a URL for the server we want to connect to. That will be some combination of hostname and/or port number, for example abc@mydomain.com:2222, given that we need to connect to the port the container exposes on our server. After choosing, we will most likely be asked for the password of the container user. While the username is abc, the password needs to be set on the container side with an appropriate ENV variable. Having given correct credentials, we will be dropped into a shell session in the container, the container’s filesystem will show up in the explorer, and we are ready to open or clone a new repository and to develop!

For convenience and security, it’s advisable to use an SSH key rather than user credentials. This can be added the same way as for any SSH server, either by adding your key to authorized_keys or by using ssh-copy-id on the client side. Note that you are free to adjust any SSH related settings by just editing the sshd_config or other SSH related files in the /config dir (remember to set correct permissions).

VSCode remote

When connecting with native VSCode and running a dev server that exposes a port locally, VSCode detects that automatically and forwards the port through the connection. It will even show you a little popup saying “Your application running on port 4321 is available. Click to open in browser”. Then you can simply access that port at localhost:4321 on your device. A little caveat is that you most likely will need to bind the dev server to listen on all addresses for it to be properly proxied through. For example, when using Vite, you simply run the dev server with a special flag vite --host (or set the appropriate setting in the config).

VSCode in browser

How to forward a port in browser-based VSCode depends a bit on how the host server itself handles incoming connections. Generally, code-server exposes the port of a running dev server on a subdomain. That means when your code-server is accessible at https://code.mydomain.com and you run a dev server on port 4321 in code-server, that port will be accessible on https://4321.code.mydomain.com. To access it, you need to do some manual labor, but the specifics depend on how your host server is set up. You most likely are running some form of reverse-proxy to serve your self-hosted applications, for example one that maps code.mydomain.com to the container running code-server. That same reverse-proxy needs to be instructed to also forward https://4321.code.mydomain.com to your code-server container. That can of course be a bit of a hassle, since the port might change depending on the project.

Personally, using traefik, the situation is fairly straightforward and I can share what small configuration serves me well.

services:
  code-server:
    image: lscr.io/linuxserver/code-server:latest
    volumes:
      - ./config:/config
      - ./init:/custom-cont-init.d:ro
      - ./services:/custom-services.d:ro
    networks:
      - reverse-proxy
    ports:
      - 2222:22
    labels:
      # general traefik labels to serve code-server
      traefik.enable: 'true'
      traefik.http.routers.codeserver.rule: Host(`code.mydomain.com`)
      traefik.http.routers.codeserver.entrypoints: websecure
      traefik.http.services.codeserver.loadbalancer.server.port: '8443'

      # this takes care of proxying to [someNumericalPort].code.mydomain.com
      traefik.http.routers.codeserver-ports.rule: HostRegexp(`^\d+\.code\.mydomain\.com$`)
      traefik.http.routers.codeserver-ports.entrypoints: websecure
      traefik.http.routers.codeserver-ports.service: codeserver
      traefik.http.routers.codeserver-ports.tls.domains[0].main: code.mydomain.com
      traefik.http.routers.codeserver-ports.tls.domains[0].sans: '*.code.mydomain.com'

The magic here is to not only bind the base domain code.mydomain.com to the container, but also dynamically bind any numerical subdomain (aka port number) to the same container, while also requesting a wildcard SSL certificate for any subdomain. And voilà, port forwarding works smoothly in the browser, too!

Additional software

To add installation of other arbitrary packages permanently to the image, we can use a second installation script, run at startup.

#!/usr/bin/with-contenv bash

set -euo pipefail

# define additional packages to add
PKGS=(zsh tmux)
MISSING=()

for pkg in "${PKGS[@]}"; do
    command -v "$pkg" &>/dev/null || MISSING=("${MISSING[@]}" "$pkg")
done

if [ ${#MISSING[@]} -gt 0 ]; then
    apt-get update -qq
    apt-get install -y --no-install-recommends "${MISSING[@]}"
fi

# set default user shell to zsh
usermod -s /usr/bin/zsh abc

This script can be modified to install many other things or set up other related tools.

Of the packages shown here, tmux is something I greatly recommend; it’s a terminal multiplexer that’s very popular and convenient in the context of server administration, allowing you to run multiple shell sessions through the same connection, and it also persists your current session even after you disconnect, so that you can always pick up straight where you left off.

GPG keys

It’s good practice to sign git commits with GPG by creating a GPG key pair and telling git to use it to autosign commits. As GPG keys would also get lost during container re-creation, we can add another script that will import all keys in the config dir on startup.

#!/usr/bin/with-contenv bash
set -euo pipefail

if ! gpg --list-secret-keys | grep -q "sec"; then
    gpg --import /config/.gnupg-host/pubring.kbx 2>/dev/null || true
    gpg --import /config/.gnupg-host/trustdb.gpg 2>/dev/null || true
    find /config/.gnupg-host/private-keys-v1.d -name "*.key" -exec gpg --import {} \; 2>/dev/null || true
fi

To use that feature, we of course need to either generate the key files in the container once or copy existing keys (with correct permissions) from elsewhere into the /config dir.