README corrections and tweaks #816
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
|
||
| - The development environment uses the `yum-test.securedrop.org` and `apt-test.freedom.press` repositories, and is configured to use the `nightly` component for apt package. It does not alter power management settings on your laptop to prevent suspension to disk (a security measure for production environments, which the staging environment preserves to be more faithful to prod-like settings). | ||
|
|
||
| - The production environment uses `yum.securedrop.org` and `apt.freedom.press` repositories, verified using the production signing key. Its setup is not covered below; see our [production install docs](https://workstation.securedrop.org/en/stable/admin/install.html) for details. |
There was a problem hiding this comment.
linking to the production docs is super helpful for future newcomers
| #### Provision the VMs | ||
|
|
||
| Once the configuration is done and this directory is copied to `dom0`, you must update existing Qubes templates and use `make` to handle all provisioning and configuration by your unprivileged user: | ||
| Once the configuration is done and this directory is copied to `dom0`, you must update existing Qubes templates and use `make` to handle all provisioning and configuration by your unprivileged user. Before you do so, you may wish to increase the scrollback in the dom0 terminal from 1000 (the default) to 100000 or unlimited, to ensure you can review any errors in the verbose output. |
There was a problem hiding this comment.
always a helpful tip
| When the installation process completes, a number of new VMs will be available on your machine, all prefixed with `sd-`. | ||
|
|
||
| #### Editing the configuration | ||
| When developing on the Workstation, make sure to edit files in `sd-dev`, then copy them to dom0 via `make clone && make dev` to reinstall them. Any changes that you make to the ~/securedrop-workstation folder in dom0 will be overwritten during `make clone`. Similarly, any changes you make to e.g. `/srv/salt/` in dom0 will be overwritten by `make dev`. | ||
|
|
||
| ### Staging Environment | ||
|
|
||
| The staging environment differs from a production envionment in that it builds a local RPM, installs it in dom0, uses the dom0 package repository configuration for future updates of the RPM package from the https://yum-test.securedrop.org repository, and makes it so that you receive the latest nightlies of the workstation components, such as the SecureDrop Client. |
There was a problem hiding this comment.
@eloquence this could be useful to add to the Development Environment section, what do you think?
There was a problem hiding this comment.
I think the removed text as written is inaccurate:
- The staging environment now uses
maininstead ofnightly(this is noted as part of this PR). - The staging environment doesn't inherently build or install an RPM like this text suggests. You could install an RPM from yum-test and then run
sdw-admin --applywith the environment set tostaging, which this README also documents.
I think it might help if we clarified in the README a bit more when to use the Makefile targets to build and install the RPM, and when to install a downloaded version of the RPM.
There was a problem hiding this comment.
oops, I meant the part about how the local RPM is built locally and installed when you run make dev
There was a problem hiding this comment.
Tried to clarify this in a couple of places in d22b80c
README.md
Outdated
| @@ -282,9 +282,9 @@ In a terminal in `dom0`, run the following commands: | |||
|
|
|||
| This project's development requires different workflows for working on provisioning components and working on submission-handling scripts. | |||
|
|
|||
| For developing salt states and other provisioning components, work is done in a development VM and changes are made to individual state and top files there. In the `dom0` copy of this project, `make clone` is used to package and copy over the updated files; `make <vm-name>` to rebuild an individual VM; and `make dev` to rebuild the full installation. Current valid target VM names are `sd-proxy`, `sd-gpg`, `sd-whonix`, and `disp-vm`. Note that `make clone` requires two environment variables to be set: `SECUREDROP_DEV_VM` must be set to the name of the VM where you've been working on the code, the `SECUREDROP_DEV_DIR` should be set to the directory where the code is checked out on your development VM. | |||
| For developing salt states and other provisioning components, work is done in a development VM and changes are made to individual state and top files there. In the `dom0` copy of this project, `make clone` is used to package and copy over the updated files; `make <vm-name>` to rebuild an individual VM; and `make dev` to rebuild the full installation. Note that `make clone` requires two environment variables to be set: `SECUREDROP_DEV_VM` must be set to the name of the VM where you've been working on the code, the `SECUREDROP_DEV_DIR` should be set to the directory where the code is checked out on your development VM. | |||
There was a problem hiding this comment.
suggestion: make clone is used to package and copy over the updated files; -> make clone is used to build the dom0 configuration RPM and copy over the updated files;
There was a problem hiding this comment.
Unpacked this monster paragraph a bit in d22b80c
sssoleileraaa
approved these changes
Aug 11, 2022
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Status
Ready for review
Description of Changes
Fixes various small issues in README: