Tutorial

Tutorial — Getting Started

This is the primary getting-started walkthrough. It installs Theia on a clean host from the GitHub release .debs plus PyPI, scaffolds a consuming workspace, generates the manifests, and runs the stack. The flow below was validated end-to-end on a clean Ubuntu 22.04 host.

For deeper background see Architecture (the runtime, supervisor, FC catalog), Deployment-Manifest-Generation-and-Serialization (the manifest pipeline), and Advanced-Tools (tdb / rtdb / GUI).

Prerequisites

• Ubuntu 22.04 or 24.04 (the debs are built per-Ubuntu: _ubuntu22.04_ / _ubuntu24.04_).

• etcd at 127.0.0.1:2379 — the per (Persistency) FC needs it. A docker etcd works:

  docker run -d --name theia-etcd -p 2379:2379 quay.io/coreos/etcd:v3.5.9 \
    /usr/local/bin/etcd \
      --advertise-client-urls http://0.0.0.0:2379 \
      --listen-client-urls   http://0.0.0.0:2379

1. Install Theia from the release debs

Download the framework, runtime, runtime-dev, services, and services-dev packages from the GitHub release (substitute the Ubuntu suffix to match your host), then install them together so apt resolves the dependency DAG:

BASE=https://github.com/perotheia/theia/releases/download/v0.1.0
for p in framework runtime runtime-dev services services-dev; do
  curl -fsSL -O "$BASE/theia-${p}_0.1.0_ubuntu22.04_all.deb"
done
sudo apt-get install -y ./theia-*_ubuntu22.04_*.deb

This lays Theia under /opt/theia (the /opt/ros/<distro> analogue): binaries in /opt/theia/bin, runtime sources in /opt/theia/src, the artheia wheel, the Bazel rules, and setup.bash.

Produces: /opt/theia populated; the theia launcher available once you source setup.bash.

2. Create your workspace and venv

You own the Python venv — install artheia and rf-theia from PyPI (both are live at 0.1.0):

mkdir test_ws && cd test_ws
python3 -m venv .venv && source .venv/bin/activate
pip install artheia rf-theia

Produces: a .venv with the artheia CLI and the rf-theia harness.

3. Put Theia on PATH

source /opt/theia/setup.bash        # exports THEIA_ROOT=/opt/theia, puts `theia` on PATH

Produces: THEIA_ROOT=/opt/theia; theia and artheia resolvable.

4. Scaffold the consuming workspace

theia init --with-services          # scaffold this dir as a workspace bound to /opt/theia

theia init writes (never overwriting) system/system.art (the aggregator), manifest/rig.py (a one-machine stub), apps/system/apps/{package,component}.art (your own empty app package, system.apps), and a Bazel module. With --with-services it also symlinks the ARA services (com, log, per, sm, ucm, shwa) from $THEIA_ROOT. Theia itself is not vendored — the runtime/supervisor/services are relative symlinks into /opt/theia.

Produces: the workspace tree with .theia recording the bound THEIA_ROOT.

5. Validate the .art tree

artheia parse system/system.art

This resolves the whole .art tree (the validation pass). A clean parse means every cross-reference, import, and TIPC address resolves.

Produces: no output on success (a non-zero exit + diagnostics on failure).

6. Generate the manifest module

artheia gen-manifest apps/system/apps/component.art apps/manifest/app.py

This serializes the app's .art into the Python manifest module the rig consumes.

Produces: apps/manifest/app.py.

7. Serialize the deploy manifests

theia manifest                      # rig.py → dist/manifest/*.json

This drives the rig through artheia generate-manifest, emitting the four AUTOSAR deploy manifests per machine (dist/manifest/<machine>/{machine,application,service,execution}.json + index.json).

Produces: dist/manifest/<machine>/*.json.

8. Install the runtime layout

theia install                       # deb-mode: stage prebuilt /opt/theia/bin binaries (puppet-free)

In deb mode theia install stages the prebuilt binaries from /opt/theia/bin into the workspace's runtime layout — no Bazel build, no Puppet.

Produces: the staged install/ runtime layout for the supervisor.

9. Start the stack

theia start                         # supervisor forks the 6 service FCs (needs etcd at :2379)

The supervisor fork/exec's the FC daemons. theia start also exports LD_LIBRARY_PATH so per finds libetcd-cpp-api.so.

Produces: a running supervisor with the six service FCs as child processes.

10. Verify

You should see all six FCs running — com, log, per, sm, ucm, shwa — and com's gRPC bridge listening on :7700:

tdb ps                              # the live supervisor tree (com / log / per / sm / ucm / shwa)
ss -ltn | grep 7700                 # com gRPC bridge is up

tdb speaks the supervisor over the local probe/TIPC; rtdb and the supervisor GUI speak it over com's gRPC on :7700. See Advanced-Tools.

11. Stop

theia stop                          # graceful SIGTERM of all workers against one deadline

Produces: all FC processes reaped; the supervisor exits.

Next steps

• Author your own FC: add a composition to apps/system/apps/component.art, then artheia gen-app --kind fc apps/system/apps/component.art --out apps, and re-run steps 6–9.
• Drive it from tests with the rf-theia harness — see MCP-and-Skills.