Skip to content
Blissful Infra

Getting Started

blissful-infra is a CLI that gives you a production-grade sandbox on your laptop. In under two minutes you have a running full-stack app, backend, frontend, database, message bus, tracing, metrics, CI/CD, and a web dashboard, wired together and managed as a unit. Experiment freely. Tear it down. Start fresh. It’s all local, isolated, and completely under your control.

Prerequisites

Section titled “Prerequisites”
  • Node.js 18+: the CLI is a Node.js package
  • Docker Desktop: all services run in Docker containers; Desktop must be running before you use any blissful-infra commands
  • 4 GB free RAM recommended (the full stack with monitoring uses ~2–3 GB)

You do not need a cloud account, Kubernetes, or any other tooling pre-installed.

Install

Section titled “Install”
Terminal window
npm install -g @blissful-infra/cli

Verify the installation:

Terminal window
blissful-infra --version

Quick start

Section titled “Quick start”
Terminal window
blissful-infra start my-app

This single command:

  1. Checks Docker is running and pre-flight checks ports
  2. Ensures the shared Jenkins CI server is up (starts it if not)
  3. Scaffolds a my-app/ directory with backend, frontend, and config files
  4. Generates a docker-compose.yaml wiring all services together
  5. Runs docker compose up --build and streams the build output
  6. Registers the project with Jenkins
  7. Opens the frontend (http://localhost:3000) and dashboard (http://localhost:3002) in your browser

Images are pulled on first run and cached, subsequent starts are significantly faster.

What gets created

Section titled “What gets created”
my-app/
├── backend/              # Spring Boot (Kotlin): REST API + Kafka producer/consumer
│   ├── src/              # Application source code
│   ├── build.gradle.kts  # Gradle build file
│   ├── Dockerfile        # Multi-stage build with OpenTelemetry agent
│   └── Jenkinsfile       # CI/CD pipeline definition
├── frontend/             # React + Vite + TypeScript + TailwindCSS
│   ├── src/              # React application source
│   ├── package.json
│   └── Dockerfile        # nginx-based production image
├── loki/                 # Loki + Promtail log aggregation config
├── prometheus/           # Prometheus scrape configuration
├── grafana/              # Pre-provisioned dashboards and datasources
├── nginx.conf            # Reverse proxy: routes /api/ and /ws/ to backend
├── docker-compose.yaml   # All services wired together
└── blissful-infra.yaml   # Project config (backend, frontend, database options)

Choosing a stack at creation time

Section titled “Choosing a stack at creation time”

The defaults are Spring Boot backend + React+Vite frontend + Postgres database. Override any of them:

Terminal window
# Lambda (Python) serverless backend + Postgres
blissful-infra start my-app --backend lambda-python --database postgres


# Spring Boot + Postgres AND Redis (cache layer)
blissful-infra start my-app --database postgres-redis


# No database (API-only or external DB)
blissful-infra start my-app --database none


# With AI/ML data pipeline
blissful-infra start my-app --plugins ai-pipeline


# Skip Prometheus + Grafana (lighter stack)
blissful-infra start my-app --no-monitoring

Available backends

Section titled “Available backends”
Flag valueStack
spring-bootKotlin + Spring Boot 3 + Kafka + WebSockets
lambda-pythonPython serverless function deployed to LocalStack Lambda

Available frontends

Section titled “Available frontends”
Flag valueStack
react-viteReact + Vite + TypeScript + TailwindCSS

Database options

Section titled “Database options”
Flag valueWhat you get
noneNo database service
postgresPostgres 16 + Flyway migrations + JPA entities + repository layer
redisRedis 7 + Spring Cache (@Cacheable / @CacheEvict)
postgres-redisBoth. Postgres for persistence, Redis as a read-through cache layer

Managing your project

Section titled “Managing your project”

Once your project is running, the key commands are:

Terminal window
# View logs for all services
blissful-infra logs


# Stop all containers
blissful-infra down


# Start a stopped project
blissful-infra up


# Development mode: hot reload with file watching
blissful-infra dev


# Open the dashboard
blissful-infra dashboard

down and up are cheap, the stack is fully containerized, so stopping and restarting costs nothing. You can tear down a project mid-experiment and bring it back exactly where it was.

Reproducing environments

Section titled “Reproducing environments”

Every project has a blissful-infra.yaml that captures the full configuration. To reproduce the exact same sandbox on another machine:

Terminal window
git clone git@github.com:your-org/my-app.git
cd my-app && blissful-infra up

This reads blissful-infra.yaml, regenerates docker-compose.yaml, and starts the stack, byte-for-byte identical to what was originally created. Share it with a teammate and they get the same environment, no setup guide required.

Next steps

Section titled “Next steps”