Skip to content

Administration#

This section covers the tools and procedures for managing a Concourse deployment.

CLI Tools#

Concourse includes several command-line tools for server management. All tools are located in the bin/ directory of the Concourse installation.

concourse#

The main control command for starting, stopping, and managing the server.

1
2
3
4
concourse start      # Start the server
concourse stop       # Gracefully shut down
concourse status     # Check if the server is running
concourse version    # Display version information

concourse monitor#

A real-time monitoring dashboard for server metrics. Supports multiple subcommands for different metric categories.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
concourse monitor overview      # General health
concourse monitor storage       # Disk and storage metrics
concourse monitor operations    # Operation counts and timing
concourse monitor transactions  # Transaction statistics
concourse monitor locks         # Lock contention analysis
concourse monitor heap          # JVM heap usage
concourse monitor gc            # Garbage collection metrics
concourse monitor threads       # Thread pool statistics
concourse monitor transport     # Buffer-to-Database metrics
concourse monitor compaction    # Compaction progress

Options:

Flag Description
--json Output in machine-readable JSON format
--watch Continuously refresh the display
--interval <seconds> Refresh interval for watch mode
-e <environment> Monitor a specific environment

concourse data#

Tools for managing the stored data files.

1
2
concourse data repair   # Detect and fix data inconsistencies
concourse data compact  # Trigger storage compaction

Environments#

Concourse organizes data into isolated environments. Each environment operates as an independent database instance with its own storage, indexes, and access controls.

Default Environment#

When a client connects without specifying an environment, it uses the default environment (configurable via default_environment in concourse.yaml).

Creating Environments#

Environments are created automatically when a client first connects to them. No manual setup is required.

1
2
3
4
// Java - connect to the "production" environment
Concourse concourse = Concourse.at()
    .environment("production")
    .connect();

1
2
// CaSH
cash --environment production

Environment Isolation#

Each environment is completely isolated. Records, keys, and values in one environment are invisible to clients connected to another environment. This makes environments suitable for separating development, staging, and production data, or for multi-tenant deployments.

User Management#

Initial Setup#

Concourse is configured with a default administrator account:

  • Username: admin (configurable via init_root_username)
  • Password: admin (configurable via init_root_password)

Change Default Credentials

Always change the default administrator password immediately after installation.

You can set the initial credentials via concourse.yaml:

1
2
3
4
init:
  root:
    username: admin
    password: your-secure-password

Or via the CONCOURSE_INIT_ROOT_PASSWORD environment variable when running in Docker.

Managing Users#

User management is handled through the server’s management interface. Users can be granted or revoked access to specific environments.

See Authentication for details on the authentication model and access control.

Plugins#

Concourse supports a plugin system for extending server functionality. See Plugins for details on installing, using, and developing plugins.

Installing Plugins#

1
2
3
4
5
# Install a local plugin package
concourse plugin install /path/to/plugin.zip

# Install from the marketplace
concourse plugin install plugin-name

Plugin Data#

Plugins can store persistent data that survives installs, upgrades, and uninstalls. Plugin data is stored in the directory configured by plugins.data_directory (default: ~/concourse/plugin-data).

Monitoring#

Concourse provides multiple monitoring options for production deployments.

JMX#

Concourse exposes metrics via JMX MBeans on the configured jmx_port (default: 9010). You can connect with any JMX client (e.g., JConsole, VisualVM) to inspect server metrics.

Prometheus#

Enable the Prometheus metrics endpoint to expose metrics in a scrapable format:

1
2
3
monitoring:
  export_metrics: true
  metrics_port: 9091

Metrics are available at http://<host>:9091/metrics in Prometheus exposition format.

OpenTelemetry#

For push-based monitoring, enable OpenTelemetry to send metrics to a remote collector:

1
2
3
4
5
monitoring:
  enable_opentelemetry: true
  opentelemetry_endpoint: http://collector:4317
  opentelemetry_protocol: grpc
  opentelemetry_interval: 15

This supports Datadog, New Relic, Honeycomb, and any OpenTelemetry-compatible collector.

Monitor CLI#

The concourse monitor command provides real-time dashboards directly in the terminal. Use --json for machine-readable output suitable for scripts and automation.

Debugging#

Retrieve a JVM Heap Dump#

A heap dump captures the state of all objects in the JVM’s memory. This is useful for diagnosing memory issues.

Connect to the server via JMX on the configured jmx_port and trigger a heap dump through the management MBean, or use the jmap tool if a JDK is installed:

1
jmap -dump:format=b,file=heap.hprof <pid>

Retrieve a JVM Thread Dump#

A thread dump shows the state of all threads, which helps diagnose deadlocks or performance bottlenecks.

1
jstack <pid> > threads.txt

Ad-hoc Debugging with JMX#

Connect to the JMX port with JConsole or VisualVM to:

  • Monitor heap usage, thread counts, and GC activity in real time
  • Inspect MBean attributes for Concourse-specific metrics
  • Trigger operations like garbage collection
1
jconsole localhost:9010

Remote Debugging#

Enable remote debugging by setting remote_debugger_port in concourse.yaml:

1
remote_debugger_port: 5005

Then attach a debugger from your IDE to the configured port.

Upgrade Procedure#

See the Upgrade page for instructions on upgrading Concourse to a newer version.

Data Export#

Concourse supports exporting data to CSV and Excel formats via the export tools. See Export for details.

Backup and Recovery#

Data Directories#

All persistent data is stored in two directories:

  • Buffer directory (buffer_directory): Write-optimized storage
  • Database directory (database_directory): Read-optimized indexed storage

To back up Concourse, stop the server and copy both directories. To restore, stop the server and replace both directories with the backup copies.

Stop Before Backup

Always stop Concourse Server before taking a backup to ensure data consistency. Do not copy data directories while the server is running.