Comment on page
⚙
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
Build and Run
Docker
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.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
Kepler is also provided via the
dockerfile
in the repo.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.If running Kepler locally for development purposes, CORS support can be enabled via the
KEPLER_CORS
config option:KEPLER_CORS=true
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 thekepler.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.
Last modified 4mo ago