Deployment Configurations

Deployment Configurations

SERP supports three standard deployment modes. All three use the same service implementations — switching modes is purely a spec change, no service code needs to be modified.

Monolith (Inprocess)

All services run in a single process and communicate via direct shared_ptr calls. There is no IPC layer.

deployment:
  name: monolith
  mode: monolith
  transport: inprocess

How it works:

• The generated main.cpp instantiates every service and wires them directly — no serialization, no sockets, no bus.
• A service calling another service's method is a normal C++ function call on a shared_ptr.
• The EventLoop still drives all services on their respective threads, so thread safety rules still apply.

Characteristics:

Property	Value
Latency	Minimal — direct function call
IPC overhead	None
Process isolation	None — a crash in any service takes down the whole process
Debuggability	Easiest — single process, single core dump
Platform	Any

Use for:

• Initial development and prototyping
• Single-board targets with no process isolation requirement
• CI — fast to build, no system dbus required
• Unit and integration tests

Multiprocess DBus (Linux)

Services are split into separate processes communicating over DBus.

deployment:
  name: multiprocess_dbus
  mode: multiprocess
  transport: dbus

How it works:

• serpgen generates adapter classes (server-side DBus skeleton) and proxy classes (client-side DBus stub) for every interface that crosses a process boundary.
• Each process has its own main.cpp that registers its services on the bus and connects proxies to services in other processes.
• The systemd lifecycle plugin generates .service unit files for each process.

Characteristics:

Property	Value
Transport	DBus (sdbus-c++)
Platform	Linux only
Runtime dependency	libsdbus-c++, dbus daemon
Process isolation	Full — processes are independent OS processes
Supervisor	systemd (or init.d)

Use for:

• Linux embedded targets (automotive, industrial)
• AAOS — DBus is idiomatic on Android Automotive
• Production Linux where process isolation and restart-on-failure are required

Multiprocess gRPC (Portable)

Services are split into separate processes communicating over gRPC.

deployment:
  name: multiprocess_grpc
  mode: multiprocess
  transport: grpc

How it works:

• serpgen generates gRPC stubs and skeletons from the SerpIDL interface definitions.
• Each process binds to a configured port. Processes in other processes connect to that port via generated client stubs.
• Process ports are configured per process in the deployment spec under grpc_port.

processes:
  car_service_app:
    domain: service
    services:
      - ClimateManager
    grpc_port: 50052

Characteristics:

Property	Value
Transport	gRPC (HTTP/2 + Protocol Buffers)
Platform	macOS and Linux
Runtime dependency	gRPC libraries
Process isolation	Full
Supervisor	script (macOS), systemd (Linux)

Use for:

• macOS development of multiprocess systems — DBus is not available on macOS, gRPC is
• Cross-platform portability (same service code runs on macOS and Linux)
• Systems that integrate with external gRPC services

Choosing a Deployment Mode

Scenario	Recommended mode
First iteration / getting started	Monolith
Local development of a multiprocess Linux system	Multiprocess gRPC (macOS) or Monolith
Production embedded Linux	Multiprocess DBus
AAOS	Multiprocess DBus
Cross-platform or macOS CI	Multiprocess gRPC or Monolith

Switching Between Modes

Because the same service implementations are used by all deployments, switching is a matter of pointing serpgen at a different deployment spec and rebuilding:

# Generate monolith deployment
serpgen generate-deployments -w specs/serp.sidl -d monolith

# Generate gRPC multiprocess deployment
serpgen generate-deployments -w specs/serp.sidl -d multiprocess_grpc

Service code in src/ does not change. Only gen/deployments/ is affected.

Related Pages

• Deployment Specs — full deployment spec syntax
• Lifecycle Backends — systemd, init.d, Android Init
• CMake Integration — linking the right transport target
• Generated Code Layout — per-deployment directory structure in gen/