Configuration

eocube reads a single, kubectl-style configuration file. It holds named authentication sources, storage definitions, stac endpoints, mcp settings, and contexts that tie them together. A global --context option selects which context a command uses.

File location

By default the file lives at:

~/.config/eocube/eocube.yml

The location honours $XDG_CONFIG_HOME (so $XDG_CONFIG_HOME/eocube/eocube.yml when that variable is set), and can be overridden entirely with the EOCUBE_CONFIG environment variable:

export EOCUBE_CONFIG=/path/to/eocube.yml

Security

The file stores your OIDC refresh tokens, so eocube creates it with secure permissions — mode 0600 (owner read/write only) inside a 0700 directory.

Loose permissions are refused

Like OpenSSH refusing a world-readable private key, eocube refuses to read the configuration file if it is group- or other-accessible. If you see such an error, tighten it with chmod 600 ~/.config/eocube/eocube.yml. Keeping the directory secure is your responsibility.

Quick setup

The fastest start writes the built-in EOCube.Ro defaults and then authenticates:

eocube setup init     # default authentication source + storage + STAC catalog
eocube auth login     # store your session in the file

eocube setup init resets the configuration to the ROCS defaults. It prompts before overwriting an existing file (pass --force to skip the prompt).

File format

A configuration produced by eocube setup init looks like this:

authentication:                       # named authentication sources
  eocube.ro:
    type: oidc
    oidc:
      discovery_url: https://aai.eocube.ro/realms/rocs/.well-known/openid-configuration
      # refresh_token / offline_refresh_token are written here by `auth login`

storage:                              # named storage definitions
  rocs-primary-storage-oidc:
    endpoint: https://storage.svc.uvt-01.eocube.ro
    auth:
      type: oidc                      # use the context's OIDC token
      oidc: {}

stac:                                 # named STAC endpoints
  eocube.ro:
    endpoint: https://stac.eocube.ro

mcp:                                  # MCP server defaults (global)
  port: 8002
  host: 127.0.0.1
  stateless: false
  allow-destructive: false

context:                              # contexts tie the sections together
  primary: eocube.ro                  # the default context
  contexts:
    eocube.ro:
      auth: eocube.ro                 # -> authentication.eocube.ro
      stac: eocube.ro                 # -> stac.eocube.ro
      storage:
        providers:                    # storage backends for components (e.g. upload)
          default:
            ref: rocs-primary-storage-oidc
          user_storage:
            ref: rocs-primary-storage-oidc
        schemes:                      # resolve a STAC item's `storage:scheme`
          eocube-uvt-01-s3:
            default: true
            ref: rocs-primary-storage-oidc

authentication

Each entry is a named login source. The oidc type points at an OpenID Connect discovery URL; eocube auth login writes the resulting refresh_token / offline_refresh_token back into the source.

storage

Named object-storage backends — an endpoint plus an auth block. The auth can be oidc (use the context's OIDC token), ref (reuse a named authentication source), or simple (static S3 keys).

stac

Named STAC API endpoints. A stac entry may carry its own auth reference; when omitted, the context's authentication is used.

mcp

Global defaults for eocube mcp serve (host, port, stateless, allow-destructive). This section is not context-dependent.

context

context.primary names the default context. Each context maps an authentication source, a STAC endpoint, and storage. The storage block has two parts, both consumed by features added later:

• providers — named storage backends for components such as upload; the provider named default is used when none is specified.
• schemes — a mapping used to resolve a STAC item's storage:scheme to a backend (the one marked default: true).

Building it by hand

Instead of setup init, you can assemble the configuration with the per-section commands:

eocube setup auth add --name eocube.ro oidc \
  --discovery-url https://aai.eocube.ro/realms/rocs/.well-known/openid-configuration
eocube setup stac add --name eocube.ro --endpoint https://stac.eocube.ro
eocube setup storage add --name rocs-primary \
  --endpoint https://storage.svc.uvt-01.eocube.ro --auth-ref eocube.ro
eocube setup context add --name eocube.ro \
  --auth eocube.ro --storage rocs-primary --stac eocube.ro --primary

--storage sets the context's default upload provider; --user-storage adds a user_storage provider.

Selecting a context

Every command accepts a global --context to choose which context to use; when omitted, context.primary is used:

eocube --context=eocube.ro services geospatialorg get-county-by-name --name Arad

If no context is configured, commands print a clear message inviting you to run eocube setup.

Environment variables

For headless, container, or CI use you can supply credentials and endpoints through environment variables. These take precedence over the configuration file, so notebooks, sidecars, and CI runners work without an eocube.yml:

Variable	Purpose
EOCUBE_ACCESS_TOKEN / ROCS_AAI_ACCESS_TOKEN	An explicit OIDC access token
ROCS_AAI_REFRESH_TOKEN	A refresh token, re-minted to an access token on expiry
EOCUBE_CLIENT_ID + EOCUBE_CLIENT_SECRET	Service-account client credentials
EOCUBE_CLIENT_SCOPE	Optional scopes for the service-account client
STAC_API_ENDPOINT	Override the STAC endpoint
EOCUBE_CONFIG	Path to the configuration file

Upgrading from an older release

Older versions stored tokens in the operating-system keychain. The keychain is no longer used — tokens now live in eocube.yml. After upgrading, run eocube auth login once to re-create your session.