More installation and general information documentation.

jberkus · jberkus · commit d0ef432e4c50 · 2021-10-21T16:42:44.000-07:00
Signed-off-by: Josh Berkus &lt;josh@agliodbs.com&gt;
diff --git a/content/en/docs/Getting started/_index.md b/content/en/docs/Getting started/_index.md
@@ -5,88 +5,17 @@ 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
+Please see the following guides:
 
-# Installation with Conda
-conda env create -f environment.yml && conda activate elekto
-```
+Ways to install Elekto, any of:
 
-#### Setup env variables
+* [Developer Installation]({{< relref "devinstall.md" >}})
+* [Server Installation]({{< relref "installation.md" >}})
+* [Kubernetes Installation]({{< relref "kubernetes.md" >}})
 
-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`.
+And then regardless of how you installed it:
 
-```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" >}})
diff --git a/content/en/docs/Getting started/installation.md b/content/en/docs/Getting started/installation.md
@@ -3,9 +3,11 @@ title: "Installation"
 linkTitle: "Installation"
 weight: 2
 description: >
-  Full installation documentation
+  Full server installation documentation
 ---
 
+This guide walks you through installing Elekto by hand on a server or VM.
+
 # Installation Concepts
 
 For Elekto to run in production, you need the following small application stack: 
@@ -16,7 +18,7 @@ For Elekto to run in production, you need the following small application stack:
 * A GitHub repository
 * An Oauth authentication source
 
-Elekto can be installed either as a native application, or as a container.
+Elekto can be installed either as a native application, or as a container.  The instructions below cover installation as a native application. For installation in a container, see [Kubernetes installation]({{< relref "kubernetes.md" >}})
 
 ## Installing Requirements and Python Binaries
 
diff --git a/content/en/docs/Overview/_index.md b/content/en/docs/Overview/_index.md
@@ -3,9 +3,11 @@ title: "Overview"
 linkTitle: "Overview"
 weight: 1
 description: >
-  Understand the working of elekto.
+  Overview of Elekto Project.
 ---
 
-The application requires a [meta]() repository to store election meta files. The meta repository is the single source of truth for the application and is managed by gitops, all the tasks like creating an election, adding/removing voters to the list are managed by raising specific pull requests in the meta repository. See our detailed instruction [docs](/docs/README.md)
+The Elekto Project is a [CNCF](https://cncf.io) accessory project which develops online voting software intended for use by the CNCF itself and by open source cloud native projects.
 
-![architecture.png](arch.png)
+Originally written for the needs of the Kubernetes and OpenTelemetry projects, the Elekto software is designed to support online preference voting for open source projects.  Based on a GitOps workflow and Condorcet election accounting, Elekto supports your steering committee and TOC elections, committee decision making, and anywhere else a formal project vote is required among a small pool of candidates or options.
+
+Read on to learn more about Elekto's [goals]({{< relref "goals.md" >}}) and [architecture]({{< relref "architecture.md" >}}).
diff --git a/content/en/docs/Overview/architecture.md b/content/en/docs/Overview/architecture.md
@@ -0,0 +1,11 @@
+---
+title: "Architecture"
+linkTitle: "Architecture"
+weight: 1
+description: >
+  Understand the working of elekto.
+---
+
+The application requires a git repository to store election meta files. The meta repository is the single source of truth for the application and is managed by gitops, all the tasks like creating an election, adding/removing voters to the list are managed by raising specific pull requests in the meta repository.
+
+![architecture.png](arch.png)
diff --git a/content/en/docs/Overview/goals.md b/content/en/docs/Overview/goals.md
@@ -6,9 +6,9 @@ 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.
+Elekto was originally built to support the [Kubernetes Steering Committee elections](https://github.com/kubernetes/steering/blob/master/elections.md), supporting the existing workflow of that community.  It's also intended to avoid several chronic issues with usage of the [CIVS election system](https://civs1.civs.us/).
 
-Before adopting, or contributing to Elekto, please read these principles as the project is very unlikely to accept features which transgress any of them.
+Before adopting, or contributing to Elekto, please read these principles as they give you a broad idea of what kinds of features and changes the project is interested in or likely to implement.
 
 ## Preference Elections for Small Organizations
 
@@ -22,7 +22,7 @@ Elekto is not designed to support public governmental elections, or any election
 
 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.
+Simplicity also makes Elekto easy to fork and modify, as well as contribute to.  We chose [Flask](https://flask.palletsprojects.com/en/2.0.x/) 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.
 
