Skip to content

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.

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
remote_debugger_port 0 (disabled) Listener port for remote debugger

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:

1
2
3
4
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#

1
2
3
4
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

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.

1
2
3
4
5
6
7
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.

1
2
3
4
5
6
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.

1
2
3
4
5
6
# 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#

1
2
3
4
5
6
7
8
// Java
// Connect using default config file
Concourse concourse = Concourse.connect();

// Connect using specific config file
Concourse concourse = Concourse.at()
    .prefs("/path/to/concourse_client.yaml")
    .connect();

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