Write quickstart guide for v3
Signed-off-by: tison <wander4096@gmail.com>
diff --git a/README.md b/README.md
index 64b819c..d831a35 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,19 @@
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 @@
The mailing lists are open to anyone and publicly archived.
You can subscribe the mailing lists by sending a message to
-<LIST>-subscribe@steve.apache.org (for example
-dev-subscribe@steve...). To unsubscribe, send a message to
-<LIST>-unsubscribe@steve.apache.org. For more instructions, send a
-message to <LIST>-help@steve.apache.org.
-
-Additional mailing list details may be found at
-http://steve.apache.org/support.html
+`<LIST>-subscribe@steve.apache.org` (for example
+`dev-subscribe@steve.apache.org`). To unsubscribe, send a message to
+`<LIST>-unsubscribe@steve.apache.org`. For more instructions, send a
+message to `<LIST>-help@steve.apache.org`.
## 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
diff --git a/v3/README.md b/v3/README.md
index 1b737a3..65c3263 100644
--- a/v3/README.md
+++ b/v3/README.md
@@ -16,6 +16,11 @@
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 @@
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 @@
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,7 +198,6 @@
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_
@@ -203,7 +205,6 @@
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 @@
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
diff --git a/v3/docs/quickstart.md b/v3/docs/quickstart.md
new file mode 100644
index 0000000..b2db15c
--- /dev/null
+++ b/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.
