Configuration File Reference#

Complete reference for GeoServer CLI TOML configuration files.

File Location#

Configuration files are located in the configs/ directory:

1
2
3
4
5

configs/
├── default.config.toml  # Default template (committed)
├── dev.config.toml      # Development (gitignored)
├── staging.config.toml  # Staging (gitignored)
└── prod.config.toml     # Production (gitignored)

File Format#

Configuration files use TOML (Tom’s Obvious Minimal Language) format.

GeoServer Section#

[geoserver]#

GeoServer REST API connection settings.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

[geoserver]
# GeoServer REST base URL
base_url = "http://localhost:8080/geoserver/rest"

# HTTP Basic Authentication username
username = "admin"

# HTTP Basic Authentication password
password = ""

# HTTP request timeout (e.g., "30s", "1m", "5m")
timeout = "30s"

Fields#

FieldTypeRequiredDefaultDescription
base_urlstringYes-GeoServer REST API base URL
usernamestringYes-HTTP Basic Auth username
passwordstringNo""HTTP Basic Auth password
timeoutdurationNo“30s”HTTP request timeout

PostGIS Section#

[postgis]#

PostGIS database connection settings (optional, used for publishing workflows).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

[postgis]
# Database hostname
host = "localhost"

# Database port
port = 5432

# Database name
database = "gis"

# Database username
user = "postgres"

# Database password
password = ""

# Schema name for table discovery
schema = "public"

# PostgreSQL SSL mode
# Options: disable, allow, prefer, require, verify-ca, verify-full
sslmode = "disable"

Fields#

FieldTypeRequiredDefaultDescription
hoststringYes*-Database hostname
portintegerNo5432Database port
databasestringYes*-Database name
userstringYes*-Database username
passwordstringNo""Database password
schemastringNo“public”Schema for table discovery
sslmodestringNo“disable”PostgreSQL SSL mode

*Required when using PostGIS publishing commands.

Complete Example#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

[geoserver]
base_url = "http://geoserver.example.com/geoserver/rest"
username = "admin"
password = "secure_password"
timeout = "60s"

[postgis]
host = "db.example.com"
port = 5432
database = "gis"
user = "geoserver"
password = "db_password"
schema = "public"
sslmode = "require"

File Permissions#

For security, configuration files should have restrictive permissions:

1
2

# Owner read/write only
chmod 600 configs/*.config.toml

The config validate command checks file permissions and warns if they’re too permissive.

Comments#

TOML supports comments using #:

1
2
3
4
5
6

[geoserver]
# Production GeoServer instance
base_url = "https://geoserver.example.com/geoserver/rest"
username = "admin"
# Password stored securely, not in version control
password = ""

Multi-Line Strings#

For long values, use triple quotes:

1
2
3
4
5

[geoserver]
base_url = """
http://geoserver.example.com:8080
/geoserver/rest
"""

Environment Variable Overrides#

All configuration values can be overridden by environment variables. See Environment Variables for details.

Validation#

Validate configuration files:

1

./geoserver-cli config validate --config my_config

Checks performed:

  • Required fields present
  • TOML syntax valid
  • File permissions secure
  • Value formats correct

Initialization#

Create a new configuration file from template:

1

./geoserver-cli config init --config configs/my_config.toml

This creates a file with all available settings and helpful comments.

Backward QGIS Integration with Rasters Environment Variables Forward