Configuration Management#

Best practices for managing GeoServer CLI configuration across environments.

Environment Strategy#

Separate Configs per Environment#

1
2
3
4
5
configs/
├── default.config.toml  # Template (committed)
├── dev.config.toml      # Development (gitignored)
├── staging.config.toml  # Staging (gitignored)
└── prod.config.toml     # Production (gitignored)

Using Environment Variables#

1
2
3
4
5
6
7
8
9
# Development
export GEOSRVCLI_CONFIG=dev
export GEOSRVCLI_ENDPOINT=http://dev-geoserver:8080/geoserver/rest
export GEOSRVCLI_DEFAULT_WORKSPACE=dev

# Production
export GEOSRVCLI_CONFIG=prod
export GEOSRVCLI_ENDPOINT=https://geoserver.example.com/geoserver/rest
export GEOSRVCLI_DEFAULT_WORKSPACE=production

Security Practices#

File Permissions#

1
2
3
4
5
# Secure config files (read/write for owner only)
chmod 600 configs/*.config.toml

# Validate permissions
./geoserver-cli config validate

Credential Management#

DO:

Store passwords in config files with secure permissions
Use environment variables for CI/CD
Use QGIS Auth Manager for QGIS exports

DON’T:

Commit passwords to version control
Share config files with passwords via insecure channels
Use --include-credentials in production QGIS exports

Environment Variables for Secrets#

1
2
3
# Use environment variables instead of config files for passwords
export GEOSRVCLI_PASSWORD=$(cat ~/.secrets/geoserver_password)
./geoserver-cli workspace list

Configuration Precedence#

Remember the precedence order:

CLI flags (highest)
Environment variables
Config file
Defaults (lowest)

Example#

1
2
3
4
5
6
# Config file has: base_url = "http://default:8080/geoserver/rest"
# Environment has: GEOSRVCLI_ENDPOINT=http://env:8080/geoserver/rest
# CLI flag: --base-url http://cli:8080/geoserver/rest

# Result: Uses CLI flag value (http://cli:8080/geoserver/rest)
./geoserver-cli workspace list --base-url http://cli:8080/geoserver/rest

Using direnv#

Setup#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Install direnv (if not installed)
# macOS: brew install direnv
# Linux: apt-get install direnv

# Create .envrc
cat > .envrc <<EOF
export GEOSRVCLI_CONFIG=dev
export GEOSRVCLI_DEFAULT_WORKSPACE=dev
export GEOSRVCLI_ENDPOINT=http://localhost:8080/geoserver/rest
PATH_add ./bin
EOF

# Allow direnv
direnv allow

Benefits#

Automatic environment setup when entering directory
Per-project configuration
No manual export commands needed

CI/CD Configuration#

GitLab CI Example#

1
2
3
4
5
6
7
variables:
  GEOSRVCLI_CONFIG: prod
  GEOSRVCLI_ENDPOINT: ${GEOSERVER_URL}/rest

deploy:
  script:
    - ./geoserver-cli publish postgis --all -w production

GitHub Actions Example#

1
2
3
4
5
env:
  GEOSRVCLI_CONFIG: prod
  GEOSRVCLI_ENDPOINT: ${{ secrets.GEOSERVER_URL }}/rest
  GEOSRVCLI_USERNAME: ${{ secrets.GEOSERVER_USERNAME }}
  GEOSRVCLI_PASSWORD: ${{ secrets.GEOSERVER_PASSWORD }}

Configuration Validation#

Pre-Deployment Checks#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
#!/bin/bash
# validate-config.sh

set -e

CONFIG=${1:-default}

echo "Validating configuration: $CONFIG"
./geoserver-cli config validate --config $CONFIG

echo "Showing resolved configuration:"
./geoserver-cli config show --config $CONFIG

echo "Testing connection:"
./geoserver-cli workspace list --config $CONFIG

Troubleshooting#

Config Not Found#

1
2
3
4
5
# Check config file exists
ls -la configs/$GEOSRVCLI_CONFIG.config.toml

# Use full path if needed
./geoserver-cli workspace list --config /full/path/to/config.toml

Wrong Environment#

1
2
3
4
5
# Check active config
./geoserver-cli config show

# Verify environment variable
echo $GEOSRVCLI_CONFIG

Permission Issues#

1
2
3
4
5
# Check file permissions
ls -la configs/*.config.toml

# Fix if needed
chmod 600 configs/*.config.toml