Page about emulated devices

src/SUMMARY.md

@@ -6,6 +6,7 @@
 
 - [Architecture](./architecture.md)
 - [Source code, Building, and Installation](./install.md)
+- [Running on an emulated device](./emulator.md)
 - [Glossary](./glossary.md)
 
 # User and Administration Guide

src/emulator.md

@@ -0,0 +1,84 @@
+# How to get Synit running on an emulated PostmarketOS device
+
+[vouch.id]: https://vouch.id/
+
+Begin by following the [generic PostmarketOS instructions for running using
+QEMU](https://wiki.postmarketos.org/wiki/QEMU_amd64_(qemu-amd64)), reprised here briefly, and
+then build and install the Synit packages and (optionally) the SqueakPhone user interface.
+
+## Build and install `qemu-amd64` PostmarketOS
+
+First, run `pmbootstrap init` (choose `qemu`, `amd64`, and a `console` UI); or, if you've done
+that previously, run `pmbootstrap config device qemu-amd64`.
+
+Then, run `pmbootstrap qemu --video 720x1440@60` to create an emulated PostmarketOS device and
+start it. You'll run that same command each time you boot up the machine, so create an alias or
+script for it, if you like.
+
+## Set up `ssh` access to the emulated device
+
+I have the following stanza in my `~/.ssh/config`:
+
+```
+Host pm-qemu
+    HostName localhost
+    Port 2222
+    User user
+    StrictHostKeyChecking no
+    UserKnownHostsFile /dev/null
+```
+
+Log in to the device using a username and password (`SSH_AUTH_SOCK= ssh pm-qemu`) and set up
+SSH key access via `~/.ssh/authorized_keys` on the device, however you like to do it. I use
+[vouch.id][] to log into my machines using an SSH certificate, so I do the
+following:
+
+```
+mkdir -p .local/bin
+cd .local/bin
+wget https://vouch.id/download/vouch
+chmod a+x
+sudo apk add python3
+echo 'export VOUCH_ID_PRINCIPAL=tonyg@leastfixedpoint.com' >> ~/.profile
+```
+
+Then I log out and back in again to pick up the `VOUCH_ID_PRINCIPAL` variable, followed by
+running
+
+```
+vouch server setup --accept-principals tonyg
+```
+
+(Substitute your own preferred certificate principal username, of course.) After this, I can
+use the [vouch.id][] app to authorize SSH logins.
+
+## Allow port forwarding over SSH to the device
+
+Edit `/etc/ssh/sshd_config` to have `AllowTcpForwarding yes`. This will let you use e.g.
+port-forwarded VNC over your SSH connection to the device once you have the user interface set
+up.
+
+## Build and install the packages
+
+Follow the [build and installation instructions](./install.md) to check out and build the code.
+
+Once you've checked out the `synit` module and have all the necessary build dependencies
+installed, change directory to `synit/packaging/squid` and run `start.sh` in one terminal
+window. Leave this open for the remainder of the build process. Open another terminal, go to
+`synit/packaging`, and run `make keyfile`. Then, run `make ARCH=x86_64`.
+
+Hopefully the build will complete successfully. Once it has done so, change to `synit/scripts`
+and run `./upload-bundle.sh pm-qemu`. Then log in to the emulated device and run the
+`./transmogrify.sh` script from the `/home/user` directory. Reboot the device. When it comes
+back, you will find that it is running Synit (check `ps` output to see that `synit-pid1` is in
+fact PID 1).
+
+## Build and install the user interface packages
+
+If you want to run the SqueakPhone image on your local machine, ensure your Unix user is in the
+`input` group.
+
+squeak-phone: ./push-image-to-phone.sh pm-qemu
+
+set `dpi.override` to have 256 in it
+

src/install.md

@@ -24,24 +24,28 @@ Synit builds upon many existing technologies, but primarily relies on the follow
 
  - Rust nightly and Cargo (perhaps installed via [rustup](https://rustup.rs/)).
 
+ - The rust `cross` tool (even for `x86_64` builds):
+
+   ```
+   cargo install cross
+   ```
+
+ - Docker (containers are used frequently for building packages, among other things!)
+
  - Python 3.9 or greater
 
  - `git`, `ssh`, `rsync`
 
  - Make, a C compiler, and so on; standard Unix programming tools.
 
- - Docker (containers are used frequently for (cross-)building of Alpine packages, among other
-   things!)
-
  - The `preserves-tool` binary installed on your `PATH`:
 
    ```
    cargo install preserves-tools
    ```
 
- - <a id="binfmt"></a>For cross builds (e.g. the very common case of building for `aarch64` on
-   an `x86_64` host), `qemu` and its `binfmt` support. On Debian, `apt install binfmt-support
-   qemu-user-static`.[^debian-qemu-bug]
+ - <a id="binfmt"></a>`qemu` and its `binfmt` support (even for `x86_64` builds). On Debian,
+   `apt install binfmt-support qemu-user-static`.[^debian-qemu-bug]
 
  - Source code for Synit components (see below).
 
@@ -52,7 +56,8 @@ Synit builds upon many existing technologies, but primarily relies on the follow
  - **Great tolerance for the possibility of soft-bricking your phone.** This is experimental
    software! When it breaks, you'll often have to (at least) reinstall PostmarketOS from
    absolute scratch on the machine. I do lots of development using `qemu-amd64` for this
-   reason.
+   reason. See [here](./emulator.md) for [instructions on running Synit on a emulated
+   device](./emulator.md).
 
 ## Get the code
 

src/introduction.md

@@ -19,10 +19,9 @@ Linux's Unix heritage.
 
 ## Quickstart
 
-If you have a mobile phone or computer capable of running
-[PostmarketOS](https://postmarketos.org/), then you can
-[install](./install.md) the software to try it out. You can also run
-Synit inside a virtual machine.
+You can [run Synit on an emulated device](./emulator.md), or if you have a mobile phone or
+computer capable of running [PostmarketOS](https://postmarketos.org/), then you can
+[install](./install.md) the software on your device to try it out.
 
 See the [installation instructions](./install.md) for a list of
 supported devices.