### Scenario 1: First-time Dangerzone Installation

Source: https://github.com/freedomofpress/dangerzone/wiki/Meeting-Notes

This scenario covers the initial installation of Dangerzone. It assumes no prior installation, empty signature data, and updates being disabled.

```text
Inputs:
* sys.dangerzone_dev: False
* share/image-name.txt: ghcr.io/freedomofpress/dangerzone/v1
* <data_dir>/signatures: <empty>
* <data_dir>/signatures/last_log_index: <empty>
* ["updater_check_all"]: None
* ["updater_container_needs_update"]: None
* `podman images $(cat image-name)`: []
* share/container.tar: present
* signatures.DEFAULT_LOG_INDEX: 10

Installed image: <none>
Destination image: container-v0.10.0.tar

Outputs:
* <data_dir>/signatures: [sig1,]
* <data_dir>/signatures/last_log_index: 100
* `podman images $(cat image-name)`: ["ghcr.io/freedomofpress/dangerzone/v1:latest",]

Rationale:
    - podman images is empty
    - updater_check_all is Falsey

    - candidates_updates is local archive
    - default_log_index > current_log_index
```

--------------------------------

### Install WiX UI Extension

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Install the WiX UI extension, ensuring its version matches the installed WiX Toolset version.

```sh
wix extension add --global WixToolset.UI.wixext/5.0.2
```

--------------------------------

### Install WiX Toolset .NET Tool

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Install the WiX Toolset .NET tool version 5.0.2 globally, required for building Windows installers.

```sh
dotnet tool install --global wix --version 5.0.2
```

--------------------------------

### Build Windows Installer

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/release/build.md

This command builds the Windows installer (.msi) for Dangerzone.

```bash
poetry run .\install\windows\build-app.bat
```

--------------------------------

### Install Python Dependencies with Poetry

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Install Poetry and then install the project's Python dependencies using Poetry.

```sh
python3 -m pip install poetry
poetry install
```

--------------------------------

### Install Dangerzone via DNF (Fedora)

Source: https://github.com/freedomofpress/dangerzone/blob/main/INSTALL.md

Installs the Dangerzone package using DNF after the repository has been added.

```bash
sudo dnf install dangerzone
```

--------------------------------

### Install Poetry on Fedora

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Installs Poetry using pipx on Fedora systems.

```bash
pipx install poetry
pipx inject poetry
```

--------------------------------

### Show Help for env.py Script

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/environments.md

To get usage information and available options for the environment creation script, run the script with the --help flag.

```bash
./dev_scripts/env.py --help
```

--------------------------------

### Prepare Archive for Air-Gapped Installation

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/independent-container-updates.md

Prepare a tar archive containing the necessary material to install a new container image in an air-gapped environment. Adapt the --arch flag to your target architecture.

```bash
dangerzone-image prepare-archive --arch amd64
```

--------------------------------

### Install Dangerzone on Fedora Template

Source: https://github.com/freedomofpress/dangerzone/blob/main/INSTALL.md

Installs Dangerzone and its dependencies on a Fedora template. This involves adding the Dangerzone repository and then installing the 'dangerzone-qubes' package.

```shell
sudo dnf config-manager addrepo --from-repofile=https://packages.freedom.press/yum-tools-prod/dangerzone/dangerzone.repo
sudo dnf install dangerzone-qubes
```

--------------------------------

### Install Poetry and Plugin on Debian/Ubuntu

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Installs Poetry and the poetry-plugin-export using pipx, ensuring it's added to the system's PATH.

```bash
pipx ensurepath
pipx install poetry
pipx inject poetry poetry-plugin-export
```

--------------------------------

### Install Poetry Dependencies

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Installs project dependencies using Poetry after cloning the repository. Ensure Poetry is in your PATH and consider disabling keyring if prompted.

```bash
cd dangerzone
poetry install
```

--------------------------------

### Install Debian/Ubuntu Dependencies

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Installs necessary packages for Dangerzone development on Debian/Ubuntu systems using apt.

```bash
sudo apt install -y podman dh-python build-essential make libqt6gui6 \
    pipx python3 python3-dev
```

--------------------------------

### Scenario 4: Building Dangerzone from Source (Development Mode)

Source: https://github.com/freedomofpress/dangerzone/wiki/Meeting-Notes

This scenario applies when Dangerzone is being built from source in development mode. It assumes a local Podman image is present and bypasses signature verification and installation from container.tar.

```text
Inputs:
* sys.dangerzone_dev: True
* share/image-name.txt: ghcr.io/freedomofpress/dangerzone/v1
* <data_dir>/signatures: []
* <data_dir>/signatures/last_log_index: N/A
* ["updater_check_all"]: False
* ["updater_container_needs_update"]: None
* `podman images $(cat image-name)`: ["ghcr.io/freedomofpress/dangerzone/v1:latest",]
* share/container.tar: present
* signatures.DEFAULT_LOG_INDEX: 200

Installed image: "ghcr.io/freedomofpress/dangerzone/v1:latest"
Destination image: The locally built one

Rationale:
    * Run build-image script with a flag that also installs it locally. Basically, if we are in dev mode and there's a Podman image, we should expect that our build script has installed it, and thus we don't need to verify signatures / install it from the container.tar.
    * podman images is not empty
    * sys.dangerzone_dev is True
```

--------------------------------

### Install Homebrew Dependencies

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Install the 'create-dmg' utility using Homebrew, a dependency for macOS application bundling.

```sh
brew install create-dmg
```

--------------------------------

### Install Poetry on Windows

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/python.md

Install or upgrade Poetry using pip on Windows.

```shell
python -m pip install -U poetry
```

--------------------------------

### Install Dangerzone via RPM-OSTree (Fedora Atomic)

Source: https://github.com/freedomofpress/dangerzone/blob/main/INSTALL.md

Installs Dangerzone on Fedora Atomic systems using `rpm-ostree`. A system restart is required after installation to apply the changes.

```bash
rpm-ostree install dangerzone
```

--------------------------------

### Install Fedora Dependencies

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Installs necessary packages for Dangerzone development on Fedora systems using dnf.

```bash
sudo dnf install -y rpm-build podman python3 python3-devel python3-poetry-core \
    pipx qt6-qtbase-gui
```

--------------------------------

### Install Dangerzone via APT (Ubuntu/Debian)

Source: https://github.com/freedomofpress/dangerzone/blob/main/INSTALL.md

Installs the Dangerzone package after the repository has been added. This requires updating the package list first.

```bash
sudo apt update
sudo apt install -y dangerzone
```

--------------------------------

### Create Debian Bookworm Development Environment and Build .deb Package

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/release/build.md

This snippet sets up a Debian Bookworm development environment, installs vendorized assets, retrieves the latest container image, and then builds a .deb package for Dangerzone within the environment.

```bash
# Create and run debian bookworm development environment
./dev_scripts/env.py --distro debian --version bookworm build-dev
./dev_scripts/env.py --distro debian --version bookworm run --dev bash

# Get the vendorized assets
poetry run mazette install

# Retrieve the latest container
poetry run dangerzone-image prepare-archive
    --image ghcr.io/freedomofpress/dangerzone/v1@sha256:${DIGEST}
    --output share/container.tar

# Create a .deb
./dev_scripts/env.py --distro debian --version bookworm run --dev bash -c "cd dangerzone && ./install/linux/build-deb.py"
```

--------------------------------

### Install Extra Build Dependencies

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Installs essential Python 3 build dependencies required for compiling Dangerzone components on the development qube.

```bash
sudo dnf install -y python3-uv-build python3-pymupdf python3-magic
```

--------------------------------

### Add Dangerzone APT Repository GPG Key (Ubuntu/Debian)

Source: https://github.com/freedomofpress/dangerzone/blob/main/INSTALL.md

Downloads and imports the GPG key for the Dangerzone APT repository. Ensure you have `gpg` and `ca-certificates` installed.

```bash
sudo apt-get update && sudo apt-get install -y gpg ca-certificates
sudo mkdir -p /etc/apt/keyrings
sudo gpg --keyserver hkps://keys.openpgp.org \
    --no-default-keyring --no-permission-warning --homedir $(mktemp -d) \
    --keyring gnupg-ring:/etc/apt/keyrings/fpf-apt-tools-archive-keyring.gpg \
    --recv-keys DE28AB241FA48260FAC9B8BAA7C9B38522604281
sudo chmod +r /etc/apt/keyrings/fpf-apt-tools-archive-keyring.gpg
```

--------------------------------

### Load Archive in Air-Gapped Environment

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/independent-container-updates.md

Install a previously prepared tar archive onto an air-gapped system. Ensure the archive file is copied to the air-gapped machine before running this command.

```bash
dangerzone-image load-archive dangerzone-amd64.tar
```

--------------------------------

### List Available WSL Distributions

Source: https://github.com/freedomofpress/dangerzone/wiki/Troubleshooting-WSL

Execute this command to see all installed WSL distributions on your system. This is useful for identifying distributions to unregister.

```bash
wsl --list
```

--------------------------------

### Poetry Debug Info Output

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/python.md

Example output of 'poetry debug info' showing Poetry and virtual environment details. This output will vary based on your system and installation.

```text
Poetry
Version: 2.1.3
Python:  3.13.5

Virtualenv
Python:         3.13.5
Implementation: CPython
Path:           [...]
Executable:     [...]
Valid:          True

Base
Platform:   darwin
OS:         posix
Python:     3.13.5
Path:       [...]
Executable: [...]
```

```text
Poetry
Version: 2.1.3
Python:  3.13.5

Virtualenv
Python:         3.13.5
Implementation: CPython
Path:           [...]
Executable:     [...]
Valid:          True

Base
Platform:   win32
OS:         nt
Python:     3.13.5
Path:       [...]
Executable: [...]
```

--------------------------------

### Install Poetry on macOS

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/python.md

Install or upgrade Poetry using pip, ensuring it uses the correct Python installation.

```shell
python3 -m pip install -U poetry
```

--------------------------------

### Build Windows Executables

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Create Dangerzone executables ('dangerzone.exe', 'dangerzone-cli.exe') by running the 'setup-windows.py' script.

```bash
poetry run python .\setup-windows.py build
```

--------------------------------

### Prepare Container Image and Download Assets (macOS)

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/release/build.md

This snippet prepares the container image for packaging and downloads necessary assets using 'mazette'. It also copies the container image to a release assets folder.

```bash
poetry run dangerzone-image prepare-archive
 --image ghcr.io/freedomofpress/dangerzone/v1@sha256:${DIGEST}
 --output share/container.tar

poetry run mazette install

# Copy the container image to the assets folder
cp share/container.tar ~dz/release-assets/$VERSION/dangerzone-$VERSION-arm64.tar
```

--------------------------------

### Build All Release Artifacts

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/doit.md

Run this command to build all defined release artifacts. It executes all tasks in the dodo.py file.

```bash
doit
```

--------------------------------

### Install Sandbox Image Updates

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/independent-container-updates.md

Manually check for and install a new sandbox image. This command is used to update the local installation with the latest available sandbox image.

```bash
dangerzone-image upgrade
```

--------------------------------

### Verify Poetry Installation on macOS

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/python.md

Check if 'which poetry' points to the expected Poetry installation.

```shell
% which poetry
/Library/Frameworks/Python.framework/Versions/3.13/bin/poetry
```

--------------------------------

### Create Offline Disposable Template for Sanitization

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Sets up an offline disposable virtual machine (app qube) named 'dz-dvm' based on a specified template. This qube is intended for the document sanitization process.

```bash
qvm-create --class AppVM --label red --template fedora-43-dz \
    --prop netvm="" --prop template_for_dispvms=True \
    --prop default_dispvm='' dz-dvm
```

--------------------------------

### Initialize Cosign and Fetch Rekor Public Key

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/independent-container-updates.md

Initialize Cosign and fetch the latest Rekor public key to configure verification material. This is for power users who need to update the key before a Dangerzone release.

```bash
cosign initialize
cat ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json  \
    | jq -r .tlogs[0].publicKey.rawBytes \
    | base64 -d \
    | openssl pkey -pubin > rekor.pub
```

--------------------------------

### Use xhost for GUI App Display Server Access

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/environments.md

Alternatively to mounting the XAUTHORITY file, the xhost command can be used to grant access to the display server for containerized GUI applications. This method is considered slightly less secure in multi-user environments.

```bash
use xhost
```

--------------------------------

### Verify Python Installation on macOS

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/python.md

Check if 'which python3' points to the expected Python installation after PATH configuration.

```shell
% which python3
/Library/Frameworks/Python.framework/Versions/3.13/bin/python3
```

--------------------------------

### Prepare Dangerzone Container Image

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Downloads the latest Dangerzone container image or prepares it for local building.

```bash
poetry run dangerzone-image prepare-archive --output share/container.tar
```

--------------------------------

### Install WSL Manually

Source: https://github.com/freedomofpress/dangerzone/wiki/Troubleshooting-WSL

Use this command in an administrator PowerShell to manually install WSL. A restart is required after execution.

```powershell
wsl --install
```

--------------------------------

### Build Local Container Image

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Build the Dangerzone container image locally for testing without verifying signatures against Sigstore.

```bash
python3 ./install/common/build-image.py
```

--------------------------------

### Install Vendorized Assets

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/release/build.md

Installs vendorized assets required for Dangerzone development. This command is typically run after setting up the development environment.

```bash
poetry run mazette install
```

--------------------------------

### Import Dangerzone GPG Key Fingerprint Confirmation (Fedora)

Source: https://github.com/freedomofpress/dangerzone/blob/main/INSTALL.md

This console output shows the expected GPG key fingerprint for Dangerzone. Users should verify this fingerprint matches the one provided on the Dangerzone website.

```console
--------------------------------------------------------------------------------
Total                                           389 kB/s | 732 MB     32:07
Dangerzone repository                           3.8 MB/s | 3.8 kB     00:00
Importing GPG key 0x22604281:
 Userid     : "Dangerzone Release Key <dangerzone-release-key@freedom.press>"
 Fingerprint: DE28 AB24 1FA4 8260 FAC9 B8BA A7C9 B385 2260 4281
 From       : /etc/pki/rpm-gpg/RPM-GPG-dangerzone.pub
Is this ok [y/N]:
```

--------------------------------

### Install Dangerzone RPM Packages in Template

Source: https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md

Installs the Dangerzone RPM packages that were copied into the 'fedora-43-dz' template. This makes the Dangerzone dependencies available within the template.

```bash
sudo dnf install ~/QubesIncoming/dz/*.rpm
```

--------------------------------

### Test New Linux Version Locally

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/release/pre-release.md

Execute this script to perform a local test of a new Linux version, focusing on the GUI.

```bash
dev_scripts/qa.py
```

--------------------------------

### Check installed Dangerzone image

Source: https://github.com/freedomofpress/dangerzone/wiki/Meeting-Notes

Verifies the currently installed Dangerzone image using `podman images` and a file containing the image name. Used in multiple scenarios to check the state of the container images.

```bash
podman images $(cat image-name)
```

--------------------------------

### Checkout Dependencies and Clean Local Copy (macOS)

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/release/build.md

This snippet is used to prepare the local environment for building release artifacts on macOS. It sets the Dangerzone version, checks out the correct git tag, cleans the repository, removes old poetry environments, and synchronizes dependencies.

```bash
# Replace with the actual version
export DZ_VERSION=$(cat share/version.txt)

# Verify and checkout the git tag for this release:
git checkout -f v$VERSION

# Clean the git repository
git clean -df

# Clean up the environment
poetry env remove --all

# Install the dependencies
poetry sync
```

--------------------------------

### Verify Windows Binary Signature

Source: https://github.com/freedomofpress/dangerzone/blob/main/INSTALL.md

Use this command to verify the GPG signature of the Windows Dangerzone installer.

```bash
gpg --verify Dangerzone-0.6.1.msi.asc Dangerzone-0.6.1.msi
```

--------------------------------

### Configure PATH on macOS

Source: https://github.com/freedomofpress/dangerzone/blob/main/docs/developer/python.md

Add this to your ~/.zprofile to ensure the correct Python version is accessible. Replace <version> with your installed Python version.

```shell
PATH="/Library/Frameworks/Python.framework/Versions/<version>/bin:${PATH}"
export PATH
```