Interstitial commit for massive documentation extensions.

Signed-off-by: Josh Berkus <josh@agliodbs.com>

Author: jberkus

content/en/docs/Getting started/configuration.md

@@ -0,0 +1,218 @@
+---
+title: "Configuration"
+linkTitle: "Configuration"
+weight: 2
+description: >
+  Setting up and configuring Elekto for operation
+---
+
+# Configuration and Setup
+
+Elekto's configuration is divided into three parts:
+
+1. Oauth and GitHub configuration
+2. Runtime environment
+3. Per-election configuration
+
+This document covers the first two, which consists of the items that need to be configured before Elekto will run.  The third part is covered in the [Administrator Guide].
+
+## Oauth and Repository Configuration
+
+Elekto relies on an external Oauth provider for user authentication, by design.  This provider must be configured to accept authentication requests from Elekto.  You may only have one Oauth provider per Elekto instance, as authentication happens before selecting an election.
+
+You must also configure the repository that contains the election metadata (hereafter "the repo") to push changes to Elekto.  
+
+Currently, the only Oauth provider offered is GitHub.  Contributions of additional providers are extremely welcome.
+
+### GitHub Setup
+
+#### GitHub Oauth
+
+You must set up an "Oauth Application" that Elekto can use.  In GitHub, this is under Settings-->Developer Tools-->Oauth Applications.  Note that Oauth Apps are belong to *accounts* rather than organizations, so you'll want to set up an account with shared access in your infra team. We also recommend setting up a separate Oauth App for Elekto rather than re-using one created for other purposes, and giving each Elekto instance its own secret key.
+
+The Oauth App must have the following settings:
+
+*
+
+Having configured this, you can populate GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in Elekto's runtime environment.
+
+#### GitHub Repository Webhook
+
+In order to receive changes from the repo, you need to add a webhook that pushes changes whenever you merge.  Webhooks are under "settings" for the individual repository (which also means you must be a repo onwer).  
+
+The Webhook should have the following settings:
+
+* Push webhook
+* JSON data format
+* Use TLS
+* 
+* Shared Secret set to the same as META_SECRET
+
+This last "secret" is an arbitrary string that authenticates the push to the Elekto server.  It can be any string, such as one created by a password generator or a passphrase you like.  This string then gets set in META_SECRET. 
+
+## The Environment File
+
+Elekto is designed to accept its runtime configuration as ENV variables in its shell environment.  A sample `.env.example` file can be found in the base directory of the Elekto source.  These ENV configuration variables are not expected to change frequently, or at all, for any particular running Elekto instance.  Changing them generally requires restarting Elekto.
+
+All of these env variables need to be set before starting Elekto as a uwsgi application, or even in developer mode; without them, Elekto will error out and refuse to start. You can set this up however you please:
+
+* as the `.bashrc` for the elekto application user
+* as ENV variables for a container running Elekto
+* preloaded in a systemd unit file
+* injected through a ConfigMap and a Secret into an Kubernetes pod
+
+Since we use ENV for Elekto configuration, this does mean that Elekto must be launched under a shell.
+
+### ENV Variables
+
+What follows are the ENV variables that must be set for Elekto to run.  
+
+#### Application Information
+
+**APP_NAME**
+
+*Required* Name of the Elekto instance you are running.  Displays in some parts of the UI.  For user information only.
+
+Example: `k8s.elections`
+
+**APP_ENV**
+
+*Optional* Status of this Elekto instance, for CI/CD purposes.  Not used internally by Elekto.
+
+Example: `production` or `development` 
+
+**APP_KEY**
+
+*Optional* Seed string for Flask encryption if running Flask in standalone mode.  Not required if fronting with an HTTPS webserver.
+
+Example: ``
+
+FIXME
+
+**APP_DEBUG**
+
+*Required* Whether to run in Debug mode for troubleshooting purposes.  In Debug mode, will output stack traces for errors and reload templates.
+
+Example: `True` or `False`
+
+**APP_URL**
+
+*Optional* URL of the Elekto instance.  Used by some uwsgi and/or Nginx configurations.  Not used internally by Elekto.
+
+Example: `http://elections.knative.dev`
+
+**APP_PORT**
+
+*Optional* Used in some uwsgi start scripts, and when running Flask in standalone mode.  Port on which to serve Elekto.
+
+Example: `5000`
+
+**APP_HOST**
+
+*Optional* Used in some webserver startup scripts, and by the Flask server in standalone mode.  Name of the host served by this Elekto instance.
+
+Example: `localhost`
+
+**APP_CONNECT**
+
+*Optional* Whether to serve uwsgi over HTTP or via a local unix socket.  Used by some startup scripts; see `entrypoint.sh` for an example.  
+
+Example: `http` or `socket`
+
+#### Database Connection
+
+**DB_CONNECTION**
+
+*Required* Which database connection type to use.  Currently only postgresql, mysql, and sqlite are supported.  
+
+Example: `postgresql`, `mysql`, or `sqlite`
+
+**DB_HOST**
+
+*Required* The URL, IP, or hostname of the database server.  Ignored if using SQLite (set to `N/A`).
+
+Example: `pgdb-1a.prod.elekto.dev`
+
+**DB_PORT**
+
+*Required* The network port for the database server.  Ignored if using SQLite (set to `1001`).
+
+Example: `3306`
+
+**DB_PATH**
+
+*Optional* Used only for SQLite.  Path to the database filesystem.
+
+Example: `/var/db/elekto-db`
+
+**DB_USERNAME**
+
+*Required* Login user for the Elekto database.  Not used by SQLite.
+
+Example: `elekto`
+
+**DB_PASSWORD**
+
+*Required* Authentication password for the Elekto database.  Not used by SQLite.
+
+Example: `1a6e4b3f55dc`
+
+#### Repository Configuration
+
+**META_REPO**
+
+*Required* GIT clone URL for the repository which contains the election configurations.  Should be the `.git` link, not the `.html` one.
+
+Example: `https://github.com/kalkayan/k8s.elections.meta.git`
+
+**ELECTION_DIR**
+
+*Required* Directory, relative to the Git repository root, containing the set of election subdirectories.  Can be an arbitrarily deep path.  Do not use a leading or trailing `/`.
+
+Example: `elections`, `gov/steering/elections`
+
+**META_DEPLOYMENT**
+
+*Optional* Reserved for future advanced configuration use.
+
+Example: `local`, `sidecar`
+
+**META_PATH**
+
+*Required* Local file location at which to store a clone of the election data repository.  This directory will be created by Elekto at sync time, so the application must have the ability to write to the parent directory.  May be absolute or relative; if relative, will be under the eletko source directory.  Defaults to `meta`.  For containers, a directory under `/tmp` is recommended to make sure the location is writeable.
+
+Example: `meta`, `/tmp/meta`
+
+**META_BRANCH**
+
+*Required* Which git branch has the merged version of the election data.  Defaults to `main`.
+
+Example: `main`, `master`, `prod`
+
+**META_SECRET**
+
+*Required* The shared secret string used in the Github webhook for updates of the election data repository.  Can be set to anything you like; we recommend a random md5 string or generated password.
+
+Example: `92a488d11c0d27bbfea0a97e3332e08a` 
+
+#### Oauth Settings
+
+At this time, there are only settings available for GitHub because other Oauth sources haven't been implemented.  When other sources get added to Elekto, each will get their own configuration variables.
+
+**GITHUB_REDIRECT**
+
+*Required* Flask path for the GitHub authentication callback.  Defaults to `/oauth/github/callback`, and there's no good reason to change it.
+
+Example: `/oauth/github/callback`
+
+**GITHUB_CLIENT_ID**
+
+*Required* The Client ID from the GitHub Oauth Application.
+
+Example: `0b9138c0b2ffeefd9fc1`
+
+**GITHUB_CLIENT_SECRET**
+
+*Required* The Client Secret from the GitHub Oauth Application.
+
+Example: `dd37278f8e9d57571590ad9288f0aae62228c2e8`

content/en/docs/Getting started/installation.md

@@ -0,0 +1,88 @@
+---
+title: "Installation"
+linkTitle: "Installation"
+weight: 2
+description: >
+  Full installation documentation
+---
+
+# Installation Concepts
+
+For Elekto to run in production, you need the following small application stack: 
+
+* The Elekto python/flask/uwsgi application
+* A backing SQL database instance
+* A web proxy such as Nginx or Kubernetes Ingress
+* A GitHub repository
+* An Oauth authentication source
+
+Elekto can be installed either as a native application, or as a container.
+
+## Installing Requirements and Python Binaries
+
+Elekto is a Python/Flask/uwsgi application developed in Python 3. Building it from source requires the following prerequisites, which should be installed using your OS's packaging system:
+
+* Python3 Pip and supporting build tools (like gcc), or Conda
+* uwsgi server
+* Database client libraries for your chosen database (see below)
+* git
+
+Having installed those prerequisites, you can now install the python requirements using Pip, which will build the python source:
+
+```bash
+# Installation with pip 
+pip install -r requirements.txt
+
+# Installation with Conda
+conda env create -f environment.yml && conda activate elekto
+```
+
+Please check the above build process carefully for error messages; the only acceptable errors are (a) warnings about out-of-date versions and (b) missing database libraries for the databases you're not using.
+
+It is completely possible that you could run Elekto using fastcgi instead of uwsgi, but at this time we have no documentation on how to do this.
+
+## Backing SQL Database
+
+Github stores ballots and some metadata in a designated SQL database, which is up to you to install and run.  Currently Elekto supports the following:
+
+* PostgreSQL
+* MySQL (and its forks)
+* SQLite
+
+However, as Elekto uses SQLAlchemy, it can potentially support any SQL database that SQLAlchemy supports.  Adding new databases will require a PR to Elekto.  
+
+Database requirements are very light, so it is completely feasible to run the database on the same server as the python application. The database server needs less than 2 CPUs, 1GB memory, and 25GB storage. You can also use a cloud database service; the included database support was chosen specifically because there are multiple cloud database services available.  In that case, you are likely to use the smallest size of cloud database available.
+
+The Elekto database user needs to have permissions to create tables. The database must be configured with user/password login.  Other forms of authentication are not yet supported.
+
+The Elekto application will not run if the database is unavailable. The ballot data contained in the database is not stored anywhere else, and as such is unrecoverable if the database is lost. For this reason, it is up to the administrator to set up and manage backups and high availability.  This is particularly a concern for SQLite, which is an embedded database; you will need to set up cron jobs on the server to back this up.
+
+## Web Server
+
+Elekto runs in the python uwsgi web application server.  Uwsgi is not very scalable, though, and does not handle SSL connections.  As such, for anything other than developer mode, we recommend that you put a web server in front of it.
+
+Nginx works well for this, whether as a standalone or as part of Kubernetes Ingress.  See the sample Nginx configuration in the installation directory of the Elekto repository for an example setup.  If running directly on a host with an Nginx proxy, you'll want to run Eletko in "socket" connection mode.  Other web servers would also work, but Nginx is the only sample configuration supplied.
+
+On Kubernetes, you'll want to access Elekto via Ingress.  See `installation/deployment` for an example of this.  In a Kubernetes setup, you want to run Elekto in http mode. 
+
+## GitHub Repository
+
+Elekto's workflow is GitOps-based.  This means that, in order to use Elekto, you must have a GitHub (GitLab TBD) repository for Elekto to attach to.  This must be a repository you own and have administration rights on, as you will be setting up a webhook and directories.
+
+It does *not* need to be a repository that's exclusively dedicated to Elekto.  Most organizations using Elekto place its election metadata into a subdirectory of a repository that's used for other community documents (e.g. `knative/community/elections`).  Given that Elekto will refresh for every webhook push, however, it's probably better if it's not a repository that gets multiple commits per hour.
+
+See [Configuration]() for how to set up this GitHub repository, and the [Administration Guide]() for what files go into it.
+
+## Oauth Authentication Source
+
+Elekto does not maintain user authentication; by design, it relies on an outside Oauth source for user login.  Currently the only Oauth source supported is GitHub.  If you want to add other sources, contributions are very welcome.
+
+See Configuration for how to configure this in GitHub.
+
+## Other System Requirements
+
+Elekto does not require elevated privileges to run, so for security we recommend running it under an elekto, www, or python application account with restricted permissions.
+
+Elekto caches a copy of the election respository on disk, and as such needs a file location to which it can write, with storage equal to the storage size of a git clone of that repository.
+
+If you've completed everything in Installation, please proceed to [Configuration]().

content/en/docs/Overview/goals.md

@@ -0,0 +1,65 @@
+---
+title: "Design Goals"
+linkTitle: "Goals"
+weight: 1
+description: >
+  Reasons behind the Elekto design
+---
+
+Elekto was originally built to support the Kubernetes Steering Committee elections, supporting the existing workflow of that community.  It's also intended to avoid several chronic issues with usage of the CIVS election system.
+
+Before adopting, or contributing to Elekto, please read these principles as the project is very unlikely to accept features which transgress any of them.
+
+## Preference Elections for Small Organizations
+
+Elekto is designed only to support "preference elections" where voters rank candidates.  We have found preference elections to offer better outcomes than other methods, such as plurality.
+
+Currently, only the Condorcet preference election algorithm is supported, but contributions of other preference election accounting methods would be very welcome.
+
+Elekto is not designed to support public governmental elections, or any election that might attract either thousands of voters, or a determined effort to compromise the system.
+
+## Simplicity
+
+The project is designed to be an extremely simple, lightweight web application.  Simplicity makes it easy to install and support in a variety of environments and platforms. This means that organizations can run Elekto as a microservice, on their own, instead of requiring a paid, hosted service.
+
+Simplicity also makes Elekto easy to fork and modify, as well as contribute to.  We chose [Flask]() as our framework with this in mind.  It's also why our container image is a simple, unified image.
+
+This does mean that changes that would substantially increase the complexity of Elekto -- such as a theme engine or porting it to Django or decomposing it into a half-dozen scalable subservices -- are unlikely to be accepted in the main project.
+
+## No Email
+
+Elekto does not send any email, or other types of messages, to anyone.  100% of Elekto interaction is via GitOps and the Web UI.
+
+This requirement is based on experience with other election systems.  Email today is a singularly unreliable way to deliver ballots or other election messages, and other channels aren't much better.  Anyone who has administered an election under CIVS can tell you that 80% of their work is troubleshooting email delivery issues.
+
+## Microservice
+
+Elekto is intended to be run as a microservice, with one Elekto instance per organization or team.  It is not intended to run as a multi-tenant service; instead, run a separate Elekto instance for each user.
+
+Each Elekto instance connects to only one metadata repository, one database, and one Oauth source.  Again, if you need multiple configurations, the solution is to run multiple Elekto instances.
+
+Elekto supports any number of elections for that one organization.
+
+## GitOps Administration
+
+The practice of defining adminstrator actions and application configuration via changes to files in a Git repository is called "GitOps".  Elekto administration is based entirely on GitOps, which offers the following advantages:
+
+* Eliminates multiple webforms, keeping the codebase smaller
+* Allows organizations to define their change and approval workflow through their git repo, including owner roles and multi-stage approval and revision
+* Provides a transparent, long-term historical record of any and all election setup changes
+* Unifies documentation and configuration
+* Reduces dependency on database hosting
+
+As such, the only data in Elekto that does not live in a git repo is data that needs to be private/secret: ballots, raw election results, and exception requests.
+
+## Transparency
+
+Elekto is aimed at public open source projects, which means that complete transparency of all election steps is required and provided.  As such, the metadata git repo and the Elekto instance are expected to be publicly readable, and no provisions have been made for running Elekto using private repos or webservers on closed networks.  
+
+Transparency is also carried out in other design decisions. For example, while only designated voters can vote in an election, any user (or any authenticated visitor) can view the details of any election.
+
+## Secret Ballot
+
+Voters must be able to vote without their individual ballots being easily snoopable, whether by other voters, election officers, or infrastructure staff.  In a small organization, infra maintainers and officers are usually voters and sometimes candidates themselves, and as such ballot identity needs to be hidden even from someone with direct access to the database.
+
+Elekto was also built with the secondary requirement of allowing voters to re-cast their ballots up until the election deadline.  However, individual ballot auditablilty was not a requirement, so it is not yet implemented (contributions welcome).  Aggregate ballot auditablity is incompatible with secrecy, and as such is out of scope.