Building, installing and maintenance

How to build and deliver the platform, where its data and journals lie, how to check an instance, make a backup and update.

1 General information about the program

1.1 Working conditions

The platform works in Ubuntu inside WSL2. The workshop is a Windows 11 program on the system WebView2; it is started by the function ui. If WSL cannot start Windows programs (for example, in ordinary Linux), the instance works without the workshop.

An instance works while the WSL virtual machine works:

• A long run. The Windows sleep mode and the command wsl --shutdown break a run off; the run goes on from its checkpoint. There are reports that WSL instances are suspended when idle even with a timeout of -1.
• Big data. They are best kept on the Linux disk: Windows files through /mnt/c are read noticeably slower.

1.2 Necessary tools

The work is checked on the following configuration:

• WSL2, Linux x86_64;
• Python 3.11 or newer;
• uv 0.12 or newer — the platform installs the Python environments of processes with it;
• Rust 1.98.0 from rust-toolchain.toml.

Needed:

• Cargo with the components rustfmt and clippy;
• make — short commands for building and checks;
• Linux in WSL2 — for the socket and starting OS processes;
• Windows 11 with WebView2 (it is already in the system) — for the workshop; nothing has to be installed in Windows.

WSL2 administrator rights are not needed to build and run. Real passwords and service keys are not written into the project.

2 The structure of the program

A person installs the platform by the installer of Windows (section 2.1). make pack builds the delivery — the folder dist/ogas/, ready to be unpacked, which the installer puts into Linux:

ogas/
  ogas
  ogas.cmd
  ogas.desktop
  LICENSE                       the licence of the platform, AGPL-3.0-or-later
  NOTICE                        what is under which licence
  THIRD-PARTY-NOTICES.txt       outside packages and the font with the texts of their licences
  assets/ogas-mark.svg
  bin/
    ogas-core
    ogas-graph
    ogas-canvas
    ogas-modules
    ogas-settings
    ogas-i18n
    ogas-observe
    ogas-sources
    ogas-profile
    ogas-ui
    ogas-gate
    ogas-assistant
    ogas-window.exe   the workshop (if built with `make window`)
    ogas-start.exe    the starter for the shortcuts of Windows: the platform with no window of the console (built with the workshop)
  core/kernel/locales/          the words of the kernel
  functions/
    <id>/function.json          the description of a function (File formats, section 3)
    <id>/…/locales/             its dictionaries
  sdk/                           the common code of modules (SDK) without its own checks, with its own licence Apache-2.0
  data/
    config/
    processes/                  empty: processes are the person's work
    runs/
    logs/
    run/

The kernel and the functions are separate executable files from one set of Cargo packages; the code of the functions is not built into the kernel. The delivery is built as a release build (--release): the engine in it is about ten times faster than in the debug one; the debug build target/debug is for working on the platform. The delivery is the platform only: the person's modules and processes, their settings, the layout of windows and runs do not go into it, and the test modules stay with the checks. The wrapper ogas passes --data-dir data relative to the root of the pack; the paths in data/functions.json point to bin/ogas-*. Without the description of any function of the register make pack does not build the delivery: the kernel would not start such a function anyway. The programs of the delivery are built separately, in target/pack, with the build paths replaced (--remap-path-prefix): the home folder, the project folder, the Cargo dependency folder and the toolchain become /home, /ogas, /cargo and /rustup, so the name of whoever built them does not get into the programs; make window builds the window with the same replacement. A program in which a path of this machine stayed make pack does not take, and names it.

make pack
./dist/ogas/ogas doctor
./dist/ogas/ogas start

2.1 The installer of Windows

make installer builds dist/ogas-setup-<version>.exe — an installer like that of an ordinary program of Windows (installer/ogas.nsi, NSIS, 64 bits). It needs makensis (the package nsis of Ubuntu; without administrator rights it is unpacked by apt download and dpkg -x and named by the variables MAKENSIS and NSISDIR) and uv for Linux x86_64 (by default the one on PATH; the variable UV_PROGRAM).

The platform lives in WSL, and it is installed there. The setup goes in three stages, each its own row of screens — a check, questions, a summary of what will be done, the doing with the journal at the bottom of the window, an end; the next stage starts by itself. There are no silent steps: nothing runs before a button is pressed — the checks of stage 1 and stage 3 go on the button «Check», the version of WSL, the updates of Linux and the packages — each on a button of its own, and each command with its answer is seen on the page; the steps of the setup write into the journal what they do before they do it. Each stage is a run of the same installer (/stage=N); the answers pass from stage to stage through its record in the registry, all but the password — it lives only in the memory of stage 1.

1) WSL and Linux. A check of Windows, of virtualization and of WSL: virtualization is not seen — how to turn it on in the BIOS, and whether to go on (Windows does not always show it); no WSL — it is installed (wsl --install --no-distribution), and after the restart stage 1 goes on by itself; WSL installing new Linux on WSL 1 by default — it is said and switched to WSL 2. The Linux for the platform: a fitting one that is here (Ubuntu or Debian, not Docker; its account stays as it is; a Linux on WSL 1 is shown marked and, when chosen, after a warning, is moved to WSL 2: the platform lives on WSL 2 only) or its own «OGAS» — Ubuntu 26.04 LTS by the usual command of WSL (wsl --install -d Ubuntu-26.04 --name OGAS --location <place>\OGAS-linux --version 2 --no-launch) on the chosen disk and in the folder, with a sparse disk and an account whose name and password the person sets right there. During the setup the password is not asked — everything is done as root through WSL; later sudo asks it, as usual. Into Linux the password goes in the environment of one command and is written neither into the journal, nor on a command line, nor on the disk. Then the updates: the version of WSL beside the latest one out (the installer learns it from the page of the releases of WSL on GitHub) and how many packages of the chosen Linux can be updated; when the newest is there, it is said so — «the latest version», when not — updating is offered (wsl --update --web-download, the packages by apt-get upgrade keeping the person's files of settings). Updating WSL stops every Linux that runs, so the installer does it only when the person ticks it — but for the old WSL built into Windows, without which its own «OGAS» cannot be installed; the packages of its own «OGAS» are ticked at once, of a person's Linux — not. A person's Linux itself the installer does not restart. 2) Packages of Linux. The groups of packages from installer/packages.json: what each gives, what for, how much room it takes and whether it is installed already — the installer learns this from the Linux itself; whether an NVIDIA video card is seen (its driver is installed in Windows). The base — Python, environments, checked downloads, uv, systemd — is always installed, the person ticks the rest; packages this Linux does not have the installer does not install and names. In a person's Linux wsl.conf only gets systemd=true when it lacks it; the Linux itself is not restarted.

The groups of packages (installer/packages.json):

3) O.G.A.S. When it is installed already: update (by default); install anew in the same place — the environments and the cache go, the data stays, and with the box «and delete my programs, modules and networks» they go too (the backup stays); change the set of packages (stage 2); for its own «OGAS» — erase it and install it anew: a backup of the data goes to Windows, the setup begins from stage 1, the data comes back at stage 3. When it is not — the folder in Linux, by default ~/ogas. Then the shortcut «O.G.A.S.» in «Start» and on the desktop, an entry among the programs of Windows and «Start O.G.A.S.».

Inside Linux everything is done by installer/setup.sh as root, an action a run: account, survey, packages, install, update, reinstall, backup-out; the checks before any change, all its output into setup.log too. A run with no /stage begins at stage 3 when O.G.A.S. is installed, and at stage 1 otherwise. On Windows stay only the uninstaller, the picture of the shortcut, the log and the starter of the shortcuts ogas-start.exe in %LOCALAPPDATA%\OGAS (the shortcut starts the platform through it, with no window of the console): for its own Linux — in the chosen place, for one that is here — in %LOCALAPPDATA%\OGAS. Uninstalling asks about the data and keeps it by default: its own «OGAS» with «Yes» is deleted whole, in a Linux that is here «Yes» deletes only the folder of the platform — the Linux itself, the packages and systemd stay.

The installer is not signed by a certificate of code: Windows may warn of an unknown publisher at the first start. The installer is a program of 64 bits and runs wsl.exe directly, with no cmd shell: Windows Defender stops unsigned programs that turn off the redirection of the system folder or pass commands through a shell (Behavior:Win32/DefenseEvasion).

make source builds the archive of the sources of the version dist/ogas-<version>-source.tar.gz — everything git holds at HEAD except the working sketches of the author: AGPL asks for the sources to go with the program.

3 Setting the program up

3.1 Preparing Rust

The version of Rust is pinned in rust-toolchain.toml (1.98.0); building on other versions is not guaranteed. The exact versions of dependencies are written in Cargo.lock in the sources, builds and checks go with the flag --locked.

If the root of the project has .cargo/bin/cargo, the Makefile uses it. Otherwise cargo must be in PATH. The wrapper ./ogas itself adds the folders .cargo/bin of the project and ~/.cargo/bin to PATH: a Windows shortcut starts it without a login profile, and otherwise cargo would not be found. From the sources ./ogas builds the platform without the network (--offline): everything needed for the build must already be on the machine. If something is missing, the wrapper refuses and names the command make build, which downloads the packages; the wrapper itself does not go to the network and does not install Rust.

rustc --version
cargo --version

3.2 Checking Python

python3 --version
python3 -m json.tool sdk/tests/doubles/echo/manifest.json

modules/ holds only the person's modules; the common code of modules — OGAS SDK — lies in sdk/. The test modules of OGAS SDK manage with the Python standard library. If a module needs dependencies, its non-empty requirements.txt is not installed by itself: the command module.install is needed. The common code of the exchange is sdk/python/ogas_runtime.py; the PYTHONPATH of a module holds only its folder and sdk/python.

3.3 Building and checking

make build
make lint
make test
make doctor
make pack

3.4 The workshop

The workshop is a Windows program from functions/ui/window (Tauri 2). It is built right in WSL, without Windows tools and without administrator rights:

make window

The result is functions/ui/window/target/x86_64-pc-windows-msvc/release/ogas-window.exe (about 3.7 MB); the function ui finds it itself. make pack puts it into dist/ogas/bin/. If the program lies elsewhere, the path to it is set by the setting ui.window.exe — as WSL sees this path, for example /mnt/e/Concept/ogas-window.exe.

To build the window, these are installed once:

• support of the target x86_64-pc-windows-msvc: the library rust-std of the same Rust version from static.rust-lang.org; the checksum is compared with the release description, installed with install.sh --prefix=<Rust folder>;
• cargo install --locked cargo-xwin — it downloads the Microsoft libraries for building for Windows into ~/.cache/cargo-xwin (about 1.1 GB); the download means agreeing to the Microsoft licence;
• llvm-rc, clang-cl, lld-link, llvm-lib: the Ubuntu packages llvm-21, libllvm21, clang-21, libclang-cpp21, libclang-common-21-dev, lld-21, liblld-21 through apt download + dpkg -x into ~/.local/llvm-21-root, wrappers with these names in ~/.local/bin;
• during the build ~/.local/bin, the cargo folder and ~/.cargo/bin must be in PATH.

The window page (functions/ui/window/ui/) is HTML, CSS and JavaScript modules without Node and a bundler: after a change of the page make window is enough.

3.5 Data

The register of functions is core/data/functions.json, the paths in it point to target/debug/ogas-*; the description of each function lies in its folder, functions/<id>/function.json. If there is no file at the path, the kernel looks for a file with the same name beside itself. make pack rewrites the paths to bin/ogas-* in dist/ogas/data/functions.json.

The person's processes are core/data/processes/<id>/; they are not in git, nor are personal settings.

A run of a process on one's own data folder:

./target/debug/ogas-core run --data-dir core/data --process ID

3.6 Settings

The settings files lie in data/config/ (core.json, system.json, user.json) and in the folder of each process (settings.json). Which file answers for what, in what order they are read and the list of keys — Settings.

The delivery brings core.json and system.json empty: the defaults are kept in the schemas. user.json is the choice of the person who works here; it is neither in the repository nor in the delivery, and is made at the first change in the settings window. layout.json — the layout of the windows of the workshop — is made the same way: the file appears at the first move of a window. When an instance is moved to another machine, both files travel with data/config/.

The platform does not correct an unfit value by itself: a new value is written only after a check by the schema, and is written whole. If core.json or system.json cannot be parsed, the kernel does not start and names the file and the line number.

3.7 Python modules

• The environment. A working process has one Python environment for all its modules: data/processes/<id>/.venv (Modules, section 5). It is made by uv: identical package files of different processes lie on disk once, in the common cache data/cache/uv/, and the environments refer to them. The uv program is named by the setting modules.uv; without it installing refuses with module_uv_not_found. uv can be installed with the command python3 -m pip install --user uv or with the installer from the uv site.
• Installing. Dependencies are installed only by an explicit command — in the workshop or ogas-core install --process ID. Starting a module neither downloads nor installs packages. Network access during installing and the source of packages are provided by the user.
• The interpreter is taken as the first fitting one from the list modules.python_candidates.
• Versions. The versions actually installed are written in requirements.freeze.txt beside the environment; the author of a module pins exact versions in their requirements.txt.

3.8 Passwords and keys

The platform does not keep, give out or manage them. Service keys, tokens and other secrets belong to modules, and the person answers for keeping them. The launch token of a function is kept only in memory.

Secrets must not be put into:

• git;
• process.json and settings;
• journals;
• the command line;
• an export of a process.

A trusted module can still read the environment variables and files the person can reach and go to the network.

4 Checking the program

4.1 Diagnostics

make doctor

Prints the signs of the kernel itself, and then the outcomes of the environment checks the functions of the register declared, with text in the language of the system.

The signs of the kernel: wsl2 — whether the distribution works in WSL2; data_remote_fs — whether the data folder lies on a Windows disk or a network disk (true: a socket cannot be made in it, and the kernel puts it into XDG_RUNTIME_DIR or /tmp, The make-up of the platform, 3.6.1); socket_path and socket_on_linux_fs — which socket path the kernel will take and whether it lies on a Linux file system; registry — whether the register core/data/functions.json is there.

The checks of the functions: sources.curl and sources.sha256sum — whether there are curl and sha256sum, with which the library searches and downloads in sources and compares what is downloaded (Protection, 3.14); ui.wsl_interop — whether Windows programs start from WSL (without it the workshop will not open); ui.window — whether the window program lies in one of its places: bin/ogas-window.exe in the delivery or the build of make window in the sources. doctor does not see the path from the setting ui.window.exe: settings are read by the working platform. graph.wsl_idle_timeouts — whether the idle terms of WSL that matter for long runs are set in .wslconfig.

If there is no register or no fitting socket path, the exit code is 1; the outcomes of the checks of the functions do not change the exit code. doctor does not look for Python (The make-up of the platform, section 5).

4.2 Checking the workshop

The order of the check after installing:

1) run make doctor: the distribution works in WSL2, the checks ui.wsl_interop and ui.window passed (passed); if the window lies elsewhere and the path to it is set by the setting ui.window.exe, ui.window will say failed, and that is no obstacle. For long runs the check graph.wsl_idle_timeouts matters: the idle terms are set by the parameters vmIdleTimeout and instanceIdleTimeout in .wslconfig; 2) open the workshop (./ogas, ogas.cmd or the shortcut) and check the panels, windows, the journal and the link with the platform; 3) look at the workshop with your own eyes: open a program, build and run it.

WSL is updated with the Windows command wsl --update or at stage 1 of the installer, when the person ticks it; the platform itself does not run it.

5 Further possibilities

5.1 Starting

./ogas-core start  --data-dir core/data
./ogas-core ui     --data-dir core/data
./ogas-core run    --data-dir core/data --process ID --text "hello from O.G.A.S."
./ogas-core doctor --data-dir core/data

The same with short commands: make start, make ui, make doctor. A second instance on the same data folder does not appear: the lock is taken, and starting the workshop again asks the working instance to open the window. What each verb does — The make-up of the platform, section 5.

5.2 The command line

ogas-core [start|ui|doctor|backup|stop] [--data-dir PATH]
ogas-core run --process ID [--data-dir PATH] [--text TEXT]
ogas-core install --process ID [--data-dir PATH]
ogas-core program --process ID [--data-dir PATH]

What each verb does — The make-up of the platform, section 5. In short: start and ./ogas start the functions together with the workshop; run runs a process without a window and stops the instance; install installs the environment of a process; program starts the platform with the workshop, switches the program of the process on and shows its face instead of the workshop, and if the platform already works — asks it to do so (The workshop, 6.6). Verbs about a process without --process refuse with exit code 1: there is no ready process that would put itself in. backup makes a backup (5.6), stop stops the running platform as leaving the window does and waits for its end. The verbs other than start, ui, doctor, backup and stop, and their arguments, are described in the register of functions (File formats, section 3); ogas-core --help lists them.

5.3 Working without Make

cargo build --workspace --locked
cargo test --workspace --locked
python3 -m unittest discover -s sdk/tests -p 'test_*.py'
python3 -m unittest discover -s scripts -p 'test_*.py'
./ogas

These are make build, make test and starting. The checks of the person's modules in modules/ are not part of this: the author of a module runs them.

5.4 Stopping and failure

The order of an ordinary stop:

1) forbid new runs; 2) send cancel to active modules; 3) wait the allotted time; 4) force the remaining OS processes to end; 5) close the functions; 6) finish writing the journals; 7) take off the lock.

After a crash of the kernel a new start:

• finds unfinished runs: the function of the graph, when introducing itself to the kernel, turns running into interrupted;
• checks the checkpoint and the generation of documents;
• offers to resume a run only where it is safe (resume.allowed, confirm_non_idempotent).

A backup does not answer the question whether a module managed to do its outside action.

On a failure of the workshop (unlike closing it) the function ui does not restart it: the instance works without a window. To bring the window back, the shortcut is started again: the second start will ask the working instance to open the window and end at once (The make-up of the platform, 3.6.3).

5.5 Journals

Table 1 — Journals

A journal request with run_id reads the file of this run, if there is one. The workshop shows the state of the kernel and the functions, the current run, problems, the events of the platform and of the process. The platform sends nothing out.

5.6 Backup and moving

A backup is made by the command ./ogas backup; the installer makes one itself before it puts a new version in place. A backup is one file ogas-<time>.tar in the folder of the setting core.backups_dir (empty — backups in the folder of the installation; a folder of Windows may be chosen, and trouble with the disk of the platform does not touch the copy). As many of the last backups are kept as core.backups_keep says; older ones go when a new one is made.

A backup holds what the platform does not make again:

• the data folder — as data/: the processes with everything of their own (documents, the memory of nodes, files, runs with their results), the settings, the journals;
• the folders the parts named for a backup — as places/<name>/: the installed modules.

Left out: data/run/, the common cache of packages data/cache/, the environments .venv — they are installed again on the spot —, downloads not taken in yet, and the folder of networks: it is large, and networks are taken from their sources. A network of one's own that cannot be downloaded is copied apart. Where each folder lay is said by data/places.json inside the backup. To bring a backup back — stop the platform and unpack data/ in place of the data folder, and places/<name>/ in place of that folder.

Handing a process over. process.export writes an export of a process — the folder data/exports/<process_id>/ with the documents of the process and the files of its modules as they are (File formats, 10.1). The folder is handed to another person in any way — an archive, a flash drive, a cloud; the platform does not choose the way.

Before adding, process.inspect shows what the export will bring: the name of the process, the modules with their human names, the size, what a module will download when the environment is prepared, the print, and whether such a module is here — no, the same, or another. The platform does not show the rights of a module: there is no sandbox, and «rights» would be a promise nobody keeps (Protection, 3.1).

process.import makes a process here from an export:

• the id is taken — the copy gets a free one (workshop-2), and the documents are rewritten to it;
• a module that is not here is installed from the export; an installed one is not overwritten and goes into modules_skipped together with a sign whether the content matched;
• the Python environment is not part of the export: after adding it is installed anew;
• an export with a link inside a module or with a module whose content does not match its print is refused;
• each document of the process is taken by its owner, who checks it: the pulpit — the function of the pulpit, the values of the settings of the process — the function of settings, the versions of modules — the function of modules; the graph of the process is written last, so an export the owner did not take makes no process.

5.7 Updating

The platform is updated by replacing the executable files and dictionaries; updates are released on the site ogas.space. The order of updating:

1) stop the instance; 2) save a backup of the data; 3) check the compatibility of formats; 4) check the functions and modules; 5) only then open the workshop.

The platform does not open a document of another version of its format and says so; going back to the former executable files brings back the former formats too, so a backup of the data is saved before updating.

6 Messages to the system programmer

Error codes, their owners and the conditions they arise in — Error codes. The records of the kernel journal and the journal of observation — File formats, section 13.