blissful-infra service

blissful-infra service manages services inside a client environment. A service is your application (backend, optional frontend, optional plugins like LocalStack) attached to the client’s shared infrastructure (Kafka, Postgres, Jenkins, observability).

A client typically holds one to a handful of related services that share the same infra and Docker network.

Subcommands

Subcommand	Purpose
service add <client> <service>	Scaffold a new service inside a client
service up <client> <service>	Start the service (within the client’s unified Compose project)
service down <client> <service>	Stop and remove the service’s containers
service logs <client> <service>	Tail logs for the service

service add

blissful-infra service add <client> <service> [options]

Scaffolds the service from templates, regenerates the client’s infra Compose to include it via the unified-project pattern (see ADR-0003), and brings the service up.

Options

Flag	Description
-b, --backend <name>	Backend framework. Choices: spring-boot, lambda-python, none. Default: spring-boot.
-f, --frontend <name>	Frontend framework. Choices: react-vite, none. Default: prompted (no default).
-p, --plugins <list>	Comma-separated service-scoped plugins. Choices: ai-pipeline, agent-service, gatling.

localstack/keycloak/clickhouse/mlflow/mage are now client-level

These were per-service plugins originally. They’ve been promoted to client-level infrastructure (ADRs 0008, 0009, 0010). Enable them on client create (interactive checkbox or infrastructure.<name>: true in the client config). They no longer appear in the service add prompt.

You can still pass them as --plugins <name> for a service-scoped instance (backward compat for advanced users who want strong test isolation between services), but the recommended path is client-level.

If a flag is omitted in interactive mode, you’ll be prompted for it. Pass all three flags to skip prompts entirely.

Interactive mode

blissful-infra service add dev app

? Backend framework  (Use arrow keys)
> spring-boot
  lambda-python
  none

? Frontend framework
> react-vite
  none

  Tip: localstack, keycloak, clickhouse, mlflow, mage are now client-level. Enable on `client create`, not here.

? Service-scoped plugins (space to toggle)
> ◯ ai-pipeline
  ◯ agent-service
  ◯ gatling

Non-interactive mode (CI / scripts)

blissful-infra service add dev app \
  --backend spring-boot \
  --frontend react-vite \
  --yes

The --yes flag skips both the framework prompts and the optional-deps prompt, and auto-enables any required infrastructure the service needs (see “Infrastructure dependency check” below).

Infrastructure dependency check

Before scaffolding, service add looks up an infra-deps manifest for the chosen backend, frontend, and plugins, then diffs that against the client’s current infrastructure: config. Two outcomes:

• Required components missing: for example, lambda-python needs localstack at the client level. The CLI prompts to enable it. With --yes, it auto-enables and prints what it did.
• Optional components missing: for example, spring-boot can use localstack for S3 uploads. The CLI shows them as a checkbox prompt and enables only what you select. With --yes, optional components are skipped entirely.

This service needs client-level components that aren't enabled:
  • postgres: JPA persistence + Flyway migrations
? Enable postgres on 'dev' now? (Y/n) y
  ✓ Enabled postgres in dev

This service can use these optional client-level components:
? Enable any now? (Space to toggle, Enter to skip)
> ◯ localstack: S3 file uploads via /api/files endpoint
  ◯ keycloak: JWT auth on protected routes

Toggling a flag only updates blissful-infra.yaml, run blissful-infra client up <client> to regenerate the Compose file and start the new container(s).

You can also enable / disable infra components on demand later with blissful-infra client infra add and client infra remove.

Per-service host ports

Each service in a client gets a deterministic port block, allocated from 13000 + (clientBlockIndex × 100) + (serviceIndex × 4). For the first service of the first client (block 0):

Container	Host port
<client>-<service>-backend	13000
<client>-<service>-frontend	13001
<client>-<service>-localstack (if plugin enabled)	13002

The CLI prints the URLs after a successful service add.

service up

blissful-infra service up <client> <service>

Starts only the named service’s containers within the client’s unified Compose project. Useful when a single service has crashed or you want to restart just one component without affecting the rest.

service down

blissful-infra service down <client> <service>

Stops and removes the service’s containers (backend, frontend, localstack if any). Other services in the client and the client’s infra continue running. The service config and source files stay on disk, you can re-up with service up.

service logs

blissful-infra service logs <client> <service>

Tails the last 100 log lines from all of the service’s containers and follows new output. Ctrl+C exits.

Container naming

Services prefix their container names with <client>-<service>- so multiple services in the same client (or across clients) never collide:

dev-app-backend
dev-app-frontend
dev-app-localstack
acme-payment-backend
acme-payment-frontend

This naming is what service logs and service up/down filter on.

Where things live

Resource	Location
Service directory	~/.blissful-infra/clients/<client>/<service>/
Service config	~/.blissful-infra/clients/<client>/<service>/blissful-infra.yaml
Service Compose (included by parent)	~/.blissful-infra/clients/<client>/<service>/docker-compose.yaml
Backend source	~/.blissful-infra/clients/<client>/<service>/backend/
Frontend source	~/.blissful-infra/clients/<client>/<service>/frontend/