Self Hosting

This skill requires sdk-embedding. Read it first for foundational concepts.

LiveCodes — Self-Host LiveCodes

LiveCodes runs entirely client-side. Host it on any static file server or CDN.

Deployment Options

Download Release

1. Download from GitHub releases
2. Extract the build folder
3. Serve from any static host

bashCopy code
# Files to serve
build/
├── index.html
├── livecodes/
│   ├── assets/
│   └── ...
└── docs/ (optional)

Build from Source

bashCopy code
git clone https://github.com/live-codes/livecodes.git
cd livecodes
npm install
npm run build      # Build to build/ directory
npm run serve      # Local preview at http://localhost:8080
npm run deploy      # Build + deploy to GitHub Pages

GitHub Pages (Built-in)

bashCopy code
# Setup
npm install
npm run deploy      # Deploys to gh-pages branch

Configure CNAME file for custom domain if needed.

Docker

bashCopy code
docker-compose up -d

Docker setup includes:

• HTTPS with auto-certificates
• Share service (short URLs)
• Broadcast server
• Open Graph meta tags
• Custom 404 page

yamlCopy code
# docker-compose.yml
# See: docs/docs/advanced/docker.mdx for customization

Other Static Hosts

• Cloudflare Pages: Connect repo, npm run build, serve build/
• Netlify: Connect repo, npm run build, serve build/
• Firebase Hosting: firebase init hosting, deploy build/

Configure SDK for Self-Hosted App

javascriptCopy code
import { createPlayground } from 'livecodes';

createPlayground('#container', {
  appUrl: 'https://playground.example.com',
  template: 'react',
});

The appUrl tells the SDK where to load the playground iframe from.

Custom Build

Subdirectory Hosting

By default, LiveCodes expects to be at the root of a domain. For subdirectories:

bashCopy code
# Host at https://example.com/playground/
npx cross-env BASE_URL="/playground/" npm run build

This sets <base href="/playground/"> and adjusts all asset paths.

Skip Building Docs

To link documentation to livecodes.io instead of building locally:

bashCopy code
npx cross-env DOCS_BASE_URL=null npm run build:app

Docs links will point to https://livecodes.io/docs/ instead of local docs.

Services

Self-hosted apps use fallback services:

Docker for Full Services

Docker setup provides all services:

bashCopy code
docker-compose up -d
# Serves at https://livecodes.localhost

See docs/docs/advanced/docker.mdx for configuration.

Permanent URL for Stable Embeds

Use versioned URLs to prevent breaking changes:

javascriptCopy code
// Version-specific URL (never changes)
createPlayground('#container', {
  appUrl: 'https://v48.livecodes.io',
  template: 'react',
});

// Pin SDK version
import { createPlayground } from 'livecodes@0.13.0';
// or
import { createPlayground } from 'https://cdn.jsdelivr.net/npm/livecodes@0.13.0';

Permanent URLs format: https://v{VERSION}.livecodes.io

Common Mistakes

MEDIUM Not configuring BASE_URL for subdirectories

Wrong:

bashCopy code
# Build default, serve at /playground/
npm run build
# Results in broken asset paths

Correct:

bashCopy code
# Set BASE_URL for subdirectory
npx cross-env BASE_URL="/playground/" npm run build

Without BASE_URL, the app expects to be at root (/) and asset paths will be wrong.

Source: docs/docs/features/self-hosting.mdx — Custom Build section

MEDIUM Self-hosted share URLs expire

javascriptCopy code
// dpaste.com deletes share URLs after 365 days
// For permanent self-hosted share:
// 1. Use Docker setup for own share service
// 2. Or use permanent URL pattern for embeds

The default dpaste.com service deletes shared URLs after one year. For permanent sharing, use Docker setup with your own share service.

Source: docs/docs/features/self-hosting.mdx — Services section

Examples

GitHub Pages

bashCopy code
# Fork live-codes/livecodes
# Enable GitHub Pages in repo settings
npm install
npm run deploy

# Access at https://your-username.github.io/livecodes/

Cloudflare Pages

bashCopy code
# Build command: npm run build:app
# Output directory: build
# Environment: NODE_VERSION=18

# Access at https://your-subdomain.pages.dev/

Docker VPS

bashCopy code
git clone https://github.com/live-codes/livecodes.git
cd livecodes
docker-compose up -d

# Access at https://livecodes.localhost
# Configure domain in docker-compose.yml