@deeep-network/riptide

Self-contained container orchestration library with lifecycle hooks for Coral Reef services.

Prerequisites

• Docker for building and running services
• Node.js 22+ and pnpm

Quick Start

Create a New Service

npx @deeep-network/riptide init my-service
cd my-service

This creates a new my-service directory with all the necessary files:

• package.json - Dependencies and build scripts
• src/hooks.ts - Service lifecycle hooks
• Dockerfile - Multi-stage container build
• riptide.config.json - Service configuration
• tsconfig.json and tsup.config.ts - TypeScript configuration

Template Options

# Create with API key validation
npx @deeep-network/riptide init my-api --template with-secrets

# Create with subprocess management  
npx @deeep-network/riptide init my-worker --template with-process

# Create with Prometheus metrics
npx @deeep-network/riptide init my-monitored --template with-metrics

Build and Run

# Install dependencies
pnpm install

# Build the service
pnpm run build

# Build Docker image
pnpm run build:docker

# Run the service
docker run -e MY_SECRETS=your-secrets reef-my-service

Templates

• basic - Simple healthy service with minimal hooks
• with-secrets - Includes API key validation and error handling
• with-process - Manages subprocess lifecycle
• with-metrics - Includes Prometheus metrics endpoint

Architecture

Riptide uses a secure 3-layer Docker architecture:

1. Builder Layer - Compiles TypeScript and installs dependencies
2. Third-party Base - Your service-specific dependencies and setup
3. Riptide Runtime - Secure container runtime injected from quay.io/nerdnode/riptide:latest

Services run as the riptide user (UID 1005) in the /riptide directory with controlled system access.

CLI Commands

# Initialize a new service (creates a new directory)
npx @deeep-network/riptide init <name> [--template TYPE]

# Start a service
npx @deeep-network/riptide start [--config PATH] [--hooks PATH]

# Validate configuration and hooks
npx @deeep-network/riptide validate [--config PATH] [--hooks PATH]

# Check service health
npx @deeep-network/riptide health

# Show service status
npx @deeep-network/riptide status

Development

# For local development
git clone <your-service-repo>
cd <your-service>
pnpm install
pnpm run build
pnpm run validate

# For Docker development
pnpm run build:docker
docker run --rm -it reef-<service-name>

License

MIT