Skip to content

Bootstrap & Runtime

Cells v5 ships with a redesigned runtime manager. The same binary can run a single-node deployment, a multi-node cluster, or a Kubernetes-managed topology — what changes is the bootstrap configuration, not the code.

bootstrap.yaml

Everything Cells needs at startup is declared in a single bootstrap.yaml file:

  • which listeners (host/port pairs) are opened
  • which servers (gRPC, HTTP, generic) are run
  • which services are attached to each server (via name-pattern filters)
  • which brokers, queues, caches, config and storage backends are wired in
  • per-service storage backends and migrations

A typical service filter looks like this:

1
2
services:
  - filter: "{{ .Name }} ~= pydio\\.grpc\\..*"

This binds every pydio.grpc.* service to that server. Cells uses templated filters everywhere, which means you can compose very different deployments from the same binary just by editing this file.

In single-node mode, a default bootstrap.yaml is generated for you on first install. In Kubernetes, the Helm chart renders the bootstrap into a ConfigMap and mounts it into the Cells pods.

URL-scheme plugin system

Inside Cells, every infrastructure component is opened through a uniform plugin API:

1
pkg.OpenPkg(ctx, url)

The scheme of the URL selects the implementation. For example:

Scheme Used for
grpc:// gRPC server / client
http:// HTTP server / client
nats:// NATS JetStream broker and queues
redis:// Distributed cache
mem:// In-memory broker / cache (single-node, dev)
sql:// Generic SQL storage (resolves the underlying driver)
mysql:// MySQL / MariaDB connection
postgres:// PostgreSQL connection (new in v5)
mongodb:// MongoDB document store
vault:// Hashicorp Vault-backed secrets
etcd:// etcd-backed config / registry
file:// Local file storage / file-based PubSub broker

Because each component is initialized from a URL, switching from an embedded backend to a managed cloud service is purely a configuration change — no code changes, no rebuild.

Service naming and filters

Services follow a structured naming convention:

1
pydio.<protocol>.<service>

Examples:

1
2
3
4
pydio.grpc.oauth
pydio.web.oauth
pydio.rest.frontend
pydio.grpc.data.sync

Combined with the filter syntax above, this lets you decide exactly which subset of services runs on each server — for example, you can isolate the gateway HTTP services on one set of nodes and the data services on another.

When to edit it directly

Most installs never need to touch bootstrap.yaml directly:

  • Single-node: the default is generated by cells configure and tweaked via the standard config commands.
  • Kubernetes: the Helm chart renders the file from your values.yaml; override the chart values rather than editing the rendered config.

Edit bootstrap.yaml directly when:

  • you need to split services across servers in unusual ways (e.g. separate listeners for internal vs. public traffic),
  • you're swapping a backend that is not yet exposed as a Helm value or an installer prompt (for example, switching the broker from gRPC to NATS, or pointing the registry at etcd),
  • you're debugging a startup issue and need to inspect what the runtime manager will actually wire up.

Further reading