Engula
docs
docs

Engula Configuration Guide

Engula is fully compatible with Valkey/Redis 7.2 configuration semantics. For most deployments, you can use the Valkey configuration documentation as your primary reference and apply it directly to Engula.

Authoritative reference: https://valkey.io/topics/valkey.conf/

This guide summarizes how to use configuration files with Engula, notes command-line overrides, and highlights runtime reconfiguration. A dedicated section at the end lists Engula-specific options (placeholders for now).

Quick start

Engula loads its built-in defaults if no configuration file is provided. For production, supply a config file to ensure repeatability:

  • Default file names (conventional): engula.conf or redis.conf
  • Start with a custom file:
    • engula-server /path/to/engula.conf

When running multiple servers, replicas, etc., customize the following at minimum to keep instances isolated:

  • dir
  • logfile
  • port (unless binding to a different IP)
  • replicaof
  • requirepass
  • masterauth

Example with a custom config:

  • engula-server /etc/engula/engula.conf

Configuration file format

Engula accepts the same syntax and directives as Valkey/Redis 7.2. Lines are of the form:

  • keyword argument1 argument2 ... argumentN

Examples:

  • replicaof 127.0.0.1 6380
  • requirepass "hello world"

Notes on quoting and escaping:

  • Use single or double quotes for arguments containing spaces.
  • Single-quoted strings may contain backslash-escaped characters.
  • Double-quoted strings may additionally include ASCII symbols via backslashed hex notation, for example "\xff".

For the full catalog of supported directives, see the Valkey reference: https://valkey.io/topics/valkey.conf/

Passing arguments via the command line

All configuration directives can also be provided as command-line flags. The mapping is identical to the config file, but keywords are prefixed with --.

Example: start a replica on port 6380 of a primary on 127.0.0.1:6379

  • engula-server --port 6380 --replicaof 127.0.0.1 6379

Internally, Engula composes an in-memory temporary configuration (merging any file you provided), translating flags to the same format as engula.conf.

Changing configuration at runtime

You can inspect and modify most configuration values while Engula is running using CONFIG GET and CONFIG SET, exactly as in Valkey/Redis.

  • CONFIG GET pattern
  • CONFIG SET key value

Caveats:

  • Not all directives are mutable at runtime.
  • Runtime changes do not automatically persist to your engula.conf file.
  • To persist changes, either edit the file manually or use CONFIG REWRITE. This rewrites only fields that differ from the current runtime values, preserves comments, and omits defaults not explicitly set.

Configuring Engula as a cache

For cache-only workloads where every key can expire and memory is bounded, consider:

  • maxmemory 2mb
  • maxmemory-policy allkeys-lru

With this setup, applications need not set explicit TTLs for each key; Engula will evict keys using an approximate LRU policy as memory approaches the limit, similar to typical memcached usage.

For more details on eviction policies and behaviors, consult the Valkey documentation: https://valkey.io/topics/valkey.conf/

Compatibility with Valkey/Redis 7.2

Engula aims for full configuration compatibility with Valkey/Redis 7.2:

  • Accepts the same configuration file format and directives.
  • Supports the same command-line flags (with -- prefix).
  • Honors CONFIG GET/SET/REWRITE semantics.
  • Follows the same default behaviors unless explicitly documented otherwise.

When in doubt, defer to the Valkey configuration documentation: https://valkey.io/topics/valkey.conf/

Engula-specific configuration

The following options are unique to Engula. They are placeholders for now and reserved for future features. Unless you explicitly use them, you can rely solely on Valkey/Redis 7.2 directives.

  • engula.feature_toggle_foo

    • Placeholder. Reserved for future feature gating.

  • engula.storage_engine

    • Placeholder. Intended to select an internal storage engine.

  • engula.compaction_tuning

    • Placeholder. Reserved for background compaction tuning parameters.

  • engula.observability.exporter

    • Placeholder. Intended to configure metrics/log export targets.

  • engula.threadpool.size

    • Placeholder. Reserved for custom worker thread pool sizing.

  • engula.security.enclave_mode

    • Placeholder. Intended for enhanced isolation settings.

  • engula.network.io_model

    • Placeholder. Intended to select the I/O reactor/driver.

These options are not required and have no effect unless explicitly implemented in your Engula build. Future documentation will specify valid values, defaults, and runtime mutability.

Best practices

  • Always use a dedicated engula.conf per instance to avoid port, dir, and logfile conflicts.
  • Check CONFIG GET dir, port, and logfile after startup to verify your instance is isolated.
  • Persist runtime changes with CONFIG REWRITE before planned restarts.
  • For containerized deployments, mount engula.conf as a read-only volume and pass minimal overrides via flags for environment-specific differences.

Examples

Minimal standalone instance:

  • port 6379
  • dir /var/lib/engula
  • logfile "/var/log/engula/engula.log"

Replica of a primary at 10.0.0.10:6379:

  • port 6380
  • replicaof 10.0.0.10 6379
  • dir /var/lib/engula-replica
  • logfile "/var/log/engula/replica.log"

Cache profile with bounded memory:

  • maxmemory 1gb
  • maxmemory-policy allkeys-lru
  • appendonly no

For all other directives, behaviors, and defaults, please refer to the Valkey configuration documentation: https://valkey.io/topics/valkey.conf/