diff --git a/Readme.md b/Readme.md index 00189de4..20c8fc0b 100644 --- a/Readme.md +++ b/Readme.md @@ -19,7 +19,7 @@ The application layer may be defined in a single Nix file. This repository contains the application layer for running the Dividat Play web app and supporting system services in a fullscreen kiosk. -See the [documentation](docs/arch) for more information. +See the [documentation](docs/arch) and [user manual](docs/user-manual) for more information. ## Quick start @@ -43,24 +43,70 @@ For example: `nix build --arg buildInstaller false --arg buildBundle false` will A virtual machine (with test instrumentation) can be started without any of the above builds. -### Virtual machine +## Components -A helper is available to quickly start a virtual machine: +### Controller -``` +The [controller](controller/) service orchestrates the system's self-update and acts as a configuration interface for the options exposed to the user. It may be run directly on a Linux host for development purposes. + +### Kiosk + +The [kiosk](kiosk/) browser is used in the default configuration of PlayOS to run any web application in a full screen kiosk. It can be run directly on most hosts for development purposes. + + +## System Testing + +To test integrated portions of the PlayOS system, there are several options/levels available: + +- Running a single system partition with QEMU (fast, partial, isolated) +- Running a full system inside a virtual machine such as VirtualBox (slow, simulated full, isolated) +- Running a single system partition from a USB stick on a physical machine (medium fast, partial, isolated) +- Running a full system on a physical machine (slow, full, isolated) + +### QEMU VM + +Most changes to system configuration and/or the controller can be tested in a virtual machine. +To create and run a VM, run: + +```bash ./build vm +./result/bin/run-in-vm ``` In order to get the vm system journal, look at the output of `run-in-vm` for a command starting with `socat`. -See the output of `run-in-vm --help` for more information. +See the output of `./result/bin/run-in-vm --help` for more information. #### Guest networking -The default user-mode network stack is used to create a virtual Ethernet connection with bridged Internet access for the guest. If you find that the guest has a dysfunctional Internet connection, check your host's firewall settings. If using ConnMan, restart ConnMan service and try again. +The default user-mode network stack is used to create a virtual Ethernet connection with bridged Internet access for the guest. If you find that the guest has a dysfunctional Internet connection, check your host's firewall settings. If using ConnMan on the host, restart the ConnMan service and try again. + +### VirtualBox VM + +PlayOS can also be tested on a VM like VirtualBox, which can simulate a system more fully, including the installer, Grub and A/B partitions. Guidance for setting this up can be found [here](./docs/arch/Readme.org#installation-on-virtualbox). + +### Testing on PlayOS hardware + +Changes such as NixOS upgrades, or to anything else that directly interacts with system hardware may necessitate testing on physical hardware. This can be done by booting from a live system or performing a complete installation. + +To build only a live system: + +```bash +nix-build --arg buildInstaller false --arg buildBundle false --arg buildDisk false +``` + +To build only an installer: + +```bash +nix-build --arg buildLive false --arg buildBundle false --arg buildDisk false +``` + +Flash the ISO in `./result/` to a USB stick and boot or install PlayOS. + +Building a complete system takes time, so it is a good idea to test at the component or QEMU VM level first, where possible. -## Testing +### Automated Testing Subcomponent tests using the [NixOS test framework](https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests) may be added to `test/integration`. diff --git a/build b/build index acedea07..0d5eceaf 100755 --- a/build +++ b/build @@ -25,12 +25,20 @@ if [ "$TARGET" == "vm" ]; then --arg buildLive false \ --arg buildDisk false) - echo - echo "Run ./result/bin/run-in-vm to start a VM." - echo - echo "- unfocus: ctrl-alt-g" - echo "- quit: ctrl-alt-q" - echo "- tty: ctrl-alt-2, sendkey ctrl-alt-f1, ctrl-alt-1" +echo -e " +Run ./result/bin/run-in-vm to start a VM. + +QEMU Shortcuts: +- Grab/release cursor: ctrl-alt-g +- Quit: ctrl-alt-q + +PlayOS shortcuts: +- Toggle controller: ctrl-shift-f12 + +You can switch virtual consoles in the guest via QEMU monitor (ctrl-alt-2), sending a key combination via 'sendkey , and returning to QEMU display (ctrl-alt-1). +- Status console: ctrl-alt-f8 +- Graphical system: ctrl-alt-f7 +" elif [ "$TARGET" == "develop" ]; then diff --git a/controller/Readme.md b/controller/Readme.md index 1e2cdb0b..82983d7c 100644 --- a/controller/Readme.md +++ b/controller/Readme.md @@ -14,9 +14,34 @@ PlayOS controller is an OCaml application that manages various system tasks for - `server/`: main application code - `bin/`: binaries to start a dev server +## Prerequisites + +Since the controller uses `Connman` for managing networks, it must be configured on your host if you want to run the controller directly. + +You should be able to build and run the controller on any Linux system, using the Nix package manager. + +If you are on NixOS, a minimal setup can be achieved as follows (remember to fill in ``): + +```nix +{ pkgs, config, ... }: +{ + networking = { + hostName = ; + wireless.enable = true; + networkmanager.enable = false; + }; + + services.connman = { + enable = true; + networkInterfaceBlacklist = [ "vboxnet" "zt" ]; + }; +} +``` + +Note the `networkmanager.enable = false` and check for any conflicting existing configuration. + ## Quick start -Prerequisites: `connman` must be running on your system. Run `nix-shell` to create a suitable development environment.