Installing and connecting Web Prolog components

Web Prolog programs can run in an ordinary Prolog process, in a browser, or across several connected nodes. A user interface is a separate component: the Trinity demonstrator is one such interface, and other interfaces can be built for teaching, development or particular applications.

This guide explains the choices before giving local installation recipes. For the implementations and their current conformance coverage, see Proof-of-concept implementations. These are experimental implementations; the facilities available depend on the selected node and version.

1. Nodes and user interfaces

A native node runs as a process on your computer or a server. It executes Prolog and exposes supported query or actor interfaces to other programs. A browser is optional: another Prolog program can be its client. The process must remain running to provide its service.

A browser node executes Prolog inside a web page. The SWI-WASM node bundles a version of SWI-Prolog compiled to WebAssembly, a format browsers can execute. You do not need to install a native Prolog system to use it. Its usual execution mode uses Web Workers, which run computations separately from the page's interface.

A user interface supplies editors, buttons and displays. It can send queries to a native node, host a browser node, or do both. An interface that only sends queries to a native node does not need a Prolog engine in the browser. Conversely, a browser node can execute local programs without any native node.

Closing a page destroys its browser engines. A native service can remain running after a client disconnects, although its session-owned resources may be reclaimed. Saving a program or its results is a separate feature that the chosen interface must provide.

2. Choosing a combination

Common arrangements
What you wantComponentsStart with
Experiment with Prolog entirely in a browserBrowser node and a compatible UIThe minimal browser host
Provide a service for other programsNative node; UI optionalThe native SWI-Prolog node
Use a browser to query a native nodeNative node and a compatible UIThe demonstrator installation
Explore local browser execution and distributed actorsBrowser node, native peers and a compatible UIThe demonstrator installation
Connect different Prolog systemsSeveral native nodes; UI optionalThe individual node guides

Choose nodes by the facilities your application needs. Query support does not imply actor support, and sharing a protocol does not make every language feature interchangeable. The conformance coverage matrix records the combinations that have been tested.

3. Run Prolog in your browser

The SWI-WASM node includes a small independent interface for loading source and running queries. It does not require the demonstrator.

  1. Download swi-wasm-node.tgz from the v0.1.0 release and extract it.
  2. Install Python 3.9 or later if necessary. Open a terminal in the extracted swi-wasm-node directory, the one containing manifest.json.
  3. Start the supplied local file server:
    python3 tools/serve.py --package . --port 8080
  4. Open http://localhost:8080/vendor/swi-wasm-minimal.html in your browser.

Keep the terminal's server running while using the page. It supplies files; the Prolog computation takes place in your browser. Opening the HTML file directly by double-clicking it is insufficient because the runtime needs to load its engine and Worker files through HTTP.

Try member(X,[a,b,c]) and request the next answers. The packaged shared database is empty; supply your own program for application-specific predicates. Save any source you want to keep before closing the page.

4. Run a native SWI-Prolog node

The SWI-Prolog node can run without any demonstrator files. Install Git and a threaded SWI-Prolog first; SWI-Prolog 10.1.19 is the tested baseline for the current implementation. In a terminal:

git clone https://github.com/torbjornlager/swi-prolog-node.git
cd swi-prolog-node
swipl load.pl

At the Prolog prompt, start a node for direct local development:

?- node(3060, [profile(actor), auth(dev)]).

Leave SWI-Prolog running. Open http://localhost:3060/call?goal=true&format=json to check that the node answers a query. This endpoint returns data rather than a graphical interface.

auth(dev) allows execution by direct loopback clients. It is a local development policy, not a deployment recipe for a public server or a server behind a proxy. The option does not itself restrict the listening socket to localhost. Consult the repository's deployment documentation before exposing the service.

5. Install the Trinity demonstrator

The Trinity demonstrator brings together tutorials, editors, native queries and browser execution. For a first installation, serve the UI and native node from the same address. This avoids additional configuration for connections between different websites.

With Git, Python 3 and the tested SWI-Prolog available, run:

git clone https://github.com/torbjornlager/trinity-demonstrator.git
cd trinity-demonstrator
python3 tools/fetch_swi.py --destination .trinity/native
python3 tools/fetch_browser.py --destination .trinity/swi-wasm-node
python3 tools/setup_swi.py --native-root .trinity/native
swipl load.pl

The fetch commands obtain the dependency revisions selected by the demonstrator, and setup assembles the required files. Use fresh destination directories. At the Prolog prompt:

?- node(3060, [profile(actor), auth(dev)]).

Open http://localhost:3060/portal. If you already started the standalone native node on port 3060, stop that process first or choose a different free port and adjust the address. The same local-development authentication qualification applies here.

The demonstrator's settings select browser execution modes and node connections. Begin with the Worker browser runtime. The optional main-thread mode provides DOM access but has different interruption and lifetime constraints. For distributed examples, use the actual addresses of running peers and check their supported facilities.

localhost always means the computer making the connection. A localhost address in a browser on another computer will not reach your server.

6. Other native nodes

The Trealla Prolog node supports queries and actors. Follow its installation instructions for the matching Trealla executable and library files. Its server startup and configuration differ from SWI-Prolog's.

The GNU Prolog node provides ISOBASE query and RPC/promise facilities, rather than the actor interface. Its build currently requires a particular upstream GNU Prolog revision and a C toolchain; consult its own guide for prerequisites and tested platforms.

The Ciao Prolog prototype concentrates on paged text queries over a resident database. Do not assume that a UI written for the actor or JSON interfaces can connect to it unchanged.

7. Separate hosting and CDN distribution

A static UI consists of files a web server sends to the browser: HTML, styles, JavaScript and, if included, the browser runtime. A content delivery network (CDN) can distribute these files. The native node remains a separate running service. Downloading UI files does not install or start a native node.

The demonstrator has tools for packaging a static UI with its browser runtime. An operator can host that package and configure native-node addresses separately. A public CDN installation service is not yet provided. Local tests of connections and authentication from a separate origin have passed; verification over HTTPS with the real SSO deployment remains pending its availability.

An origin is the combination of scheme, hostname and port. Even http://localhost:8080 and http://localhost:3060 are different origins. Browsers require the node or its proxy to explicitly allow cross-origin HTTP requests (CORS), and WebSocket connections need their own origin checks. Merely moving a UI to another port is therefore not a complete setup.

For private nodes, the operator must also configure HTTPS and login. SSO means using a shared sign-in service; login normally happens in a browser page, while API requests use the resulting session. Cookie restrictions can affect connections between unrelated sites. Follow the demonstrator's remote-node and authentication guide for this deployment work.

8. Build your own user interface, with AI assistance

The demonstrator is one possible UI. You might prefer a small query console, a teaching exercise, a statechart editor or an interface that hides Prolog queries behind application-specific controls. Such an interface can host a browser node, connect to native nodes, or combine both approaches.

Working with an AI can be useful here, especially if you know Prolog but have little experience with HTML, CSS and JavaScript. Describe what the user should be able to do, provide a small Prolog program and its expected answers, and ask for an interface built around the existing runtime or node protocols.

We provide a technical brief for UI development that you can give to an AI. It describes the browser runtime's JavaScript interface, native HTTP and WebSocket interfaces, session handling and authentication, with links to the implementation sources. You can also download the brief as a plain text file and attach it to your conversation.

For example:

Read the attached Web Prolog UI development brief. Help me build a small teaching interface that runs Prolog locally using swi-wasm-node. I will supply the Prolog program. Show one answer at a time, provide Next and Stop controls, and let me save my source. Explain the web code as we go. Use the real runtime and test with the example queries I provide.

The AI should check the APIs against your selected implementation and version, and run the resulting interface against a real engine. Generated code still needs review and testing. Keep passwords and sign-in credentials out of the conversation and the published files.

Each new UI should document which nodes and versions it supports, where node addresses are configured, how login and reconnection work, and what is saved when a session or page closes. These details make it possible to use the UI independently of the demonstrator.

Back to proof-of-concept implementations