Web UI

Docker-based web UI

As mentioned in the Readme, the easiest way to try out ORDeC including its web UI is using Docker:

docker pull ghcr.io/tub-msc/ordec:latest
docker run --rm -p 127.0.0.1:8100:8100 -it ghcr.io/tub-msc/ordec:latest

Then, access the web interface via the generated URL and try out examples.

For serious work, you likely want to use your own local files and text editor instead of the text editor integrated in the web UI. To do so, you can create an ORD file my_design.ord (or a Python file my_design.py) and then run the Docker-based web UI in local mode:

docker run --rm -p 127.0.0.1:8100:8100 -v .:/designs -w /designs \
    -it ghcr.io/tub-msc/ordec:latest ordec -l 0.0.0.0 -p 8100 \
    --no-browser --url-authority 127.0.0.1:8100 -m my_design

The web UI will automatically refresh when it detects changes to my_design.ord.

As projects grow, you can split them into multiple files or create a Python Package, e.g. a folder my_design containing an __init__.py file and your other .py or .ord files.

Launching the web UI in a custom installation

You can also install ORDeC without Docker, e.g. using the ORDeC PyPI package and then launch the web UI using the ordec command.

ordec is the command line tool to start the web UI of ORDeC, the custom IC design platform.

There are three recommended setups to run the ordec web UI:

  1. Combined frontend + backend server with regular installation: A regular installation of ORDeC includes a compiled version of the frontend (webdist.tar). In this case, ORDeC can be started through a simple ordec.

  2. Combined frontend + backend server with editable installation: In case of a editable installation (“develop mode” / pip -e), setup (1) is not supported, as webdist.tar is not available in the package. Instead, the frontend can be build separately through ‘npm run build’ in the web/ directory. The build results must then be supplied to the ordec command: ordec -r [...]/web/dist/

  3. Separate frontend + backend server for frontend development: In the web/ directory, run the Vite frontend server using ‘npm run dev’. Then, separately start the backend server using ordec -b. This gives the best development experience when working on the frontend code. In this setup, the Vite server acts as proxy for the backend server. Thus, you should use the browser only to connect to the Vite server / port.

Furthermore, there are two modes in which you can use the ORDeC web UI:

  1. Integrated mode: The source code is entered through the web UI’s integrated editor. The design is rebuilt automatically when the source is changed. The entered source code is not saved anywhere. Please save any code that you want to keep manually using copy & paste to local files.

    Unless --module (-m) is specified, the web UI is launched in integrated mode.

  2. Local mode: Source code is entered and stored in the local file system. An editor outside the web browser is used. The design is rebuilt automatically when it is detected that source files have changed. This is done using inotify.

    By specifying --module (-m), the web UI is launched in local mode.

    The specified module name (e.g. --module mydesign) is treated as regular Python module import. It could reference a single Python file mydesign.py, a single ORD file mydesign.ord, or a directory mydesign/ containing an __init__.py (which enables projects / packages with multiple modules / source files). Hierarchical names such as mydesign.submodule are permitted as well.

Integrated mode is recommended for demo purposes and getting started. Local mode is likely preferrable for bigger projects.

The mode is selected purely using URL parameters passed the frontend. Every running server supports both integrated and local mode. /app.html?example=nand2 opens example nand2 in integrated mode. /app.html?module=mymodule&view=CellA().schematic opens mymodule in local mode and shows CellA().schematic.

Security

To prevent unauthorized users from gaining access and executing arbitrary code through ORDeC, a new authentication token is generated on each start of the ordec server (similar to https://jupyter-server.readthedocs.io/en/latest/operators/security.html). This token-based authentication is also important in localhost / single-user setups to prevent privilege escalation. The authentication token is passed to the frontend using the auth= query parameter. From there, it is stored in the browser’s localStorage and sent to the server at the start of each websocket connection.

In combination with access to the web server, the authentication token allows executing arbitrary code in the context of the user running ordec. Therefore, the authentication token must be kept secret.

CSRF protection: The authentication token empowers the browser to execute arbitrary Python code on the ORDeC server. This opens up some scenarios on which an attacker could execute arbitrary code by linking to a running ORDeC web UI instance. This is a form of cross-site request forgery (CSRF). Links that open the web UI in integrated mode are considered safe, as only the predefined and safe examples can be run. However, links that open the web UI in local mode are a potential danger, as they can import (i.e. run) arbitrary locally available Python modules, which is unsafe in itself. Moreover, arbitrary code can be passed and executing through the view name in the URL’s query string. To prevent this, in local mode, module and view name must be authenticated using an HMAC-SHA256 code passed through the query string. The authentication token, known to the web UI and the server, is used as shared secret. This HMAC is verified in client-side Javascript, before the websocket connection is established.