Configuration and Setup
Elekto’s configuration is divided into three parts:
- Oauth and GitHub configuration
- Runtime environment
- 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.
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:
- 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
.bashrcfor 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.
What follows are the ENV variables that must be set for Elekto to run.
Required Name of the Elekto instance you are running. Displays in some parts of the UI. For user information only.
Optional Status of this Elekto instance, for CI/CD purposes. Not used internally by Elekto.
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.
Required Whether to run in Debug mode for troubleshooting purposes. In Debug mode, will output stack traces for errors and reload templates.
Optional URL of the Elekto instance. Used by some uWSGI and/or Nginx configurations. Not used internally by Elekto.
Optional Used in some uWSGI start scripts, and when running Flask in standalone mode. Port on which to serve Elekto.
Optional Used in some webserver startup scripts, and by the Flask server in standalone mode. Name of the host served by this Elekto instance.
Optional Whether to serve uWSGI over HTTP or via a local Unix socket. Used by some startup scripts; see
entrypoint.sh for an example.
Optional: Integer. Minimum length for a voter-ballot passphrase in order to deter hacking. Set to 6 if left blank.
Required Which database connection type to use. Currently only PostgreSQL, MySQL, and SQLite backends are supported.
Required The URL, IP, or hostname of the database server. Ignored if using SQLite (set to
Required The network port for the database server. Ignored if using SQLite (set to
Optional Used only for SQLite. Path to the database filesystem.
Required Login user for the Elekto database. Not used by SQLite.
Required Authentication password for the Elekto database. Not used by SQLite.
Required GIT clone URL for the repository which contains the election configurations. Should be the
.git link, not the
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
Optional Reserved for future advanced configuration use.
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.
Required Which git branch has the merged version of the election data. Defaults to
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.
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.
Required Flask path for the GitHub authentication callback. Defaults to
/oauth/github/callback, and there’s no good reason to change it.
Required The Client ID from the GitHub Oauth Application.
Required The Client Secret from the GitHub Oauth Application.