|
| 1 | +# Docker Setup |
| 2 | + |
| 3 | +LiveCodes is a [client-side app](../why.mdx#client-side). It can be easily self-hosted on any static file server or CDN (See [Self-Hosting guide](../features/self-hosting.mdx)). |
| 4 | + |
| 5 | +LiveCodes core functionalities (e.g. editors, compilers, formatters, code execution, etc) run in the browser. However, some features require [external services](./services.mdx) which depend on server-side implementations. |
| 6 | +This docker setup provides an easy out-of-the-box implementations for self-hosting these services. |
| 7 | + |
| 8 | +## Example |
| 9 | + |
| 10 | +This is an example of a self-hosted deployment, that was deployed to a VPS using the included docker setup: |
| 11 | + |
| 12 | +https://vps.livecodes.io/ |
| 13 | + |
| 14 | +This is the command used to build and run the app: |
| 15 | + |
| 16 | +```sh |
| 17 | +HOST_NAME=vps.livecodes.io docker compose up --build -d |
| 18 | +``` |
| 19 | + |
| 20 | +## Requirements |
| 21 | + |
| 22 | +- Docker |
| 23 | +- Docker Compose |
| 24 | +- Git (optional): for pulling updates. |
| 25 | + |
| 26 | +<details> |
| 27 | +<summary> |
| 28 | +Install Git, Docker and Docker Compose on Ubuntu |
| 29 | +</summary> |
| 30 | + |
| 31 | +This script installs git, docker, and docker compose on Ubuntu: |
| 32 | + |
| 33 | +```sh |
| 34 | +#!/bin/bash |
| 35 | + |
| 36 | +# Update package lists |
| 37 | +sudo apt update |
| 38 | + |
| 39 | +# Install Git |
| 40 | +sudo apt install -y git |
| 41 | + |
| 42 | +# Install Docker |
| 43 | +sudo apt install -y ca-certificates curl gnupg lsb-release |
| 44 | +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg |
| 45 | +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 |
| 46 | +sudo apt update |
| 47 | +sudo apt install -y docker-ce docker-ce-cli containerd.io |
| 48 | + |
| 49 | +# Add current user to docker group |
| 50 | +sudo usermod -aG docker $USER |
| 51 | +newgrp docker # Apply group changes immediately |
| 52 | + |
| 53 | +# Install Docker Compose |
| 54 | +sudo apt install -y docker-compose |
| 55 | +``` |
| 56 | + |
| 57 | +To use this script: |
| 58 | + |
| 59 | +**Save** |
| 60 | + |
| 61 | +Save the script to a file, for example: `install_docker_ubuntu.sh`. |
| 62 | + |
| 63 | +**Make Executable** |
| 64 | + |
| 65 | +Make the script executable with: |
| 66 | + |
| 67 | +```sh |
| 68 | +chmod +x install_docker_ubuntu.sh |
| 69 | +``` |
| 70 | + |
| 71 | +**Run** |
| 72 | + |
| 73 | +Execute the script using: |
| 74 | +```sh |
| 75 | +sudo ./install_docker_ubuntu.sh |
| 76 | +``` |
| 77 | + |
| 78 | +It's recommended to run it with `sudo` to ensure all necessary permissions are granted. |
| 79 | + |
| 80 | +**Verify** |
| 81 | + |
| 82 | +Verify the installations with: |
| 83 | + |
| 84 | +```sh |
| 85 | +git --version |
| 86 | +docker --version |
| 87 | +docker compose version |
| 88 | +``` |
| 89 | +</details> |
| 90 | + |
| 91 | +## Getting Started |
| 92 | + |
| 93 | +Clone the repo: |
| 94 | + |
| 95 | +```sh |
| 96 | +git clone https://github.com/live-codes/livecodes.git |
| 97 | +``` |
| 98 | + |
| 99 | +Enter the directory: |
| 100 | + |
| 101 | +```sh |
| 102 | +cd livecodes |
| 103 | +``` |
| 104 | + |
| 105 | +Optionally, checkout a specific branch: |
| 106 | + |
| 107 | +```sh |
| 108 | +git checkout main |
| 109 | +``` |
| 110 | + |
| 111 | +Run docker compose: |
| 112 | + |
| 113 | +```sh |
| 114 | +docker compose up -d |
| 115 | +``` |
| 116 | + |
| 117 | +By default, the app is served at https://livecodes.localhost |
| 118 | + |
| 119 | +The hostname and many other options can be set using [environment variables](#environment-variables). |
| 120 | + |
| 121 | +## Features |
| 122 | + |
| 123 | +- Automatic HTTPS |
| 124 | + |
| 125 | + This is provided by [Caddy server](https://caddyserver.com), which automatically obtains and renews TLS certificates. |
| 126 | + Local addresses (e.g. `localhost`, `livecodes.localhost`) are served over HTTPS using locally-trusted certificates. |
| 127 | + |
| 128 | +- [Open Graph meta tags](https://ogp.me/) |
| 129 | + |
| 130 | + Provide project-specific meta tags, that show projects title and description on social media cards. |
| 131 | + |
| 132 | +- [oEmbed](https://oembed.com/) |
| 133 | + |
| 134 | + Allows embedded representations on third party sites. |
| 135 | + |
| 136 | +- [Short-URL share service](../features/share.mdx) |
| 137 | + |
| 138 | + Generates a short URL that can be shared. The project config is stored in a [Valkey](https://valkey.io/) store (a Redis fork with a permissive open-source license). |
| 139 | + Data is persisted to disk every 60 seconds (See [Volumes](#volumes) section below). |
| 140 | + |
| 141 | +- [Broadcast server](../features/broadcast.mdx) |
| 142 | + |
| 143 | + Broadcasts updates to connected clients. |
| 144 | + |
| 145 | +- CORS proxy |
| 146 | + |
| 147 | + Allows [importing content](../features/import.mdx) from external URLs. |
| 148 | + |
| 149 | +- Separate origin sandbox |
| 150 | + |
| 151 | + Runs code in a separate origin [sandboxed iframe](https://www.html5rocks.com/en/tutorials/security/sandboxed-iframes/) to prevent cross-site scripting. |
| 152 | + |
| 153 | + |
| 154 | +## Environment Variables |
| 155 | + |
| 156 | +The app can be customized by setting different environment variables. |
| 157 | + |
| 158 | + |
| 159 | +Environment variables can be defined in the `.env` file in the root of the repository (on the same level as `docker-compose.yml`). |
| 160 | + |
| 161 | +```txt title=".env" |
| 162 | +HOST_NAME=playground.website.com |
| 163 | +``` |
| 164 | + |
| 165 | +Please note that some variables are used **during build**. So after setting environment variables, the app needs to be rebuilt. e.g.: |
| 166 | + |
| 167 | +```sh |
| 168 | +docker compose up --build -d |
| 169 | +``` |
| 170 | + |
| 171 | +The following environment variables are supported: |
| 172 | + |
| 173 | +| Variable | Description | Default | |
| 174 | +| --- | --- | --- | |
| 175 | +| `HOST_NAME` | Hostname of the app | `livecodes.localhost` | |
| 176 | +| `PORT` | Port of the app | `443` | |
| 177 | +| `SELF_HOSTED_SHARE` | Enable [share service](../features/share.mdx) | `true` | |
| 178 | +| `SELF_HOSTED_BROADCAST` | Enable [broadcast server](../features/broadcast.mdx) | `true` | |
| 179 | +| `BROADCAST_PORT` | Port of the broadcast server | `3030` | |
| 180 | +| `BROADCAST_TOKENS` | Comma-separated list of broadcast [user tokens](../features/broadcast.mdx#technical-details) | | |
| 181 | +| `SANDBOX_HOST_NAME` | Hostname of the sandbox | `$HOST_NAME` | |
| 182 | +| `SANDBOX_PORT` | Port of the sandbox | `8090` | |
| 183 | +| `FIREBASE_CONFIG` | [Firebase config object](https://firebase.google.com/docs/web/learn-more#config-object) (JSON), used for [authentication](../features/github-integration.mdx) | | |
| 184 | +| `DOCS_BASE_URL` | [Base URL](../features/self-hosting.mdx#custom-build) of the documentation | `null` | |
| 185 | +| `LOG_URL` | URL to send server-side analytics | `null` | |
| 186 | + |
| 187 | +## Volumes |
| 188 | + |
| 189 | +The following directories are mounted as volumes: |
| 190 | + |
| 191 | +- `/data` - Persistent data is stored here (e.g. for Valkey and Caddy). Make sure to **backup** this. |
| 192 | +- `/assets` - Static assets saved here are served on the app URL (`/assets/`). This can be used to serve images, stylesheets, [custom modules](../features/module-resolution.mdx#custom-module-resolution), [custom types](../features/intellisense.mdx#custom-types), etc. |
| 193 | + |
| 194 | +## Deployment |
0 commit comments