Merge pull request #7 from elekto-io/user-docs

WIP: Add user documentation

Author: jberkus

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

@@ -5,88 +5,13 @@ weight: 2
 description: >
   Start using elekto for your organisation.
 ---
-#### Create a development environment
 
-The application is written in `python` using `flask` and `sqlalchemy`. This repository ships a `requirements.txt` and  a `environment.yml` for conda users.
+Elekto is a DIY service, so in order to start using it, you're going to have to install it:
 
-```bash
-# Installation with pip 
-pip install -r requirements.txt
+* [Developer Installation]({{< relref "devinstall.md" >}})
+* [Server Installation]({{< relref "installation.md" >}})
+* [Kubernetes Installation]({{< relref "kubernetes.md" >}})
 
-# Installation with Conda
-conda env create -f environment.yml && conda activate elekto
-```
+And then regardless of how you installed it:
 
-#### Setup env variables
-
-The repository has a `.env.example` file which can be used as a template for `.env` file, update the environment file after copying from `.env.example`.
-
-```bash
-# create a new .env file from .env.example
-cp .env.example .env
-```
-
-Set the basic information about the application in the upper section
-```bash
-APP_NAME=k8s.elections     # set the name of the application
-APP_ENV=development        # development | production   
-APP_KEY=                   # random secret key (!! important !!)
-APP_DEBUG=True             # True | False (production)
-APP_URL=http://localhost   # Url where the application is hosted
-APP_PORT=5000              # Default Running port for development 
-APP_HOST=localhost         # Default Host for developmemt 
-```
-
-Update the database credentials, 
-```bash
-DB_CONNECTION=mysql        # Mysql is only supported 
-DB_HOST=localhost
-DB_PORT=3306
-DB_DATABASE=name          
-DB_USERNAME=user
-DB_PASSWORD=password
-```
-
-Update the meta repository info
-```bash
-META_REPO=https://github.com/elekto-io/elekto.meta.test.git
-META_DEPLOYMENT=local
-META_PATH=meta
-META_BRANCH=main
-META_SECRET=db5a951969c379e75d0bf15ad6ff8b4a36fbeb02  # same as webhook of the same meta repository
-```
-
-Update the Oauth info, create an github oauth app if already not created.
-```bash
-GITHUB_REDIRECT=/oauth/github/callback
-GITHUB_CLIENT_ID=d79f002c1d2e3cf20521
-GITHUB_CLIENT_SECRET=2f64fff6612c46f87314ad5bb81d05c8fd29c561
-```
-
-#### Migrate and Sync DB with Meta
-
-The `console` script in the repository is used to perform all the table creations and syncing of the meta. 
-
-```bash
-# to migrate the database from command line 
-python console --migrate 
-```
-
-To sync the database with the meta files 
-
-```bash
-# to the sync the database with the meta
-python console --sync
-```
-
-#### Run the application Server locally 
-
-The flask server will start on `5000` by default but can be changed using `--port` option.
-
-```bash
-# to run the server on default configs
-python console --run
-
-# to change host and port
-python console --port 8080 --host 0.0.0.0 --run
-```
+* [Configuration]({{< relref "installation.md" >}})

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

@@ -0,0 +1,219 @@
+---
+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 ones created for other purposes, and giving each Elekto instance its own secret key.
+
+The Oauth App must have the following settings:
+
+* Application Name: whatever you've named your Elekto instance
+* Homepage URL: the url of your Elekto instance
+* Authorization Callback URL: `https://your.elekto.domain/oauth/github/callback`  (note that this can be changed in ENV)
+
+Once you create the Oauth App, GitHub will create a ClientID for it, which you populate in GITHUB_CLIENT_ID in ENV.  You then create a new Oauth secret under the app and copy the value for that, and that gets populated in GITHUB_CLIENT_SECRET.
+
+#### GitHub Repository Webhook
+
+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 owner).  
+
+The Webhook should have the following settings:
+
+* Payload URL: `https://your.election.domain/v1/webhooks/meta/sync`
+* Content type: application/json
+* Secret set to the same as META_SECRET
+* Enable SSL Verification
+* Just The Push Event
+* Check "Active" to turn it on
+
+This "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 a 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* 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.
+
+Example: `2400229255`
+
+**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 backends 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. Must be a parent directory. 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.  The directory may be absolute or relative; if it is relative, it will be under the Eletko source directory.  Otherwise it 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 its 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`