Configuration

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. 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

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

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

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