Write quickstart guide for v3

README.md

@@ -8,13 +8,19 @@ Directors.
 Read more about STV at
 http://en.wikipedia.org/wiki/Single_transferable_vote
 
+> [!NOTE]
+>
+> The `v3` directory contains the current (ongoing) version of Steve.
+> Read the [v3/README.md](v3/README.md) file for more information about
+> this version. Read the [Getting Started Guide](v3/docs/quickstart.md)
+> to set up a development environment for v3.
+
 ## Getting Started
 
 Getting Started documentation can be found at: http://steve.apache.org/demo.html
 Otherwise, come to the #steve channel on the Slack workspace at the-asf.slack.com, 
 and we'd be glad to help you.
 
-
 ## Documentation
 
 Documentation may be found at http://steve.apache.org/documentation.html
@@ -34,21 +40,13 @@ Notification on all code changes are sent to the following mailing list:
 The mailing lists are open to anyone and publicly archived.
 
 You can subscribe the mailing lists by sending a message to
-<LIST>[email protected] (for example
-dev-subscribe@steve...).  To unsubscribe, send a message to
-<LIST>[email protected].  For more instructions, send a
-message to <LIST>[email protected].
-
-Additional mailing list details may be found at
-http://steve.apache.org/support.html
+`<LIST>[email protected]` (for example
+`[email protected]`).  To unsubscribe, send a message to
+`<LIST>[email protected]`.  For more instructions, send a
+message to `<LIST>[email protected]`.
 
 ## Issue Tracker
 
 If you encounter errors in Steve or want to suggest an improvement or a new
 feature, please visit the Steve issue tracker at
-https://issues.apache.org/jira/browse/STEVE
-
-## Implemented changes
-
-Implemented changes can be found at:
-    https://github.apache.org/apache/steve/
+https://github.com/apache/steve/issues

v3/README.md

@@ -16,6 +16,11 @@ framework, using more recent technologies for greater leverage.
 For background reference in this README, see the documentation for the
 [database schema](docs/schema.md)
 
+## Getting Started
+
+Read the [Getting Started Guide](docs/quickstart.md) to set up a development
+environment.
+
 ## Data Model
 
 v2 is the initial guide for a data model, to be used by v3.
@@ -45,7 +50,6 @@ no known items to monitor.
 The owner/creator of an Election will be given a dashboard to view progress,
 in an anonymized form.
 
-
 ## Hashes and Anonymity
 
 The recorded Votes must be as anonymized as possible. The goal is to
@@ -86,14 +90,13 @@ To reveal the votes for computing a final tally of an Issue, the
 the corresponding votes for the tally (only most-recent vote used).
 
 The votes will be decrypted and fed into the issue's tally
-function (based on the vote type (eg. yes/no/abstain, or Single
+function (based on the vote type, eg. yes/no/abstain, or Single
 Transferable Vote).
 
 When a Person loads their ballot, and needs to know which issues have
 not (yet) been voted upon, then we compute a `vote_token` for each
 eligible Issue, then look into the **Votes** table for rows.
-The actual vote does
-not need to be decrypted for this process.
+The actual vote does not need to be decrypted for this process.
 
 ## Implementation
 
@@ -195,15 +198,13 @@ To tally a specific issue:
 3. Decrypt the ciphertext to produce the original `votestring`
 4. Feed these votes into the tally mechanism for the Issue's vote type.
 
-
 ## API Documentation
 
 This is _TBD_
 
 A basic example of using the API is available via the
 [code coverage testing script](test/check_coverage.py).
 
-
 ## Threat Model
 
 There are two primary threat vectors that can compromise the cryptographic
@@ -212,7 +213,5 @@ records of elections, people, issues, and their votes:
 1. **root** on the system
 2. Remote Code Execution (RCE) that can surface necessary rows from the database
 
-
-
 [^fernet]: https://cryptography.io/en/latest/fernet/
 [^argon2]: https://passlib.readthedocs.io/en/stable/lib/passlib.hash.argon2.html

v3/docs/quickstart.md

@@ -0,0 +1,104 @@
+# Getting Started
+
+## Prerequisites
+
+STeVe v3 uses `uv` as the project manager. You can install `uv` via:
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+For other installation methods, see the [uv installation documentation](https://docs.astral.sh/uv/getting-started/installation/).
+
+You'll also need to have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [SQLite 3.x](https://www.sqlite.org/download.html) installed on your system. You can verify their installation by running:
+
+```shell
+git --version
+sqlite3 --version
+```
+
+## Cloning the Repository
+
+Clone the STeVe repository from GitHub:
+
+```shell
+git clone https://github.com/apache/steve.git
+```
+
+## Setting Up the Development Environment
+
+First of all, head over to the `v3/` directory. This is where all the current development is happening.
+
+```shell
+cd steve  # navigate to the cloned repository
+cd v3     # navigate to the v3 directory
+```
+
+Run the following command to set up the development environment using `uv`:
+
+```shell
+uv sync
+```
+
+## Preparing the Database
+
+Head into the `server` directory for preparing data:
+
+```shell
+cd server
+```
+
+Create the steve.db file by loading the schema:
+
+```shell
+sqlite3 steve.db < ../schema.sql
+```
+
+Load steve.db's "person" table with ASF userids. For this step, you will need access to the ASF LDAP server. If you don't have access, please reach out on the developer mailing list or Slack channel for assistance.
+
+```shell
+cat > bin/bind.txt
+# <2 magic lines for user/pass; talk to me on Slack>
+```
+
+Once bind.txt is ready, run the LDAP loading script (this may take a few minutes):
+
+```shell
+uv run bin/asf-load-ldap.py
+```
+
+Then prepare some fake testing data:
+
+```shell
+uv run bin/load-fakedata.py --owner-pid <your_asf_id> # e.g., tison
+```
+
+All the data is now prepared.
+
+## Running the Server
+
+Ensure you are in the `server` directory.
+
+Before running the server, you need to create the config file and generate server certificates.
+
+To create the config file, copy the example config:
+
+```shell
+cp config.yaml.example config.yaml
+```
+
+Then, follow the instructions in [`server/certs/README.md`](../server/certs/README.md) to create self-signed certificates for development purposes.
+
+Now, you can run the server with:
+
+```shell
+uv run main.py # ensure you are in the server/ directory
+```
+
+Point your browser to https://localhost:58383/
+
+Congratulations! You should see the STeVe v3 web interface.
+
+If you modify anything (code, templates), then the server should automatically reload the change.
+
+If you run into a problem, please reach out on the developer mailing list or Slack channel for assistance.