Configuration#

Concourse is configured through YAML files. The server reads its configuration from concourse.yaml in the conf/ directory, and the client drivers read connection settings from concourse_client.yaml.

Server Configuration#

Configuration File#

The primary configuration file is concourse.yaml, located at:

1	`concourse-server/conf/concourse.yaml`

All settings have sensible defaults. You only need to specify values for settings you want to change.

Development Overlays#

For local development, create a concourse.yaml.dev file in the same directory. Settings in the .dev file override those in the base concourse.yaml. The .dev file should be excluded from version control.

Legacy Format

Concourse also supports the older .prefs format (concourse.prefs). YAML files are preferred and take precedence when both exist, with one exception: concourse.prefs.dev takes precedence over concourse.yaml to honor the convention that local development overrides always win. Client configuration (concourse_client.yaml vs concourse_client.prefs) follows the same YAML-wins rule without the dev-overlay exception.

Core Settings#

Network#

Setting	Default	Description
`client_port`	`1717`	Listener port for client connections
`http_port`	`0` (disabled)	Listener port for HTTP/S connections. Set to 0 to disable
`jmx_port`	`9010`	Listener port for JMX management
`shutdown_port`	(auto)	Listener port for shutdown commands, which the server accepts only from its own host
`remote_debugger_port`	`0` (disabled)	Listener port for remote debugger
`management_port`	(auto)	Listener port for management CLIs, which the server accepts only from its own host

Storage#

Setting	Default	Description
`buffer_directory`	`~/concourse/buffer`	Path to write-optimized buffer storage
`database_directory`	`~/concourse/db`	Path to read-optimized database storage
`buffer_page_size`	`8KB`	Size of each buffer page

Performance Tip

For optimal performance, place the buffer_directory and database_directory on separate disk partitions, ideally on separate physical devices.

Memory#

Setting	Default	Description
`heap_size`	(auto)	JVM heap size allocation

Concourse automatically chooses a heap size based on available system memory:

System Memory	Recommended Heap Size
Less than 2GB	1/2 of system memory
2GB to 4GB	1GB
Greater than 4GB	1/4 of system memory, up to 8GB

Avoid Oversizing

Setting the heap too large can cause longer garbage collection pauses and interfere with memory-mapped file performance.

Environment#

Setting	Default	Description
`default_environment`	`default`	Default environment for connections that do not specify one

Java#

Setting	Default	Description
`java_home`	(auto)	Path to Java installation
`force_g1gc`	`false`	Force G1 garbage collector on JDK 8

Logging#

Setting	Default	Description
`log_level`	`INFO`	Logging verbosity: `ERROR`, `WARN`, `INFO`, or `DEBUG`
`enable_console_logging`	`false`	Also print logs to the console

Each log level includes all less verbose levels. Use DEBUG only for diagnosing issues, as it can impact performance.

Security#

Setting	Default	Description
`init_root_username`	`admin`	Initial administrator username
`init_root_password`	`admin`	Initial administrator password
`access_credentials_file`	`{concourse.home}/.access`	Path to credentials storage

Nested YAML form is also supported:

init:
  root:
    username: admin
    password: admin

Change Default Credentials

Always change the default admin password after initial setup.

Data Transport#

The transporter moves data from the write-optimized Buffer to the read-optimized Database in the background. Concourse supports two strategies:

Batch Transporter (Default)#

The batch transporter processes large batches of data per pass and indexes without blocking operations until merge time. This provides higher overall throughput.

1	`transporter: batch`

Streaming Transporter#

The streaming transporter processes smaller batches more frequently. It provides consistent throughput but may cause performance degradation under high concurrent load.

1	`transporter: streaming`

Advanced Transport Configuration#

transporter:
  type: batch
  num_threads: 2
  passive: false

Setting	Default	Description
`type`	`batch`	Transport strategy: `batch` or `streaming`
`num_threads`	`1`	Number of transport threads
`passive`	`false`	Allow other operations to preempt the transporter

Spill Configuration#

While Concourse Server builds a new data file, it holds the data that it indexes for that file in memory until it writes the file. Spilling moves that data to temporary files on disk when the Java heap fills up, so building a large data file doesn’t run out of memory. The data file is the same either way.

Setting	Default	Description
`storage.spill.heap_usage_threshold`	`0`	Share of the maximum heap, from 0 to 1, in use after a garbage collection that triggers a spill (0 = disabled outside of upgrades)
`storage.spill.use_system_temp_dir`	`false`	Put the temporary files in the system’s temporary directory instead of the `database_directory`

storage:
  spill:
    heap_usage_threshold: 0.8
    use_system_temp_dir: false

Every upgrade spills at a threshold of 0.8 or lower while it runs. A storage.spill.heap_usage_threshold below 0.8 stays in effect; 0 or a value above 0.8 becomes 0.8 for the upgrade. The temporary files go in a directory named .spills. When Concourse Server starts, it deletes the files that were left in the database_directory. It leaves the system’s temporary directory alone, because other programs can share it.

Search Configuration#

Setting	Default	Description
`max_search_substring_length`	`40`	Maximum substring length indexed for full-text search

Set this to the longest word you expect in search queries. The default of 40 characters accommodates the longest English words.

Experimental Settings#

These settings are experimental and may change in future versions.

Setting	Default	Description
`enable_compaction`	`false`	Enable background storage optimization
`enable_async_data_reads`	`false`	Use multiple threads for disk reads
`enable_efficient_metadata`	`false`	Use memory-efficient metadata (~33% heap reduction)
`enable_search_cache`	`false`	Cache full-text search indexes in memory
`enable_verify_by_lookup`	`false`	Optimize verify operations with lookup records

Compaction#

When enabled, compaction automatically merges and reorganizes data files in the background to improve read performance. This runs continuously without disrupting reads or writes.

1	`enable_compaction: true`

Async Data Reads#

When enabled, Concourse uses multiple threads to read data from disk concurrently. This is most beneficial for data that exceeds the in-memory cache, especially search indexes.

1	`enable_async_data_reads: true`

Efficient Metadata#

Reduces the heap space needed for storage metadata by approximately one-third. May slightly increase CPU usage per operation.

1	`enable_efficient_metadata: true`

Plugin Configuration#

Setting	Default	Description
`plugins.bootstrapper`	`external`	Plugin discovery method: `external` or `internal`
`plugins.data_directory`	`~/concourse/plugin-data`	Path to durable plugin storage

1
2
3

plugins:
  bootstrapper: external
  data_directory: /path/to/plugin-data

The external bootstrapper allows plugins compiled against newer Java versions to work with older servers (e.g., a Java 21 plugin on a Java 8 server). See Plugins for details.

HTTP Configuration#

Setting	Default	Description
`http_port`	`0`	HTTP listener port (0 = disabled)
`http_enable_cors`	`false`	Enable CORS headers
`http_cors_default_allow_origin`	`*`	Allowed CORS origins
`http_cors_default_allow_headers`	`*`	Allowed CORS headers
`http_cors_default_allow_methods`	`*`	Allowed CORS methods

Monitoring Configuration#

Concourse supports Prometheus metrics scraping and OpenTelemetry push for observability. See Administration for details on monitoring tools.

monitoring:
  export_metrics: true
  metrics_port: 9091
  enable_opentelemetry: false
  opentelemetry_endpoint: http://localhost:4317
  opentelemetry_protocol: grpc
  opentelemetry_interval: 15

Setting	Default	Description
`monitoring.export_metrics`	`false`	Enable Prometheus metrics endpoint
`monitoring.metrics_port`	`9091`	Port for metrics HTTP endpoint
`monitoring.enable_opentelemetry`	`false`	Enable OTLP push
`monitoring.opentelemetry_endpoint`	`http://localhost:4317`	OTLP collector URL
`monitoring.opentelemetry_protocol`	`grpc`	OTLP transport: `grpc` or `http`
`monitoring.opentelemetry_interval`	`15`	Push interval in seconds

Cluster Configuration#

For distributed deployments, configure the cluster section. See Distributed Concourse for details.

cluster:
  nodes:
    - host1:1717
    - host2:1717
    - host3:1717
  replication_factor: 2

Client Configuration#

Client drivers read connection settings from concourse_client.yaml (or concourse_client.prefs). This file can be placed in the working directory or specified explicitly.

# concourse_client.yaml
host: localhost
port: 1717
username: admin
password: admin
environment: default

Setting	Default	Description
`host`	`localhost`	Server hostname
`port`	`1717`	Server port
`username`	`admin`	Authentication username
`password`	`admin`	Authentication password
`environment`	`default`	Default environment

Using Client Configuration in Java#

// Java
// Connect using default config file
Concourse concourse = Concourse.connect();

// Connect using a specific config file
Concourse concourse = Concourse.connect(
        Paths.get("/path/to/concourse_client.yaml"));

// Or use a pre-loaded configuration handler
ConcourseClientConfiguration config =
        ConcourseClientConfiguration.from(
                Paths.get("/path/to/concourse_client.yaml"));
Concourse concourse = Concourse.connect(config);

Environment Variable Overrides#

Client configuration values can be overridden by environment variables:

Variable	Overrides
`CONCOURSE_HOST`	`host`
`CONCOURSE_PORT`	`port`
`CONCOURSE_USERNAME`	`username`
`CONCOURSE_PASSWORD`	`password`
`CONCOURSE_ENVIRONMENT`	`environment`