Deployment Configurations

Deployment Configurations

SERP supports four single-transport deployment modes plus a mixed-transport mode. All 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 POSIX (Portable, No Deps)

Services are split into separate processes communicating over POSIX Unix Domain Sockets. Requires no external libraries.

deployment:
  name: multiprocess_posix
  mode: multiprocess
  ipc: posix

How it works:

• serpgen generates POSIX UDS adapter and proxy classes for every interface that crosses a process boundary.
• Each process binds a socket at /tmp/serp-<ComponentName>.sock (overridable via env).
• No external libraries required — POSIX sockets are part of any POSIX-compliant OS.

Characteristics:

Property	Value
Transport	POSIX Unix Domain Sockets
Platform	macOS and Linux
Runtime dependency	None
Process isolation	Full
Supervisor	script (macOS), systemd (Linux)

Use for:

• macOS development — zero external dependencies unlike gRPC
• CI/CD without gRPC or DBus setup
• Lightweight embedded Linux without gRPC overhead

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

Mixed Transport

A single deployment can mix transport backends — different service connections can use different IPC. Transport is selected per-connection via SUML arrow labels; the ipc: field in the .sidl is the fallback for unlabelled arrows.

@startuml multiprocess_mixed
package client_app {
  component ClientService <<generated_service>>
}
package hal_app {
  component HalService <<generated_service>>
}
package cloud_app {
  component CloudService <<generated_service>>
}
ClientService --> HalService : posix
ClientService --> CloudService : grpc
@enduml

# multiprocess_mixed.sidl
deployment:
  mode: multiprocess
  ipc: posix    # fallback for any unlabelled arrows

The generator resolves each connection independently and produces the correct adapter/proxy namespace per connection. See Transports for full details.

Choosing a Deployment Mode

Scenario	Recommended mode
First iteration / getting started	Monolith
macOS multiprocess, zero deps	Multiprocess POSIX
macOS multiprocess, gRPC features needed	Multiprocess gRPC
Production embedded Linux	Multiprocess DBus
AAOS (Linux device)	Multiprocess DBus
AAOS (emulator, no deps)	Multiprocess POSIX
Different IPC needs per connection	Mixed transport
Cross-platform or macOS CI	Multiprocess POSIX 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.

AAOS VHAL Integration

SERP can generate a complete AAOS VHAL from a SerpIDL workspace. The generated VehicleHardwareAdapter translates SERP property change events into AIDL onPropertyEvent calls consumed by CarService. The VHAL binary registers as android.hardware.automotive.vehicle and runs as a native service on the Android device or emulator.

The aaos_posix deployment (POSIX transport) is preferred for emulator development — it has no gRPC or DBus dependency and links statically. The aaos_grpc deployment can be used when gRPC is available.

See serp-vhal for a working example.

---

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/
• serp-vhal — AAOS VHAL example project