From d56739421e890d529c5f8e2a0a4e4773ecce0029 Mon Sep 17 00:00:00 2001
From: Kunal Mehta <legoktm@debian.org>
Date: Fri, 21 Jul 2023 17:44:45 -0400
Subject: [PATCH] WIP: Document packaging repositories

Fixes #80.
---
 docs/apt_repo.rst      | 46 -------------------------------------
 docs/index.rst         |  2 +-
 docs/package_repos.rst | 51 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 52 insertions(+), 47 deletions(-)
 delete mode 100644 docs/apt_repo.rst
 create mode 100644 docs/package_repos.rst

diff --git a/docs/apt_repo.rst b/docs/apt_repo.rst
deleted file mode 100644
index d67fde48..00000000
--- a/docs/apt_repo.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-SecureDrop apt Repository
-=========================
-
-This document contains brief descriptions of the Debian packages
-hosted and maintained by Freedom of the Press Foundation in our apt
-repository (`apt.freedom.press`_).
-
-linux-image-\*-grsec
-    This package contains the Linux kernel image, patched with grsecurity.
-    Listed as a dependency of ``securedrop-grsec``.
-
-`ossec-agent <https://github.com/ossec/ossec-hids>`_
-    Installs the OSSEC agent, repackaged for Ubuntu.
-    Listed as a dependency of ``securedrop-ossec-agent``.
-
-`ossec-server <https://github.com/ossec/ossec-hids>`_
-    Installs the OSSEC manager, repackaged for Ubuntu.
-    Listed as a dependency of ``securedrop-ossec-server``.
-
-securedrop-app-code
-    Packages the SecureDrop application code, Python pip dependencies and
-    AppArmor profiles.
-
-securedrop-ossec-agent
-    Installs the SecureDrop-specific OSSEC configuration for the *Application Server*.
-
-securedrop-ossec-server
-    Installs the SecureDrop-specific OSSEC configuration for the *Monitor Server*.
-
-securedrop-grsec
-    SecureDrop grsecurity kernel metapackage, depending on the latest version
-    of ``linux-image-*-grsec``.
-
-securedrop-keyring
-    Packages the public signing key for this apt repository.
-    Allows for managed key rotation via automatic updates, as implemented in
-    `SecureDrop 0.3.10`_.
-
-.. note::
-   The SecureDrop install process configures a custom Linux kernel hardened
-   with the grsecurity patch set. Only binary images are hosted in the apt
-   repo. For source packages, see the `Source Offer`_.
-
-.. _SecureDrop 0.3.10: https://github.com/freedomofpress/securedrop/blob/c5b4220e04e3c81ad6f92d5e8a92798f07f0aca2/changelog.md
-.. _apt.freedom.press: https://apt.freedom.press
-.. _`Source Offer`: https://github.com/freedomofpress/securedrop/blob/develop/SOURCE_OFFER
diff --git a/docs/index.rst b/docs/index.rst
index bfdc49ba..8b810ce2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -39,7 +39,7 @@ administrators <https://docs.securedrop.org/>`_.
    testing_application_tests
    testing_configuration_tests
    testing_continuous_integration
-   apt_repo
+   package_repos
    updating_ossec
    apparmor_profiles
    portable_demo
diff --git a/docs/package_repos.rst b/docs/package_repos.rst
new file mode 100644
index 00000000..0247eb1d
--- /dev/null
+++ b/docs/package_repos.rst
@@ -0,0 +1,51 @@
+SecureDrop package repositories
+===============================
+
+SecureDrop publishes .deb and .rpm packages via apt and yum repositories, respectively.
+
+Each package repository is hosted on a dedicated virtual server and corresponds to a specific Git LFS repository.
+The Git repository contains the .deb and .rpm files and in some cases, the repository metadata too. When a new commit
+is pushed, a webhook instructs the server to pull new changes. A fallback cron job to git pull the repository also
+runs every 15 minutes.
+
+There are three levels of package repositories, which correspond to different stages
+of the development process.
+
+Test repositories
+-----------------
+
+* apt: apt-test.freedom.press, via securedrop-apt-test
+* yum: yum-test.securedrop.org, via securedrop-yum-test
+
+Test repositories serve two primary functions. First, during the release process,
+release candidate packages are published here to enable developers to perform QA,
+including testing upgrades.
+
+Second, nightly package builds are automatically pushed to test repositories by CI
+to enable developers to test integrated systems with code straight from `main`.
+
+Packages pushed to test repositories are automatically signed with a lower-security
+"test repository" key.
+
+QA repositories
+---------------
+
+* apt: apt-qa.freedom.press, via securedrop-apt-prod's release branch
+* yum: yum-qa.securedrop.org, via securedrop-yum-prod's release branch
+
+QA repositories are used as the final QA step before a new version is fully released.
+Developers upload candidate packages (using a non-release candidate version) to the
+`release` branch, and sign the repository using the high-security SecureDrop signing key.
+
+Once the new packages have been QA'd and approved, the `release` branch is merged into `main`,
+which publishes the packages on the production repositories.
+
+Production repositories
+-----------------------
+
+* apt: apt.freedom.press, via securedrop-apt-prod's main branch
+* yum: yum.securedrop.org, via securedrop-yum-prod's main branch
+
+Production repositories are used by real deployments of SecureDrop. SecureDrop server
+is configured to automatically fetch and install updates every 24 hours while SecureDrop Workstation
+requires a manual updater run.