Docker Compose Quick Start

The fastest and recommended way to deploy PingsNest in production environments with full container isolation.

Zero manual configuration required on boot. Docker Compose automatically provisions TimescaleDB hypertables, Redis cache clusters, and Apache Kafka message buses out of the box.

1. Clone & Launch Container Stack

Execute the following commands in your host terminal to clone the codebase and initialize all containers:

TERMINAL COMMANDS

# Clone official PingsNest repository git clone https://github.com/PingsNest/PingsNest.git cd PingsNest # Start full container stack in background docker compose up -d # Verify container status docker compose ps

2. Included Production Containers

The default docker-compose.yml boots 4 co-located microservice containers:

Container Name	Host Port	Description & Purpose
api-gateway-monitor	3001	Express TypeScript backend API server & WebSocket live log streamer.
timescaledb	5432	PostgreSQL 15 time-series database storing route telemetry & logs.
redis	6379	Redis 7 high-speed metrics cache & real-time pub/sub message bus.
kafka	9092	Apache Kafka distributed streaming log ingestion pipeline.
pingsnest-portfolio	8085	Static Nginx portfolio & enterprise marketing website container.

3. Health Verification & Web Dashboard

Verify container health and access your local dashboard UI:

CURL & URL

# Healthcheck curl endpoint curl -f http://localhost:3001/api/health # Dashboard Access URL http://localhost:3001 # Portfolio Website Access URL http://localhost:8085

4. Standalone Portfolio Docker Build

To build and run only the portfolio/marketing static website as an isolated Nginx container directly from html_folder/:

PORTFOLIO DOCKER COMMANDS

# Build Portfolio Nginx Docker Image from html_folder cd html_folder docker build -t pingsnest-portfolio . # Run Portfolio container on host port 8085 docker run -d -p 8085:8080 --name pingsnest-portfolio pingsnest-portfolio

Bring Your Own Database (Custom Infrastructure)

How to connect PingsNest to an existing PostgreSQL / TimescaleDB cluster, AWS RDS, or external Redis infrastructure.

PingsNest supports any PostgreSQL 14+ database. Installing the timescaledb extension is recommended for automatic 10x timeseries data compression.

1. Prepare Your PostgreSQL / TimescaleDB Database

Log into your existing PostgreSQL instance and create a dedicated database and timeseries extension:

SQL QUERY

-- Connect to PostgreSQL shell CREATE DATABASE pingsnest; \c pingsnest; -- Enable TimescaleDB extension CREATE EXTENSION IF NOT EXISTS timescaledb CASCADE;

2. Update Environment Credentials

Open your root .env file and specify your database and Redis connection URIs:

ENV CONFIGURATION

# Custom PostgreSQL / TimescaleDB Connection String DATABASE_URL="postgresql://db_user:secret_password@your-db-host.rds.amazonaws.com:5432/pingsnest?sslmode=require" # Custom Redis Cluster Connection String REDIS_URL="redis://:redis_password@your-redis-cluster.cache.amazonaws.com:6379" # Backend Web Server Port PORT=3001

Where to Make Configuration Changes

Comprehensive directory map detailing exact codebase files to modify for environment settings, API routes, AWS regions, and UI styling.

Codebase Architecture & File Map

File Path	Purpose & Description	Key Options to Customize
.env	Root environment file for credentials & DB URLs.	`DATABASE_URL`, `REDIS_URL`, `AWS_ACCESS_KEY_ID`
docker-compose.yml	Docker container setup & port mappings.	Port bindings, volume mounts, memory limits
server/index.ts	Backend Express TypeScript REST API & WebSockets.	API routes, WebSocket streaming, subscriber persistence
src/components/Settings.tsx	AWS IAM credentials UI & theme switcher handler.	`nova_app_theme`, Account Profile CRUD logic
src/constants/awsRegions.ts	List of supported AWS regions and endpoints.	AWS region list (`us-east-1`, `ap-south-1`)
html_folder/styles.css	Design system CSS variables & theme tokens.	`--accent-cyan`, `--bg-dark`, `--font-sans`
html_folder/app.js	Portfolio JavaScript event handlers & subtabs.	Navbar toggle, subtab switcher, search filter

Kubernetes (K8s) & Helm Charts COMING SOON

Official Kubernetes manifests, Helm charts, and HPA (Horizontal Pod Autoscaler) policies planned for Q3 2026 release.

The upcoming Helm chart deployment will feature native Prometheus ServiceMonitors, cert-manager TLS ingress, and multi-replica Kafka StatefulSets.

1. Planned Helm Installation Commands

HELM COMMANDS

# Add official PingsNest Helm repository helm repo add pingsnest https://charts.pingsnest.com helm repo update # Install PingsNest telemetry stack in K8s namespace helm install pingsnest pingsnest/pingsnest \ --namespace telemetry \ --create-namespace \ --set global.awsRegion=us-east-1 \ --set replicaCount=3

API Gateway Routes Telemetry

Deep dive into route-level P50, P90, and P99 latency percentiles, error rate tracking, and CloudWatch metrics ingestion.

1. Ingested Gateway Metrics

PingsNest continuously ingests CloudWatch telemetry metrics for both REST APIs and HTTP APIs:

CloudWatch Metric Name	Unit	Description
Latency	Milliseconds (ms)	Total response time from API Gateway receiving request to sending response.
IntegrationLatency	Milliseconds (ms)	Time taken by backend Lambda function or HTTP proxy endpoint to respond.
4XXError / 5XXError	Count	Client-side 4xx errors and server-side 5xx gateway integration failures.

AWS Lambda Fleet Analytics

Fleet-wide inventory of all active Lambda functions, cold start penalty tracking, and 1-click provisioned concurrency controls.

1. Cold Start Penalty Tracking

PingsNest automatically isolates cold start duration from warm execution duration by analyzing CloudWatch `REPORT` log entries:

LOG EVENT SAMPLE

REPORT RequestId: 9a8b1c2d Duration: 48.20 ms Billed Duration: 49 ms Memory Size: 512 MB Max Memory Used: 124 MB Init Duration: 182.40 ms

Synthetic Endpoint & SSL Probes

Multi-region synthetic HTTP/HTTPS availability probes, SSL certificate expiration warnings, and public status portal pages.

AWS IAM Permissions Policy

Minimal read-only IAM JSON policy required to grant PingsNest permission to discover API Gateways and read CloudWatch logs.

IAM POLICY JSON

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:GET", "logs:GetLogEvents", "logs:FilterLogEvents", "lambda:ListFunctions", "lambda:GetFunction", "lambda:PutProvisionedConcurrencyConfig" ], "Resource": "*" } ] }

OpenTelemetry (OTLP) Ingestion & SDKs

Point your OpenTelemetry Collector or application language SDKs directly to PingsNest OTLP receiver endpoints.

1. OpenTelemetry Collector YAML Config

OTEL CONFIG YAML

exporters: otlp/pingsnest: endpoint: "http://localhost:3001" tls: insecure: true service: pipelines: traces: receivers: [otlp] exporters: [otlp/pingsnest] metrics: receivers: [otlp] exporters: [otlp/pingsnest]

2. Language SDK Code Snippets

NODE.JS / TYPESCRIPT

import { NodeSDK } from '@opentelemetry/sdk-node'; import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'; const sdk = new NodeSDK({ traceExporter: new OTLPTraceExporter({ url: 'http://localhost:3001/v1/traces', }), }); sdk.start();

HTTP Method	Endpoint Path	Description
GET	/api/health	Backend server health check and database connectivity status.
POST	/api/subscribe	Newsletter subscription endpoint processing email requests.
GET	/api/subscribers	Retrieve all stored subscriber records from local storage.
WS	/ws/logs	Real-time CloudWatch log streaming WebSocket connection.