Add development instructions for Qubes integration

Add instructions aimed at developers who want to try out Qubes
integration.

Fixes #411

BUILD.md

@@ -102,11 +102,193 @@ Create a .rpm:
 ./install/linux/build-rpm.py
 ```
 
-## QubesOS
+## Qubes OS
 
-Create a Debian- or Fedora-based standalone VM with at least 8GB of private storage space, and follow the relevant instructions above.
+<details>
+  <summary><i>:memo: Expand this section if you want to use containers instead of disposable qubes.</i></summary>
+  </br>
 
-Over time, you may need to increase disk space or prune outdated Docker images if you run into build issues on this VM.
+  Create a Debian or Fedora-based development standalone qube with at least
+  8GB of private storage space, and follow the relevant instructions above for
+  the respective template.
+
+  Remember to set the environment variable `DZ_USE_CONTAINERS=1`, before executing
+  Dangerzone.
+
+  Over time, you may need to increase disk space or prune outdated container
+  images if you run into build issues on this VM.
+</details>
+
+> :warning: Native Qubes support is in alpha stage, so the instructions below
+> require switching between qubes, and are subject to change.
+
+### Initial Setup
+
+The following steps must be completed once. Make sure you run them in the
+specified qubes.
+
+#### In `dom0`
+
+1. Create a new Fedora **template** (`fedora-37-dz`) for Dangerzone development:
+
+   ```
+   qvm-clone fedora-37 fedora-37-dz
+   ```
+
+   > :bulb: Alternatively, you can use your base Fedora 37 template in the
+   > following instructions. In that case, replace `fedora-37-dz` with
+   > `fedora-37` in the steps below.
+
+2. Create a **disposable**, offline app qube (`dz-dvm`), based on the
+   `fedora-37-dz` template. This will be the qube where the documents will be
+   sanitized:
+
+   ```
+   qvm-create --class AppVM --label red --template fedora-37-dz \
+       --prop netvm="" --prop template_for_dispvms=True \
+       dz-dvm
+   ```
+
+3. Create an **app** qube (`dz`) that will be used for Dangerzone development
+   and initiating the sanitization process:
+
+   ```
+   qvm-create --class AppVM --label red --template fedora-37-dz dz
+   ```
+
+   > :bulb: Alternatively, you can use a different app qube for Dangerzone
+   > development. In that case, replace `dz` with the qube of your choice in the
+   > steps below.
+
+4. Add an RPC policy (`/etc/qubes/policy.d/50-dangerzone.policy`) that will
+   allow launching a disposable qube (`dz-dvm`) when Dangerzone converts a
+   document, with the following contents:
+
+   ```
+   dz.Convert         *       @anyvm       @dispvm:dz-dvm  allow
+   dz.ConvertDev      *       @anyvm       @dispvm:dz-dvm  allow
+   ```
+
+#### In the `fedora-37-dz` template
+
+1. Install dependencies:
+
+   ```
+   sudo dnf install -y rpm-build pipx qt5-qtbase-gui libreoffice python3-magic \
+       tesseract*
+   ```
+
+2. Shutdown the `fedora-37-dz` template:
+
+   ```
+   shutdown -h now
+   ```
+
+#### In the `dz` app qube
+
+1. Clone the Dangerzone project:
+
+   ```
+   git clone https://github.com/freedomofpress/dangerzone
+   ```
+
+2. Install Poetry using `pipx`:
+
+   ```sh
+   pipx install poetry
+   ```
+
+3. Change to the `dangerzone` folder, and install the poetry dependencies:
+
+   ```
+   poetry install
+   ```
+
+   > **Note**: due to an issue with
+   > [poetry](https://github.com/python-poetry/poetry/issues/1917), if it
+   > prompts for your keyring, disable the keyring with `keyring --disable` and
+   > run the command again.
+
+4. Change to the `dangerzone` folder and copy the Qubes RPC calls into the
+   template for the **disposable** qube that will be used for document
+   sanitization (`dz-dvm`):
+
+   ```
+   qvm-copy-to-vm dz-dvm qubes/
+   ```
+
+#### In the `dz-dvm` template
+
+1. Create the directory that will contain the Dangerzone RPC calls, if it does
+   not exist already:
+
+   ```
+   sudo mkdir -p /rw/usrlocal/etc/qubes-rpc/
+   ```
+
+2. Move the files we copied in the previous step to their proper place:
+
+   ```
+   sudo cp ~/QubesIncoming/dz/qubes/* /rw/usrlocal/etc/qubes-rpc/
+   ```
+
+3. Shutdown the `dz-dvm` template:
+
+   ```
+   shutdown -h now
+   ```
+
+### Developing Dangerzone
+
+From here on, developing Dangerzone is similar as in other Linux platforms. You
+can run the following commands in the `dz` app qube:
+
+```sh
+# start a shell in the virtual environment
+poetry shell
+
+# run the CLI
+./dev_scripts/dangerzone-cli --help
+
+# run the GUI
+./dev_scripts/dangerzone
+```
+
+Create a .rpm:
+
+```sh
+./install/linux/build-rpm.py --qubes
+```
+
+For changes in the server side components, you can simply edit them locally,
+and they will be mirrored to the disposable qube through the `dz.ConvertDev`
+RPC call.
+
+The only reason to update the `fedora-37-dz` template from there on is if:
+1. The project requires new server-side components.
+2. The code for `dz.ConvertDev` needs to be updated. Copy the updated file
+   as we've shown in the steps above.
+
+### Installing Dangerzone system-wide
+
+If you want to test the .rpm you just created, you can do the following:
+
+On the `dz` app cube, copy the built `dangerzone.rpm` to `fedora-37-dz`
+template:
+
+```
+qvm-copy-to-vm fedora-37-dz dist/dangerzone*.noarch.rpm
+```
+
+On the `fedora-37-dz` template, install the copied .rpm:
+
+```
+sudo dnf install -y ~/QubesIncoming/dz/dangerzone-*.rpm
+```
+
+Shutdown the `fedora-37-dz` template and the `dz` app qube, and then you can
+refresh the applications on the `dz` qube, find Dangerzone in the list, and use
+it to convert a document.
 
 ## macOS
 

CHANGELOG.md

@@ -9,8 +9,11 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 
 ### Added
 
+- Platform support: Alpha integration with Qubes OS ([issue #411](https://github.com/freedomofpress/dangerzone/issues/411))
+
 ### Removed
-- Platform support: Drop Fedora 36, since it's end-of-life ([issues #420](https://github.com/freedomofpress/dangerzone/issues/420))
+
+- Platform support: Drop Fedora 36, since it's end-of-life ([issue #420](https://github.com/freedomofpress/dangerzone/issues/420))
 
 ### Fixed
 

INSTALL.md

@@ -8,6 +8,7 @@ Dangerzone is available for:
 - Fedora 38
 - Fedora 37
 - Fedora 36
+- Qubes OS (alpha support)
 
 ### Ubuntu, Debian
 
@@ -117,8 +118,24 @@ After confirming that it matches, type `y` (for yes) and the installation should
 
 </details>
 
+### Qubes OS
 
+<details>
+  <summary><i>:memo: Expand this section if you want to use containers instead of disposable qubes.</i></summary>
+  </br>
+
+  Create a Debian or Fedora-based development standalone qube with at least
+  8GB of private storage space, and follow the relevant instructions above for
+  the respective template.
+
+  Remember to set the environment variable `DZ_USE_CONTAINERS=1`, before
+  executing Dangerzone.
+</details>
+
+> :warning: Native Qubes support is in alpha stage, so we don't have official
+> installation instructions yet. If you want to try out Dangerzone with native
+> Qubes support, check out our [build instructions](BUILD.md#qubes-os) instead.
 
 ## Build from source
 
-If you'd like to build from source, follow the [build instructions](https://github.com/freedomofpress/dangerzone/blob/master/BUILD.md).
+If you'd like to build from source, follow the [build instructions](BUILD.md).