Skip to main content

Self-Hosting

LiveCodes is a client-side app. It can be easily self-hosted on any static file server or CDN.

All core functionalities (e.g. editors, compilers, formatters, code execution, etc) run in the browser. However, some minor features require external services (e.g. sharing short URLs, broadcast, etc). If you also want to self-host these services, you can use the Docker setup (for VPS) or the PHP setup (for shared hosting).

Guide​

The built app can be obtained using any of the following methods:

Download a Release​

Download the app from the releases, extract the folder and add it to your website.

Build from Source​

Fork the GitHub repo and clone it. You may wish to use the included setup to deploy to GitHub Pages:

git clone https://github.com/{your-username}/livecodes
cd livecodes
npm install
npm run build      # build the app to "build" directory
npm run serve      # locally serve to http://localhost:8080

# deploy
npm run deploy     # build and deploy to GitHub Pages

# for development
npm start          # start local development with code watch, rebuild and live-reload

Git Integration​

Fork the GitHub repo and use one of the hosting services that integrate with GitHub to allow automatic deploys on code push (e.g. Cloudflare Pages, Netlify, Firebase, etc.). When prompted, the build command is npm run build and the build output directory is build.

Additionally, several GitHub Actions workflows are included to automatically build and deploy the app when a new commit is pushed (e.g. to the main branch). Deploy targets include GitHub Pages, FTP and SSH. See the Deployment guide for the available deploy actions, when they are triggered, and the required secrets and variables.

Docker Setup​

In addition to the static app provided by the previous methods, the included Docker setup provides alternative implementations for server-side features available in the hosted app, e.g. automatic HTTPS, Open Graph meta tags, oEmbed, custom headers, short-URL share, broadcast server, separate origin sandbox to run code, custom 404 page, etc.

docker-compose up -d

By default, the app is served at https://livecodes.localhost.

For customization and detailed guide, see Docker setup docs.

PHP Setup on Shared Hosting​

For shared hosting that supports PHP and MySQL, the included PHP setup provides the same services as the Docker setup, without installing anything on the server. It is deployed via FTP/SSH using the included GitHub Actions workflow.

Deployment​

For continuous deployment, you can use the included GitHub Actions workflows to automatically build and deploy the app when a new commit is pushed (e.g. to the main branch).

Deploy targets include GitHub Pages, FTP, SSH, the Docker setup (VPS) and the PHP setup (shared hosting).

See the Deployment guide for the available deploy actions, when they are triggered, and the required secrets and variables.

Custom Build​

By default, when building the app, it is expected to be hosted on the root of the domain/subdomain (e.g. https://my-website.com or https://playground.my-website.com). The documentation is also hosted in the /docs/ directory (e.g. https://my-website.com/docs/).

If you wish to host the app in a subdirectory (e.g. https://my-username.github.io/playground/), the base URL of the app needs to be supplied by the environment variable BASE_URL during build.

Example:

npx cross-env BASE_URL="/playground/" npm run build

If you do not want to build documentations and instead direct all documentation links to https://livecodes.io/docs/, use the following command:

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

Services​

Some of the services used by the app are not supported on static self-hosted deploys and are either replaced by other compatible services (e.g. the share service uses dpaste for short URLs, which are deleted after 365 days) or require you to provide an alternative service (e.g. Firebase configuration for authentication).

You may wish to use the included Docker setup (for VPS) or PHP setup (for shared hosting) to self-host these services.

info

LiveCodes sponsors (Bronze sponsors and above) get access to a hosted Docker setup with managed services.

Examples​

Static App on GitHub Pages​

This is an example of a self-hosted deployment, that was deployed to GitHub Pages using the built-in setup:

https://live-codes.github.io/livecodes/

Docker Setup on VPS​

This is an example of a self-hosted deployment, that was deployed to a VPS using the included Docker setup:

https://vps.livecodes.io

PHP Setup on Shared Hosting​

This is an example of a self-hosted deployment, that was deployed to shared hosting using the included PHP setup:

https://self-hosted.livecodes.io

SDK Usage​

The SDK can still be used with the self-hosted app by providing the appUrl embed option.

index.js
import { createPlayground } from 'livecodes';

const options = {
  appUrl: 'https://playground.my-website.com',
  template: 'react',
  // other embed options
};
createPlayground('#container', options);
Sponsors