This guide makes it easy to set up a self-hosted instance of LiveCodes on a VPS using Docker.

LiveCodes is a client-side app. It can be easily self-hosted on any static file server or CDN (See Self-Hosting guide).

All core functionalities (e.g. editors, compilers, formatters, code execution, etc) run in the browser. However, some features require external services which depend on server-side implementations (e.g. sharing short URLs, broadcast server, etc). The docker setup described here provides out-of-the-box implementations for self-hosting these services. See below for the list of provided services.

This allows self-hosted instances to have the same features as the hosted app (livecodes.io).

:::warning Note Most self-hosted instances will not require this setup. The static app should work just fine using other simpler self-hosting methods. Only use the docker setup if you need to self-host these services. :::

This is an example of a self-hosted instance deployed to a VPS using the included Docker setup:

https://vps.livecodes.io/

Setting it up can be as simple as running the following command:

HOST_NAME=vps.livecodes.io docker compose up --build -d

• Docker and Docker Compose (installation guide)
• Git: optional - for pulling updates (installation guide)

#!/bin/bash

# Update package lists
sudo apt update

# Install Docker
sudo apt install -y ca-certificates curl gnupg lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

# Add current user to docker group
sudo usermod -aG docker $USER
newgrp docker # Apply group changes immediately

# Install Docker Compose
sudo apt install -y docker-compose

# Install Git
sudo apt install -y git

chmod +x install_docker_ubuntu.sh

sudo ./install_docker_ubuntu.sh

docker --version
docker compose version
git --version

:::info note When running in a non-local environment (e.g. VPS), make sure your domain's A/AAAA DNS records properly point to the machine public IP before running the docker containers. The hostname should be set using environment variables. :::

Clone the repo:

git clone https://github.com/live-codes/livecodes.git

Enter the directory:

cd livecodes

Optionally, checkout a specific branch:

git checkout main

Run docker compose:

docker compose up -d

By default, the app is served at https://livecodes.localhost
(Yes, localhost can be served over HTTPS and have subdomains!).

The hostname and many other options can be set using environment variables.

• Automatic HTTPS

  This is provided by Caddy server, which automatically obtains and renews TLS certificates. Local addresses (e.g. localhost, livecodes.localhost) are served over HTTPS using locally-trusted certificates.

• Open Graph meta tags

  Provide project-specific meta tags, for social media cards.

• oEmbed

  Allows embedded representations on third party sites.

• Adding headers

  e.g. aggressive caching of static assets for improved performance.

• Short-URL share service

  Generates a short URL that can be shared. The project config is stored in a Valkey store (a Redis fork with a permissive open-source license). Data is persisted to disk every 60 seconds (See Volumes section below).

• Broadcast server

  Broadcasts updates to connected clients.

• CORS proxy

  Allows importing content from external URLs.

• Separate origin sandbox

  Runs code in a separate origin sandboxed iframe to prevent cross-site scripting.

• 404 page

  Custom 404 page for resources that are not found.

The app can be customized by setting different environment variables.

Environment variables can be defined in a .env file in the root of the repository (on the same level as docker-compose.yml).

HOST_NAME=playground.website.com

Please note that some variables are used during build. So after setting environment variables, the app needs to be rebuilt. e.g.:

docker compose up --build -d

The following environment variables are supported:

:::info note When running in a non-local environment (e.g. VPS), setting the HOST_NAME environment variable is required. It should match the domain name set in DNS records. :::

The following docker volumes are used:

• ./assets - A bind mount for static assets that get served under the app URL (/assets/). This can be used to serve images, stylesheets, custom modules, custom types, etc.
• livecodes-share-data - A named volume where persistent data for the share service is saved. Make sure to backup this.

#!/bin/bash

VOLUMES=("livecodes-share-data")
BACKUP_DIR="./backups"

mkdir -p $BACKUP_DIR

for VOLUME in "${VOLUMES[@]}"; do
  echo "Backing up $VOLUME..."
  docker run --rm \
    -v $VOLUME:/data \
    -v $(pwd)/$BACKUP_DIR:/backup \
    alpine \
    tar cvf /backup/$VOLUME.tar /data
done

echo "Backup complete. Files are in $BACKUP_DIR."

#!/bin/bash

VOLUMES=("livecodes-share-data")
BACKUP_DIR="./backups"

for VOLUME in "${VOLUMES[@]}"; do
  echo "Restoring $VOLUME..."
  docker volume create $VOLUME
  docker run --rm \
    -v $VOLUME:/data \
    -v $(pwd)/$BACKUP_DIR:/backup \
    alpine \
    tar xvf /backup/$VOLUME.tar -C /data --strip 1
done

echo "Restore complete."

For continuous deployment, you can use the included GitHub Actions workflow to deploy to a VPS when a new commit is pushed (e.g. to the main branch).

This assumses that you have followed the Getting Started instructions and have cloned the repo to your VPS.

The workflow uses secrets and variables from your GitHub repo settings for SSH access and setting required environment variables.