This is an automated email from the ASF dual-hosted git repository. tison pushed a commit to branch quickstart-v3 in repository https://gitbox.apache.org/repos/asf/steve.git
commit bad9edcf34439a48f3f1bb6d7cca1226df37d75c Author: tison <[email protected]> AuthorDate: Wed Nov 19 19:18:53 2025 +0800 Write quickstart guide for v3 Signed-off-by: tison <[email protected]> --- README.md | 26 ++++++------- v3/README.md | 15 ++++---- v3/docs/quickstart.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 123 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 64b819c..d831a35 100644 --- a/README.md +++ b/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 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 @@ 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,7 +198,6 @@ 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_ @@ -203,7 +205,6 @@ 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 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.
