Services Module

Development services orchestration for devenv.

Overview

This module provides project-local database and infrastructure services with lifecycle management. Services use deterministic ports based on project name and expose environment variables for easy connectivity.

Directory Structure

services/
├── default.nix           # Module aggregator - imports all service modules
├── global-services.nix   # Maps globalServices to stackpanel.services
├── postgres/
│   └── default.nix       # PostgreSQL service implementation
├── redis/
│   └── default.nix       # Redis service implementation
├── minio/
│   └── default.nix       # MinIO S3 service implementation
├── caddy/
│   └── default.nix       # Caddy reverse proxy scripts and utilities
├── caddy.nix             # Caddy devenv module (uses caddy/)
├── aws.nix               # AWS Roles Anywhere certificate authentication
├── binary-cache.nix      # Nix binary cache configuration
└── security-healthchecks.nix  # Security health checks

Supported Services

PostgreSQL

Database service with automatic database creation.

stackpanel.globalServices.postgres = {
  enable = true;
  databases = ["myapp" "myapp_test"];
};

Environment: DATABASE_URL, PGHOST, PGPORT, PGUSER, POSTGRES_URL

Location: services/postgres/default.nix

Redis

Key-value store for caching and queues.

stackpanel.globalServices.redis.enable = true;

Environment: REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_SOCKET

Location: services/redis/default.nix

MinIO

S3-compatible object storage.

stackpanel.globalServices.minio.enable = true;

Environment: MINIO_ENDPOINT, S3_ENDPOINT, MINIO_ROOT_USER, MINIO_ROOT_PASSWORD

Location: services/minio/default.nix

Caddy

Reverse proxy with virtual hosts and optional TLS.

stackpanel.caddy = {
  enable = true;
  project-name = "myapp";
  use-step-tls = true;
};

Commands: caddy-start, caddy-stop, caddy-add-site, caddy-list-sites

Location: services/caddy/default.nix (library), services/caddy.nix (module)

Adding a New Service

Create a new directory: services/<service-name>/
Create services/<service-name>/default.nix with the service implementation
Export a mkService function following the pattern in existing services
Add the service to core/services/services.nix registry
Optionally add a devenv module in services/<service-name>.nix

Service Implementation Pattern

Each service implementation should export:

{
  pkgs,
  lib,
  baseDir,  # Base directory for service data (e.g., ".stackpanel/state/services")
}:
{
  # Required packages
  packages = [ ... ];

  # Factory function to create service instances
  mkService = { projectName, port ? defaultPort, ... }:
    {
      # Environment variables
      env = { ... };

      # Packages needed by CLI
      allPackages = [ ... ];

      # Shell hook for env setup
      shellHook = ''...'';

      # Foreground start script for process-compose
      startScript = pkgs.writeShellScriptBin "service-start" ''...'';

      # Service-specific paths
      dataDir = "...";
      port = ...;
    };
}

AWS Certificate Authentication

Passwordless AWS access using Step CA device certificates.

stackpanel.aws.roles-anywhere = {
  enable = true;
  account-id = "123456789";
  role-name = "developer";
  trust-anchor-arn = "arn:aws:rolesanywhere:...";
  profile-arn = "arn:aws:rolesanywhere:...";
};

Commands: check-aws-cert, aws-creds-env

Service Lifecycle

All services are managed via the stackpanel CLI:

stackpanel services start    # Start all enabled services
stackpanel services stop     # Stop all services
stackpanel services status   # Check service status

Services run under process-compose and are configured with:

Automatic restart on failure
Readiness probes for health checking
Proper shutdown handling

Architecture

User Config (stackpanel.globalServices)
    ↓
services/global-services.nix (maps to stackpanel.services)
    ↓
core/services/services.nix (service registry/factory)
    ↓
services/{postgres,redis,minio}/default.nix (implementations)
    ↓
process-compose (lifecycle management)

Services Module

On this page