Skip to main content
Prerequisites:
  • Docker and Docker Compose (recommended)
  • Node.js 24.4.1 or higher (for manual deployment)
  • Basic understanding of web server configuration
LiveCodes is designed to be easily self-hosted on your own infrastructure, giving you complete control over your code playground instance. This guide covers multiple deployment approaches.

​
Quick Start with Docker

The fastest way to get LiveCodes running is using Docker Compose:
1

Download the release

Download the latest release from the GitHub releases page:
wget https://github.com/live-codes/livecodes/releases/latest/download/livecodes.tar.gz
tar -xzf livecodes.tar.gz
cd livecodes
2

Configure environment variables

Create a .env file in the root directory:
# Required: Your domain name
HOST_NAME=livecodes.yourdomain.com

# Optional: Custom ports (defaults shown)
PORT=443
SANDBOX_PORT=8090
BROADCAST_PORT=3030

# Optional: Enable/disable features
SELF_HOSTED_SHARE=true
SELF_HOSTED_BROADCAST=true

# Optional: Broadcast authentication
BROADCAST_TOKENS=token1,token2,token3

# Optional: Firebase config for GitHub auth
FIREBASE_CONFIG={"apiKey":"...","authDomain":"..."}
The SANDBOX_HOST_NAME must be on a different origin than HOST_NAME for security isolation. Use a subdomain like sandbox.yourdomain.com.
3

Launch the services

docker-compose up -d
This starts three services:
  • app: The main LiveCodes application
  • valkey: Redis-compatible database for sharing features
  • server: Caddy reverse proxy for HTTPS
4

Verify deployment

Access your LiveCodes instance:
curl https://livecodes.yourdomain.com

​
Environment Variables Reference

​
Build Arguments

These are set during the Docker build process:
VariableDescriptionDefault
SELF_HOSTEDEnable self-hosted modetrue
SELF_HOSTED_SHAREEnable project sharingtrue
SELF_HOSTED_BROADCASTEnable live broadcasttrue
BROADCAST_PORTPort for broadcast service3030
SANDBOX_HOST_NAMESandbox domain (must be different origin)livecodes.localhost
SANDBOX_PORTPort for sandbox8090
FIREBASE_CONFIGFirebase config JSON for auth-
DOCS_BASE_URLCustom docs URL or null to skip docsnull
NODE_OPTIONSNode.js memory options--max-old-space-size=4096

​
Runtime Environment

These are set when running the container:
VariableDescriptionDefault
HOST_NAMEPrimary domain namelivecodes.localhost
PORTHTTPS port443
BROADCAST_TOKENSComma-separated auth tokens-
LOG_URLExternal logging endpointnull
VALKEY_HOSTValkey/Redis hostvalkey
VALKEY_PORTValkey/Redis port6379

​
Manual Deployment

For deployment without Docker:
1

Build the application

SELF_HOSTED=true \
SANDBOX_HOST_NAME=sandbox.yourdomain.com \
SANDBOX_PORT=8090 \
npm run build:app
2

Install server dependencies

cd server
npm ci
3

Copy build artifacts

cp -r ../build ./
cp -r ../functions ./
cp -r ../src/livecodes/html/sandbox ./src/
4

Configure and start the server

export HOST_NAME=livecodes.yourdomain.com
export PORT=443
export SANDBOX_HOST_NAME=sandbox.yourdomain.com
export SANDBOX_PORT=8090

node src/app.ts

​
Static File Hosting

For the simplest deployment, LiveCodes can run entirely as static files: 
npm run build:app
Upload the build directory to any static file host:
  • Cloudflare Pages
  • Netlify
  • Firebase Hosting
  • GitHub Pages
  • AWS S3 + CloudFront
Static hosting disables server-dependent features like sharing and broadcast. The playground itself works fully client-side.

​
Custom Assets

To use custom assets (logos, themes, etc.): 
volumes:
  - ./custom-assets:/srv/build/assets
Place your custom files in custom-assets/ and they’ll be available at /assets/*.

​
Performance Optimization

​
Memory Configuration

For large deployments, increase Node.js memory: 
environment:
  - NODE_OPTIONS=--max-old-space-size=8192

​
Caching Strategy

The server sets cache headers automatically:
  • /assets/*: 1 year cache (immutable)
  • /livecodes/* (except maps): 1 year cache (immutable)
  • /livecodes/assets/*: 4 hours cache (must-revalidate)

​
CDN Integration

Place a CDN in front of your deployment: 
# Cloudflare, CloudFront, or other CDN
upstream livecodes {
    server livecodes.yourdomain.com:443;
}

proxy_cache_valid 200 1y;
proxy_cache_valid 404 10m;

​
Security Considerations

Always use HTTPS in production. The sandbox must be on a separate origin for security isolation.

​
Origin Isolation

The sandbox runs on a separate origin to prevent:
  • Cross-site scripting attacks
  • Access to parent application data
  • Cookie theft
Valid configurations:
  • Main: https://livecodes.com, Sandbox: https://sandbox.livecodes.com
  • Main: https://code.example.com, Sandbox: https://sandbox.code.example.com

​
CORS Configuration

The CORS proxy endpoint (/api/cors) only accepts requests from:
  • The configured HOST_NAME
  • Localhost/127.0.0.1 (for development)

​
Share Data Persistence

Shared projects are stored in Valkey/Redis with these characteristics:
  • 14-character unique IDs (vs 9 for dpaste, 11 for API)
  • Automatic collision avoidance
  • Configurable persistence with snapshots every 60 seconds

​
Monitoring and Logging

​
Application Logs

docker-compose logs -f app
Look for: 
App is running on https://livecodes.yourdomain.com
Sandbox is running on https://sandbox.yourdomain.com:8090
Broadcast is running on https://livecodes.yourdomain.com:3030

​
External Logging

Configure external logging endpoint: 
LOG_URL=https://logging.example.com/api/log

​
Troubleshooting

Symptom: Code doesn’t execute, sandbox iframe errorsSolutions:
  1. Verify SANDBOX_HOST_NAME is on a different origin
  2. Check DNS resolves correctly for both domains
  3. Ensure HTTPS is configured for both origins
  4. Verify ports 8090 is accessible
Symptom: Projects can’t be saved or loadedSolutions:
  1. Verify Valkey container is running: docker-compose ps
  2. Check SELF_HOSTED_SHARE=true is set
  3. Verify Valkey connection: docker-compose logs valkey
  4. Check network connectivity between app and valkey
Symptom: Live broadcast doesn’t workSolutions:
  1. Ensure SELF_HOSTED_BROADCAST=true
  2. Verify broadcast port (3030) is accessible
  3. Check BROADCAST_TOKENS if authentication is enabled
  4. Verify WebSocket connections aren’t blocked
Symptom: Container crashes or restartsSolutions:
  1. Increase NODE_OPTIONS=--max-old-space-size=8192
  2. Monitor memory usage: docker stats
  3. Consider horizontal scaling
  4. Optimize asset delivery via CDN

​
Upgrading

To upgrade to a new version: 
# Pull new images
docker-compose pull

# Restart with new version
docker-compose up -d

# Clean up old images
docker image prune
Data stored in Valkey persists across upgrades via the livecodes-share-data volume.

​
Next Steps

Docker Setup

Deep dive into Docker configuration

Services Architecture

Understand the service architecture

Security Model

Learn about security features

Performance

Optimize your deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us