# Server Configuration

These parameters control and fine-tune various default server-settings in Typesense.

TIP

We manage the following parameters for you in Typesense Cloud. So this section only applies if you're self-hosting Typesense.

# Using Command Line Arguments

Command line arguments can be passed to the server as --parameter=value.

# Common Parameters

Parameter Required Description
--config false Path to the configuration file. If you use this argument, you can define all of the other command line arguments in a configuration file.
--api-key true A bootstrap admin API key that allows all operations. Be sure to create additional keys with specific ACLs using the key management API.

NOTE: Don't expose this admin API key to your browser JS client: use the key management API to create search-only or scoped API keys.
--data-dir true Path to the directory where data will be stored on disk.

# CORS

Parameter Required Description
--enable-cors false Allow JavaScript client to access Typesense directly from the browser.
--cors-domains false Comma separated list of domains which are allowed for CORS. E.g. https://example.com,https://example2.com (no trailing slashes!)

# Analytics

Parameter Required Description
--enable-search-analytics false Allow search queries to be aggregated for query analytics. Default: false
--analytics-dir false Directory for Typesense to store analytics data.
--analytics-flush-interval false Interval (in seconds) that determines how often the search query aggregations are persisted to storage. Default: 3600 (every hour)
--analytics-minute-rate-limit false Maximum number of analytics events that can be sent per minute. Default: 5

# Logging

Parameter Required Description
--log-dir false By default, Typesense logs to stdout and stderr. To enable logging to a file, provide a path to a logging directory.
--enable-access-logging false Logs the API requests and corresponding IP addresses to the log-dir. Default: false
--enable-search-logging false Logs the search API request + payload right at the start of search request lifecycle. Default: false
--log-slow-requests-time-ms false Requests that take over this amount of time (in milliseconds) are logged. Default: -1 which disables slow request logging.

You can also dynamically enable slow requests logging via the /config API.

# Networking

Parameter Required Description
--api-address false Address to which Typesense API service binds. Default: 0.0.0.0
--api-port false Port on which Typesense API service listens. Default: 8108
--peering-address false Internal IP address to which Typesense peering service binds. If this parameter is not specified, Typesense will attempt to use the first available internal IP.
--peering-port false Port on which Typesense peering service listens. Default: 8107
--peering-subnet false Internal subnet that Typesense should use for peering, e.g. 192.160.1.0/24.

# SSL / HTTPS

Parameter Required Description
--ssl-certificate false Path to the SSL certificate file. You must also define ssl-certificate-key to enable HTTPS.
--ssl-certificate-key false Path to the SSL certificate key file. You must also define ssl-certificate to enable HTTPS.
--ssl-refresh-interval-seconds false Frequency of automatic reloading of SSL certs from disk. Default: 8 * 60 * 60.

# Clustering

Parameter Required Description
--nodes false Path to file containing comma separated string of all nodes in the cluster.
--reset-peers-on-error false Forcefully reset node's peers on an irrecoverable clustering error. This could cause intermittent data loss and is only attempted as a last-resort.

# Resource Usage

Parameter Required Description
--thread-pool-size false Number of threads used for handling concurrent requests. Default: NUM_CORES * 8.
--num-collections-parallel-load false Number of collections that are loaded in parallel during start up. Default: NUM_CORES * 4.
--num-documents-parallel-load false Number of documents per collection that are indexed in parallel during start up. Default: 1000.
--cache-num-entries false Number of entries to be stored in the LRU cache used for storing search query responses. Default: 1000.
--disk-used-max-percentage false Reject writes when used disk space exceeds this percentage. Default: 100 (never reject).
--memory-used-max-percentage false Reject writes when used memory usage exceeds this percentage. Default: 100 (never reject).
--healthy-read-lag false Reads are rejected if the updates lag behind this threshold. Default: 1000.
--healthy-write-lag false Writes are rejected if the updates lag behind this threshold. Default: 500.
--snapshot-interval-seconds false Frequency of replication log snapshots. Default: 3600 follower recovery.

NOTE: Frequent snapshotting helps in faster recovery from a cold start. However, if this value is too low for a large dataset, repeated snapshotting can actually slow down follower recovery.
--db-compaction-interval false Frequency of automatic on-disk database compaction. Default: 604,800 (7 days)

If you do frequent collection drops and recreates, you want to considering setting this to say 24 hours.
--skip-writes false Starts Typesense in a mode that does not read writes from the Raft log. This is useful when the server has crashed due to some recent bad writes that you want to skip over temporarily.
--filter-by-max-ops false Maximum number of operators permitted in filter_by clause. Default: 100
--max-per-page false Max number of hits permitted per page. Default: 250

# Using a Configuration File

As an alternative to command line arguments, you can also configure Typesense server through a configuration file or via environment variables.

Command line arguments are given the highest priority, while environment variables are given the least priority.

Our Linux DEB/RPM packages install the configuration file at /etc/typesense/typesense-server.ini.

The configuration file uses a simple INI format:

You can use any of the parameters from the table above without the preceding -- in the typesense-server.ini file.

# Using Environment Variables

If you wish to use environment variables, you can do that too. The environment variables map to the command line arguments documented above: just use CAPS and underscores instead of hyphens, and prefix the variable names with TYPESENSE_.

For example, use TYPESENSE_DATA_DIR for the --data-dir argument.

Last Updated: 10/3/2024, 3:32:44 AM