Merge pull request #9 from elekto-io/v060

jberkus · web-flow · commit 1b1d95cf6ce8 · 2022-07-11T14:29:58.000-07:00
Update documentation for 0.6.0 release.
diff --git a/content/en/docs/Administration/_index.md b/content/en/docs/Administration/_index.md
@@ -6,7 +6,7 @@ description: >
   Guide for running elections using Elekto.
 ---
 
-Administering elections in Elekto is done through pushes of structured files to a GitHub repository.  See the [configuration guide]({{< ref "/Configuration" >}}) for how to configure the link to the repository.  This guide outlines how the Election Administrators run an individual election.  There are three parts to this:
+Administering elections in Elekto is done through pushes of structured files to a GitHub repository.  See the [configuration guide]({{< ref "/docs/Setup/configuration.md" >}}) for how to configure the link to the repository.  This guide outlines how the Election Administrators run an individual election.  There are three parts to this:
 
 1. [Creating an election]({{< relref "creating.md" >}})
 2. [Running an election]({{< relref "running.md" >}})
diff --git a/content/en/docs/Setup/_index.md b/content/en/docs/Setup/_index.md
@@ -1,6 +1,6 @@
 ---
-title: "Getting Started"
-linkTitle: "Getting Started"
+title: "Installation and Setup"
+linkTitle: "Installation"
 weight: 2
 description: >
   Start using elekto for your organisation.
diff --git a/content/en/docs/Setup/configuration.md b/content/en/docs/Setup/configuration.md
@@ -1,7 +1,7 @@
 ---
 title: "Configuration"
 linkTitle: "Configuration"
-weight: 2
+weight: 3
 description: >
   Setting up and configuring Elekto for operation
 ---
@@ -86,7 +86,9 @@ Example: `production` or `development`
 
 **APP_KEY**
 
-*Optional* Encryption seed for application cookies.  Deprecated; will be set automatically by Elekto in the future, but for now set it to a random 8byte+ value.
+*Optional* Encryption seed for application cookies.  Most users should leave blank, in which case it will be set automatically as a 
+random 8-byte key by the startup code.  Set manually to an 8-16 character key if you need to run multiple Elekto instances for the
+same organization.
 
 Example: `2400229255`
 
@@ -120,6 +122,12 @@ Example: `localhost`
 
 Example: `http` or `socket`
 
+**MIN_PASSCODE_LENGTH**
+
+*Optional*: Integer. Minimum length for a voter-ballot passphrase in order to deter hacking. Set to 6 if left blank.
+
+Example: `8`
+
 #### Database Connection
 
 **DB_CONNECTION**
diff --git a/content/en/docs/Setup/devinstall.md b/content/en/docs/Setup/devinstall.md
diff --git a/content/en/docs/Setup/installation.md b/content/en/docs/Setup/installation.md
diff --git a/content/en/docs/Setup/kubernetes.md b/content/en/docs/Setup/kubernetes.md
@@ -1,7 +1,7 @@
 ---
 title: "Kubernetes Installation"
 linkTitle: "Kubernetes Installation"
-weight: 2
+weight: 4
 description: >
   Installing Elekto on Kubernetes
 ---
diff --git a/content/en/docs/Setup/upgrading.md b/content/en/docs/Setup/upgrading.md
@@ -0,0 +1,68 @@
+---
+title: "Upgrading Elekto"
+linkTitle: "Upgrading"
+weight: 7
+description: >
+  How to upgrade Elekto
+---
+
+# Upgrading
+
+In most cases, you should be able to upgrade Elekto just by replacing the 
+Python/Flask code or the container image and restarting the service.
+The cases where that is not true are documented below.
+
+If you are running Elekto as Python code, you should also update the
+dependencies every time you upgrade, as we usually upgrade python library 
+versions to current ones.
+
+```
+pip3 install -r requirements.txt
+```
+
+## Upgrading from 0.5 to 0.6
+
+**This Upgrade Requires Extra Steps**
+
+Version 0.6 involves several major changes to the database schema which require 
+a multi-step database migration.  **At this time, this process is only automated
+for PostgreSQL**.
+
+**The Elekto Project Recommends Backing Up Your Database Before Upgrading**
+
+For users on PostgreSQL, the process should be as simple as:
+
+1. Shut the Elekto web application down
+2. Upgrade Elekto software
+3. Run `python console --migrate`
+
+If you are using the official container image, or others built like it, then
+the container image should automatically do the above when you delete and replace
+the container or pod.
+
+This may fail on PostgreSQL, either because you have modified your database schema
+after creation by Elekto, or because the Elekto database user does not have 
+permissions to modify tables.  In either case, you may need to run the 
+database migration manually.  If so, you will need to run the following SQL
+statements as the database owner or superuser:
+
+```
+CREATE TABLE schema_version ( version INT PRIMARY KEY );
+INSERT INTO schema_version VALUES ( 2 );
+ALTER TABLE voter ADD COLUMN salt BYTEA, ADD COLUMN ballot_id BYTEA;
+CREATE INDEX voter_election_id ON voter(election_id);
+ALTER TABLE ballot DROP COLUMN created_at, DROP COLUMN updated_at;
+ALTER TABLE ballot DROP CONSTRAINT ballot_pkey;
+ALTER TABLE ballot ALTER COLUMN id TYPE CHAR(32) USING to_char(id , 'FM00000000000000000000000000000000');
+ALTER TABLE ballot ALTER COLUMN id DROP DEFAULT;
+ALTER TABLE ballot ADD CONSTRAINT ballot_pkey PRIMARY KEY ( id );
+CREATE INDEX ballot_election_id ON ballot(election_id);
+```
+
+We [do not yet have instructions](https://github.com/elekto-io/elekto/issues/67) for upgrading MySQL or SQLite.  Those are in development.
+If you have an Elekto/MySQL instance, please contact us via Elekto slack channel
+on CNCF Slack, or by [commenting on the issue](https://github.com/elekto-io/elekto/issues/67); we would like to work with you on this.
+
+If you do not care about preserving election history, your other option is 
+to simply delete the old database and create a new, empty one.  In that case,
+Elekto will generate a new, updated schema through `console --migrate`.
diff --git a/content/en/docs/Voting/_index.md b/content/en/docs/Voting/_index.md
@@ -100,15 +100,15 @@ You are allowed to "tie" two candidates, giving them the same number ranking, if
 
 When you have finished ranking candidates, you may optionally enter a passphrase that will allow you to re-cast your vote.  This passphrase is used to encrypt the link between your account and your vote, so that the Election Officers are unable to eavesdrop on your specific ballot. If you enter a passphrase, you need to remember it or write it down because it is not retrievable via Elekto.  If you know that there is no chance you will want to re-do your ballot before the election is over, then you can leave the passphrase empty.
 
-## Re-Casting Your Vote
+## Reviewing and Re-Casting Your Vote
 
-If permitted by your administrator, Elekto allows you to revoke and re-cast your vote for as long as the election is open.  This way, you can vote when it opens, and update your vote if you learn new information about candidates.  If not permitted, you will not see the Revoke option.
+If permitted by your administrator, Elekto allows you to review, revoke and re-cast your vote for as long as the election is open.  This way, you can vote when it opens, and update your vote if you learn new information about candidates.  If not permitted, you will not see the View option.
 
-![revoke vote interface](revoke.png)
+In order to ensure that this doesn't compromise the privacy of your ballot, though, the link between your identity and ballot are encrypted with a passphrase you supplied when you voted (see above).  As such, you must enter that passphrase in the field in the election UI in order to review your vote.  If you didn't set one, or cannot remember it, you cannot re-cast your vote.  Administrators will not be able to help.
 
-In order to ensure that this doesn't compromise the privacy of your ballot, though, the link between your identity and ballot are encrypted with a passphrase you supplied when you voted (see above).  As such, you must enter that passphrase in the field in the election UI in order to revoke your vote.  If you didn't set one, or cannot remember it, you cannot re-cast your vote.  Administrators will not be able to help.
+If you enter your passphrase, and click "View", and you will be presented with a read-only view of your ballot. You can then check if the ballot still matches how you wish to vote.  
 
-If you enter your passphrase, and click "Revoke", your original ballot will be deleted.  You can then select "vote" in order to cast your ballot again.
+If it does not, you can revoke your ballot from the View screen.  Simply enter your passphrase again, and then press "Revoke".  Your original ballot will be deleted.  You can then select "vote" in order to cast your ballot again.  Note that, if you revoke your ballot and do not vote again, you are canceling your vote in that election.
 
 ## Checking the Results
 
diff --git a/content/en/docs/Voting/revoke.png b/content/en/docs/Voting/revoke.png
diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md
@@ -18,4 +18,6 @@ Elekto was designed to support the following:
 - Preference election voting (starting with Condorcet)
 - Multiple elections for the same organization
 - Responsive web design
-- Secret ballot voting
+- Secret ballot voting
+
+This set of documentation covers Elekto version 0.6.X.
