Deploy Falcon Live Code Server

This guide explains how to deploy your own instance of Falcon, the live code execution engine used to securely run code inside isolated Docker containers.

Prerequisites

Before deploying Falcon, ensure your server meets the following requirements:

• A cloud server (DigitalOcean, AWS EC2, Hetzner, or any VPS)
• Python 3.11 or later
• Docker and Docker Compose
• Git
• Nginx
• A domain name

Step 1: Clone the Repository

Clone the Falcon repository onto your server.

git clone https://github.com/fossunited/falcon
cd falcon

If you maintain your own fork, clone that repository instead.

Step 2: Create the Python Environment

Create a virtual environment and install the required Python dependencies.

python3 -m venv env
source env/bin/activate

pip install --upgrade pip
pip install -r dev-requirements.txt

Falcon requires WebSocket support, so install the standard Uvicorn package.

pip install "uvicorn[standard]"

Step 3: Pull Runtime Docker Images

Falcon executes code inside isolated Docker containers. Pull the supported runtime images.

docker pull fossunited/falcon-python:3.9
docker pull fossunited/falcon-golang
docker pull fossunited/falcon-rust
docker pull frappedevs/falcon-javascript

Step 4: Create a Systemd Service

Create a new service file at:

/etc/systemd/system/falcon.service

Use the following configuration:

[Unit]
Description=Falcon LiveCode Service
After=network.target

[Service]
User=root
WorkingDirectory=/root/falcon
ExecStart=/root/falcon/env/bin/uvicorn livecode_server.server:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

Reload Systemd and start the Falcon service.

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable falcon
sudo systemctl start falcon

To verify the service is running, view the logs.

journalctl -u falcon -f

Step 5: Configure Nginx

Install Nginx if it is not already available.

sudo apt update
sudo apt install nginx

Create a new site configuration:

/etc/nginx/sites-available/falcon

Add the following configuration.

server {
    listen 80;
    server_name falcon.example.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Enable the site and reload Nginx.

sudo ln -s /etc/nginx/sites-available/falcon /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl restart nginx

Enable HTTPS (Optional)

Use Certbot to secure your deployment with SSL.

sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx

Step 6: Test the Deployment

Include the LiveCode client library on your webpage.

const script = document.createElement("script");

script.src = "https://falcon.frappe.io/static/livecode.js";

document.head.appendChild(script);

Create a new LiveCode session.

const session = new LiveCodeSession({
    base_url: "https://falcon.example.com",
    runtime: "python",
    code: "print('Hello')",
    onMessage: console.log
});

If the deployment is successful, you should receive the following response.

{
    msgtype: "welcome",
    message: "welcome to livecode"
}

Troubleshooting