⚙️Configuring and Running Kepler

Setting up a Host

Kepler is a Rust application which can serve Controllers and Clients over HTTP. To build Kepler yourself, you need only Cargo and Git.

First, clone the Kepler repository:

git clone https://github.com/spruceid/kepler

Next, choose a location which the Hosts can use to store content uploaded by Clients. The easiest way is to use the local filesystem. Make sure that the path exists before running the application. For example:

mkdir -p ./kepler/blocks
KEPLER_STORAGE_BLOCKS_TYPE="Local"
KEPLER_STORAGE_BLOCKS_PATH="./kepler/blocks"

Finally, decide on a secret for this Kepler instance. This secret MUST be encoded as a URL-safe unpadded base 64 string. It is used to derive the identifiers and cryptographic key pairs for the Hosts belonging to this kepler instance. For example:

KEPLER_KEYS_TYPE="Static"
KEPLER_KEYS_SECRET="c29tZSBzdHVmZiB3aGljaCBpcyBhIHNlY3JldCBzdHJpbmc"

With these environment variables set, Kepler can be run in a few ways (these are example config options for testing things out, do not use this secret value in production):

With Cargo

Running Kepler from source with Cargo is easy:

KEPLER_STORAGE_BLOCKS_TYPE="Local" \
KEPLER_STORAGE_BLOCKS_PATH="./kepler/blocks" \
KEPLER_KEYS_TYPE="Static" \
KEPLER_KEYS_SECRET="c29tZSBzdHVmZiB3aGljaCBpcyBhIHNlY3JldCBzdHJpbmc" \
cargo run

To see debug log output, you can add the RUST_LOG=debug environment variable.

Build and Run

Kepler can also be built from source in release mode:

cargo build --release
KEPLER_STORAGE_BLOCKS_TYPE="Local" \
KEPLER_STORAGE_BLOCKS_PATH="./kepler/blocks" \
KEPLER_KEYS_TYPE="Static" \
KEPLER_KEYS_SECRET="c29tZSBzdHVmZiB3aGljaCBpcyBhIHNlY3JldCBzdHJpbmc" \
target/release/kepler

Docker

Kepler is also provided via the dockerfile in the repo.

Additional Configuration Options

There are a number of configuration options available to Kepler deployments. They can be configured via environment variables or a kepler.toml configuration file. The only required config options are the Host's secret and the content storage config. For more information, see the Configuration section of the Kepler readme.

CORS

If running Kepler locally for development purposes, CORS support can be enabled via the KEPLER_CORS config option:

KEPLER_CORS=true

Notes on production deployment

When deploying in a production environment, the following points are STRONGLY RECOMMENDED:

• Back up the value of KEPLER_KEYS_SECRET in a secure location

• Do not configure KEPLER_KEYS_SECRET via the kepler.toml config file, only with an environment variable.

• Make use of the KEPLER_STORAGE_DATABASE configuration option. By default it will use an in-memory instance of SQLite which will NOT be persisted. In production it will be essential to persist this information, either in an on-disk SQLite file or an instance of PostgreSQL.