Running a web app

A web app, such as a Flask site or an API, runs inside your workspace. To open it in a browser, it has to listen on 0.0.0.0 on one of your ports. To share it, give it a public URL.

1. Listen on 0.0.0.0

Many frameworks listen on 127.0.0.1 (localhost) by default. That address only answers inside your workspace, so the URL the framework prints, such as http://127.0.0.1:5000, will not load in your browser. Bind to 0.0.0.0 so CS Room can route traffic to the app. In Flask:

import os

app.run(host="0.0.0.0", port=int(os.environ["PORT_START"]))

flask run with no options already does this, because CS Room sets FLASK_RUN_HOST and FLASK_RUN_PORT for you. Other frameworks:

# Node / Express
app.listen(process.env.PORT_START, "0.0.0.0")

# Python's built-in server
python -m http.server $PORT_START --bind 0.0.0.0

2. Use one of your ports

Your workspace has ten ports, for example 10000 through 10009, and a port outside that range cannot be reached. The top two are reserved for the graphical display and the Preview tab, which leaves eight for your apps.

Your range is in $PORT_START and $PORT_END. $PORT_END is the last of all ten, which is reserved, so count up from $PORT_START. The Ports button at the right end of the terminal's tab bar shows the range you can use.

3. Give it a public URL

Click Ports, check the port (the lowest one without a URL is filled in), type a name, and click Add subdomain. Anyone can open the HTTPS address you get. It is on your region's app domain, such as https://your-name.app.nyc0.csroom.org, and the panel lists it.

Names are 3 to 32 lowercase letters, digits and hyphens, and cannot start or end with a hyphen. Some names, such as www, api and admin, are reserved, as is anything starting with gui- or preview-.

You rarely need to open the panel yourself. When a server starts on one of your ports and has no URL yet, a notice appears with a Give it a URL button, which opens the panel with that port filled in. If the server cannot be reached, the notice says why: it is bound to 127.0.0.1, or its port is outside your range.

Preview a page without a public URL

HTML, CSS and JavaScript sites and PHP pages don't need a server of your own. Open the .html or .php file and click Preview. The page opens in a Preview tab beside your files, reloads whenever a file changes, and stays loaded while you switch back to your code.

Only you can open the preview. It serves your whole workspace with its folder layout, so relative links, stylesheets and scripts load as they would on a real site. To share the site, run your own server on one of your ports and give it a public URL.

PHP pages run on PHP 8 and can use SQLite through PDO. A .php file also has a Run button, which runs it as a command-line script in the terminal.

Troubleshooting

• The app says it is running, but the page will not load. It is bound to 127.0.0.1. Bind it to 0.0.0.0 as in step 1.
• "Address already in use." Another process has that port. Use a different port in your range, or stop the other process.
• The URL loads for me but not for others. Check that you added a subdomain in the Ports panel. Others cannot reach the port without one.