🚀 DevOps Infrastructure Stack with VPN Security

A comprehensive Docker Compose-based infrastructure stack for modern DevOps operations, featuring WireGuard VPN security, observability, monitoring, CI/CD, and service discovery capabilities.

📋 Table of Contents

🏗️ Architecture Overview
Security Layer
Core Infrastructure
Observability Stack
CI/CD & Development
Identity & Security
🔐 VPN Security Model
Public Services
Private Services
VPN Management
Security Benefits
🖥️ Server Specifications
Minimum Requirements
Recommended Specifications
🌐 Service Access Matrix
Public Services
Private Services
VPN Infrastructure
Blocked Ports
🔍 Observability Stack
🛠️ Development Tools
Monitoring & Alerting
🚀 Quick Start
� Configuration Files
🔧 Advanced Configuration
🐛 Troubleshooting
📖 Documentation
🎉 Getting Started Checklist
🤝 Contributing
📄 License
🔄 Maintenance & Updates
📦 Default Credentials
🧪 Local Development

📚 Documentation Directory

🏗️ Architecture Overview

This infrastructure stack provides a complete DevOps platform with enterprise-grade security:

🔐 Security Layer (NEW)

VPN Server: WireGuard for secure remote access
VPN Management: WG-Easy web interface for client management
DNS Security: Pi-hole for internal DNS and ad-blocking
Access Control: IP-based filtering and port blocking
Firewall: Automated iptables rules for network security

Core Infrastructure

Reverse Proxy: Traefik with automatic SSL certificates and VPN integration
Service Discovery: Consul for service registration and discovery
Secret Management: Vault for secure secret storage
Message Queue: RabbitMQ for asynchronous communication
Cache: Redis for session storage and caching
Database: PostgreSQL with pgAdmin interface

Observability Stack (OpenSearch-based)

Search & Analytics: OpenSearch with OpenSearch Dashboards
Distributed Tracing: Jaeger with OpenSearch backend (with sensitive data filtering)
Telemetry Collection: OpenTelemetry Collector (with privacy controls)
Log Processing: Fluent Bit for advanced log processing
Metrics & Monitoring: Prometheus + Grafana
Log Aggregation: Loki + Promtail

CI/CD & Development

CI/CD Pipeline: Jenkins with persistent storage
Artifact Management: Nexus repository manager
Asset Serving: Nginx for static file serving
Uptime Monitoring: Uptime Kuma for service health

Identity & Security

Identity Management: Keycloak for authentication and authorization
Secret Storage: Vault with Consul backend
SSL/TLS: Automatic Let's Encrypt certificates via Traefik
Network Security: VPN-only access for administrative services

🔐 VPN Security Model

This infrastructure implements a zero-trust security model where:

Public Services (Internet Accessible)

📊 Status Page: status.olanna.ai (Uptime Kuma)
🗂️ Assets: assets.olanna.ai (Static files)
🔧 VPN Admin: vpn-admin.olanna.ai (WG-Easy - with authentication)

Private Services (VPN Required)

🔐 Authentication: auth.olanna.ai (Keycloak)
📈 Monitoring: monitoring.olanna.ai (Grafana)
🔍 Search: search.olanna.ai (OpenSearch Dashboards)
🔗 Tracing: tracing.olanna.ai (Jaeger)
⚙️ CI/CD: jenkins.olanna.ai (Jenkins)
🗄️ Database: database.olanna.ai (pgAdmin)
🏛️ Service Discovery: consul.olanna.ai (Consul)
🔐 Secrets: vault.olanna.ai (Vault)
📦 Artifacts: nexus.olanna.ai (Nexus)
🚦 Proxy Admin: traefik.olanna.ai (Traefik Dashboard)
📨 Message Queue: rabbitmq.olanna.ai (RabbitMQ)
🌐 DNS Admin: dns.olanna.ai (Pi-hole)
📡 Telemetry: telemetry.olanna.ai (OpenTelemetry)

VPN Management (Admin Access)

🔧 VPN Admin: vpn-admin.olanna.ai (WG-Easy - with authentication)

Security Benefits

✅ Zero direct port exposure for administrative services
✅ Encrypted VPN tunnel for all private access
✅ IP-based access control at multiple layers
✅ Automatic firewall management
✅ Internal DNS resolution with ad-blocking
✅ Sensitive data filtering in traces and logs
SSL/TLS: Automatic Let's Encrypt certificates via Traefik

🖥️ Server Specifications

Minimum Requirements

🟠 OS: Ubuntu 24.10 x64 (or compatible Linux distribution)
⚙️ vCPUs: 4 cores (minimum 2)
🧠 RAM: 16GB (minimum 8GB)
💾 Disk: 100GB SSD (minimum 60GB)
🌐 Network: Public IP with domain access
🔐 VPN: WireGuard kernel module support

Recommended Specifications

⚙️ vCPUs: 8 cores
🧠 RAM: 32GB
💾 Disk: 200GB NVMe SSD
🌐 Network: 1Gbps connection

🌐 Service Access Matrix

🌍 Public Services (Internet Access)

Service	Domain	Port	Purpose	Security
Uptime Kuma	`status.olanna.ai`	3001	Public status page	Read-only status
Assets Server	`assets.olanna.ai`	15010	Static file serving	Read-only content

🔒 Private Services (VPN Required)

Service	Domain	Port	Purpose	VPN Required
Grafana	`monitoring.olanna.ai`	3000	Monitoring dashboards	✅
OpenSearch	`search.olanna.ai`	5601	Log & data search	✅
Jaeger	`tracing.olanna.ai`	16686	Distributed tracing	✅
Jenkins	`jenkins.olanna.ai`	8090	CI/CD pipeline	✅
pgAdmin	`database.olanna.ai`	5050	Database management	✅
Consul	`consul.olanna.ai`	8500	Service discovery	✅
Vault	`vault.olanna.ai`	8200	Secret management	✅
Nexus	`nexus.olanna.ai`	8081	Artifact repository	✅
Traefik	`traefik.olanna.ai`	8080	Proxy dashboard	✅
RabbitMQ	`rabbitmq.olanna.ai`	15672	Message queue UI	✅
OpenTelemetry	`telemetry.olanna.ai`	8889	Telemetry metrics	✅
Keycloak	`auth.olanna.ai`	8091	Authentication & SSO	✅

🔧 VPN Infrastructure (VPN Management)

Service	Domain	Port	Purpose	Access
WG-Easy	`vpn-admin.olanna.ai`	51821	VPN client management	Basic auth + admin only
Pi-hole	`dns.olanna.ai`	8053	DNS management	✅ VPN Required

🚫 Blocked Ports (Internal Only)

Service	Port	Access	Purpose
PostgreSQL	5432	Docker network only	Database
Redis	6379	Docker network only	Cache
OpenSearch API	9200	Docker network only	Search engine
Loki	3100	Docker network only	Log aggregation
Prometheus	9090	Docker network only	Metrics collection
WireGuard	51820	Public (UDP only)	VPN tunnel

🔍 Observability Stack

OpenSearch Cluster

Image: opensearchproject/opensearch:2.11.1
Features:
Single-node cluster for development
Performance analyzer enabled
Index lifecycle management
Custom index templates
Memory-optimized configuration

OpenSearch Dashboards

Image: opensearchproject/opensearch-dashboards:2.11.1
Features:
Kibana-compatible interface
Visualizations and dashboards
Index pattern management
Data exploration tools

Jaeger Distributed Tracing

Image: jaegertracing/all-in-one:latest
Backend: OpenSearch for span storage
Features:
Service dependency graphs
Trace timeline visualization
Performance analytics
Error tracking

OpenTelemetry Collector

Image: otel/opentelemetry-collector-contrib:latest
Purpose: Unified telemetry collection
Supported Protocols:
OTLP (gRPC/HTTP)
Jaeger
Prometheus
Exporters: OpenSearch, Prometheus, Logging

Fluent Bit Log Processing

Image: fluent/fluent-bit:latest
Features:
Container log collection
Host system log monitoring
Advanced parsing and filtering
Direct OpenSearch integration

🛠️ Development Tools

Jenkins CI/CD

Image: jenkins/jenkins
Features:
Persistent job storage
Docker socket access
Configuration as Code support
Automated SSL termination

Nexus Repository Manager

Image: sonatype/nexus3:latest
Repositories:
Docker registry (ports 5000/5001)
Gradle/Maven/NPM repositories
Raw asset storage
Storage: Persistent volumes

Git Integration

Webhook support for automated builds
Multi-branch pipeline support
Docker-in-Docker capabilities

🔒 Security & Secrets

Vault Secret Management

Image: hashicorp/vault:1.15
Backend: Consul storage
Features:
Dynamic secret generation
Secret rotation
Audit logging
Policy-based access control

Keycloak Identity Management

Image: quay.io/keycloak/keycloak:22.0
Database: PostgreSQL backend
Features:
Single Sign-On (SSO)
Identity federation
User management
Role-based access control

SSL/TLS Certificates

Provider: Let's Encrypt via Traefik
Features:
Automatic certificate generation
Certificate renewal
SNI support
HTTP to HTTPS redirection

📊 Monitoring & Alerting

Prometheus Metrics

Image: prom/prometheus:latest
Retention: 15 days, 3GB storage
Targets:
System metrics
Application metrics
Container metrics

Grafana Dashboards

Image: grafana/grafana:latest
Data Sources:
Prometheus (metrics)
Loki (logs)
OpenSearch (traces)

Uptime Kuma

Image: louislam/uptime-kuma:latest
Features:
HTTP/HTTPS monitoring
SSL certificate monitoring
Multi-notification channels
Status page generation

🚀 Quick Start

Option A: VPN-Secured Setup (Recommended)

1. Prerequisites

# Install Docker & Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.21.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Install WireGuard tools
sudo apt update && sudo apt install -y wireguard-tools

2. VPN Infrastructure Setup

# Clone repository
git clone https://github.com/Olanna-tech/devops-scripts.git
cd devops-scripts

# Run automated VPN setup
./scripts/quick-vpn-setup.sh

# Apply firewall rules (IMPORTANT for security)
sudo ./firewall-rules.sh

3. Domain Configuration

Update your DNS records to point to your server IP:

# VPN & Admin domains
vpn.olanna.ai              A    YOUR_SERVER_IP
vpn-admin.olanna.ai        A    YOUR_SERVER_IP

# Public services
status.olanna.ai           A    YOUR_SERVER_IP
assets.olanna.ai           A    YOUR_SERVER_IP

# Private services (VPN required)
auth.olanna.ai             A    YOUR_SERVER_IP
monitoring.olanna.ai       A    YOUR_SERVER_IP
search.olanna.ai           A    YOUR_SERVER_IP
tracing.olanna.ai          A    YOUR_SERVER_IP
jenkins.olanna.ai          A    YOUR_SERVER_IP
database.olanna.ai         A    YOUR_SERVER_IP
consul.olanna.ai           A    YOUR_SERVER_IP
vault.olanna.ai            A    YOUR_SERVER_IP
nexus.olanna.ai            A    YOUR_SERVER_IP
traefik.olanna.ai          A    YOUR_SERVER_IP
rabbitmq.olanna.ai         A    YOUR_SERVER_IP
dns.olanna.ai              A    YOUR_SERVER_IP
telemetry.olanna.ai        A    YOUR_SERVER_IP

4. Start Main Services

# Start VPN infrastructure first
docker-compose -f docker-compose-vpn.yml up -d

# Start main application stack
docker-compose up -d

# Check service status
docker-compose ps

5. Create VPN Clients

# Option 1: Web interface (recommended)
# Open https://vpn-admin.olanna.ai
# Login: admin / secureWgPassword123!
# Click "Add Client" and download configuration

# Option 2: Command line
./scripts/manage-access.sh generate-client "my-laptop"

6. Test Access

# Without VPN - should work:
curl -I https://status.olanna.ai

# Without VPN - should be blocked (403 Forbidden):
curl -I https://monitoring.olanna.ai
curl -I https://auth.olanna.ai

# Connect VPN and test private services:
./scripts/manage-access.sh test-vpn

Option B: Local Development Setup

1. Network Setup

# Create external network
docker network create olanna-network

2. Start Local Services

# Clone repository
git clone https://github.com/Olanna-tech/devops-scripts.git
cd devops-scripts

# Start with local configuration
docker-compose -f docker-compose-local.yml up -d

# Check service status
docker-compose ps

3. Initialize OpenSearch

# Wait for OpenSearch to be ready
until curl -f http://localhost:9200/_cluster/health; do sleep 5; done

# Setup index templates
./opensearch/setup-indices.sh

4. Access Services Locally

All services available on localhost:PORT - see Service Access Matrix for ports.

Primary Dashboard: http://localhost:5601
Monitoring: http://localhost:3000
Tracing: http://localhost:16686

� VPN Setup & Management

📱 VPN Client Setup

Desktop (Windows/Mac/Linux)

Download WireGuard client: https://www.wireguard.com/install/
Open VPN admin interface: https://vpn-admin.olanna.ai
Login: admin / secureWgPassword123!
Click "Add Client" → Download config
Import config into WireGuard client

Mobile (iOS/Android)

Install WireGuard app from app store
Open VPN admin interface on phone: https://vpn-admin.olanna.ai
Login and scan QR code for new client
Connect and test access

Command Line (Linux)

# Install WireGuard
sudo apt install wireguard

# Get config from web interface and save as wg0.conf
sudo cp downloaded-config.conf /etc/wireguard/wg0.conf

# Start VPN
sudo wg-quick up wg0

# Check status
sudo wg show

# Stop VPN
sudo wg-quick down wg0

🛠️ Access Management Commands

# Show current configuration
./scripts/manage-access.sh show-config

# Add new VPN-only service
./scripts/manage-access.sh add-vpn-service myapp.olanna.ai myapp 8080

# Add new public service (⚠️ use carefully)
./scripts/manage-access.sh add-public-service api.olanna.ai myapi 3000

# Block additional ports from public access
./scripts/manage-access.sh block-port 3306
./scripts/manage-access.sh update-firewall
sudo ./firewall-rules.sh

# Test VPN connectivity
./scripts/manage-access.sh test-vpn

# Generate client config template
./scripts/manage-access.sh generate-client "john-laptop"

🔒 Security Management

Change Default Passwords

# Update VPN admin password in docker-compose-vpn.yml
WG_EASY_PASSWORD: "YOUR_STRONG_PASSWORD"

# Update Pi-hole admin password
PIHOLE_PASSWORD: "YOUR_STRONG_PASSWORD"

# Restart services
docker-compose -f docker-compose-vpn.yml up -d

Monitor VPN Connections

# Check active VPN connections
docker exec wg-easy wg show

# Monitor access logs
docker logs traefik | grep "monitoring.olanna.ai"

# Check firewall status
sudo iptables -L -n

Emergency Access

If locked out, temporarily allow your IP:

# Get your public IP
MY_IP=$(curl -s ifconfig.me)

# Temporarily allow access (use carefully!)
sudo iptables -I INPUT -s $MY_IP/32 -j ACCEPT

# Remove rule after fixing issue
sudo iptables -D INPUT -s $MY_IP/32 -j ACCEPT

📊 Network Layout

Internet (Public)
    ↓
[Firewall Rules] ← Only ports 22, 80, 443, 51820 allowed
    ↓
[Traefik Reverse Proxy] ← Domain routing + IP filtering
    ↓
┌─ Public Services (Any IP)
│   ├─ auth.olanna.ai (Keycloak)
│   ├─ status.olanna.ai (Uptime Kuma)
│   ├─ assets.olanna.ai (Static files)
│   └─ vpn-admin.olanna.ai (VPN management)
│
└─ Private Services (VPN Required: 10.8.0.0/24)
    ├─ monitoring.olanna.ai (Grafana)
    ├─ search.olanna.ai (OpenSearch)
    ├─ jenkins.olanna.ai (Jenkins)
    ├─ vault.olanna.ai (Vault)
    └─ ... (all other administrative services)

Networks:
- VPN Subnet: 10.8.0.0/24
- Docker Network: 172.18.0.0/16
- Pi-hole DNS: 172.18.0.10

�📁 Configuration Files

Core Configuration

├── docker-compose.yml              # Production configuration
├── docker-compose-local.yml        # Local development
├── traefik.yml                     # Traefik configuration
├── letsencrypt/                    # SSL certificates
│   └── acme.json

OpenSearch Configuration

├── opensearch/
│   ├── config/
│   │   └── opensearch.yml          # OpenSearch settings
│   └── setup-indices.sh            # Index template setup
├── otel-collector-config.yaml      # OpenTelemetry configuration
├── fluent-bit.conf                 # Log processing rules

Service Configuration

├── prometheus.yml                  # Metrics collection
├── loki-config.yml                # Log aggregation
├── promtail-config.yml            # Log shipping
├── rabbitmq.conf                  # Message queue settings

Security Configuration

├── consul/
│   └── config/
│       ├── consul.hcl             # Service discovery
│       ├── acl.hcl                # Access control
│       └── telemetry.hcl          # Monitoring
├── vault/
│   ├── config/
│   │   └── vault.hcl              # Secret storage
│   └── policies/                  # Access policies

🔧 Advanced Configuration

OpenSearch Performance Tuning

# opensearch/config/opensearch.yml
indices.memory.index_buffer_size: 20%
indices.fielddata.cache.size: 40%
indices.queries.cache.size: 20%
thread_pool.write.queue_size: 1000

OpenTelemetry Pipeline Configuration

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  opensearch:
    http:
      endpoint: "http://opensearch:9200"
    logs_index: "otel-logs"
    traces_index: "otel-traces"

Custom Index Templates

# Application logs template
curl -X PUT "http://localhost:9200/_index_template/application-logs" \
  -H 'Content-Type: application/json' \
  -d @templates/app-logs-template.json

# Trace data template
curl -X PUT "http://localhost:9200/_index_template/jaeger-traces" \
  -H 'Content-Type: application/json' \
  -d @templates/traces-template.json

Grafana Dashboard Import

# Import predefined dashboards
docker exec grafana grafana-cli plugins install grafana-opensearch-datasource
docker exec grafana grafana-cli admin reset-admin-password admin

🐛 Troubleshooting

Common Issues

1. OpenSearch Memory Issues

# Check memory usage
docker stats opensearch

# Adjust JVM heap size
OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g

2. SSL Certificate Problems

# Check Traefik logs
docker logs traefik

# Verify domain resolution
nslookup localhost

# Check Let's Encrypt rate limits
# https://letsencrypt.org/docs/rate-limits/

3. Service Discovery Issues

# Check Consul cluster
curl http://localhost:8500/v1/status/leader

# Verify service registration
curl http://localhost:8500/v1/catalog/services

4. Database Connection Problems

# Test PostgreSQL connection
docker exec postgres pg_isready -U admin

# Check database logs
docker logs postgres

Performance Optimization

System Limits

# Increase file descriptor limits
echo "* soft nofile 65536" >> /etc/security/limits.conf
echo "* hard nofile 65536" >> /etc/security/limits.conf

# Increase vm.max_map_count for OpenSearch
echo "vm.max_map_count=262144" >> /etc/sysctl.conf
sysctl -p

Docker Optimization

# Enable Docker logging driver optimization
echo '{"log-driver": "json-file", "log-opts": {"max-size": "10m", "max-file": "3"}}' > /etc/docker/daemon.json
systemctl restart docker

📖 Documentation

📚 Complete Documentation Set

Document	Purpose	Audience
README.md	Main overview and setup guide	All users
VPN_SETUP_GUIDE.md	Detailed VPN infrastructure setup	DevOps engineers
VPN_ACCESS_GUIDE.md	Quick VPN access instructions	End users
QUICK_REFERENCE.md	Common commands and troubleshooting	Operators
SECURITY.md	Security configuration and best practices	Security team
OPENSEARCH_FEATURES.md	OpenSearch specific features	Data engineers

🛠️ Management Scripts

Script	Purpose	Usage
scripts/quick-vpn-setup.sh	Automated VPN infrastructure setup	`./scripts/quick-vpn-setup.sh`
scripts/manage-access.sh	Service access control management	`./scripts/manage-access.sh help`
scripts/setup-vpn.sh	Detailed VPN configuration	`./scripts/setup-vpn.sh`
scripts/configure-tracing.sh	Tracing with sensitive data protection	`./scripts/configure-tracing.sh local`

📝 Configuration Files

File	Purpose	Documentation
docker-compose.yml	Production stack with VPN security	Service Access Matrix
docker-compose-local.yml	Local development stack	Local Setup
docker-compose-vpn.yml	VPN infrastructure services	VPN Setup Guide
traefik-vpn.yml	Traefik with VPN integration	VPN Setup Guide
traefik-dynamic.yml	Access control middleware	Access Control
access-control.yml	Service categorization	VPN Access Guide

🔗 API Documentation

OpenSearch API Examples (VPN Required)

# Health check (via VPN)
curl "https://search.olanna.ai/_cluster/health"

# Search all indices
curl "https://search.olanna.ai/_search?q=*" \
  -H 'Authorization: Bearer YOUR_TOKEN'

# Search application logs
curl "https://search.olanna.ai/app-logs-*/_search" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "bool": {
        "must": [
          {"term": {"level": "ERROR"}},
          {"range": {"@timestamp": {"gte": "now-1h"}}}
        ]
      }
    }
  }'

Jaeger API Examples (VPN Required)

# Get services
curl "https://tracing.olanna.ai/api/services"

# Search traces (sensitive data filtered)
curl "https://tracing.olanna.ai/api/traces?service=my-service&limit=20"

# Get trace by ID
curl "https://tracing.olanna.ai/api/traces/{trace-id}"

Grafana API Examples (VPN Required)

# Get dashboards
curl "https://monitoring.olanna.ai/api/search" \
  -H 'Authorization: Bearer YOUR_GRAFANA_TOKEN'

# Query metrics
curl "https://monitoring.olanna.ai/api/datasources/proxy/1/api/v1/query" \
  -H 'Authorization: Bearer YOUR_GRAFANA_TOKEN' \
  -d 'query=up'

🚨 Troubleshooting Quick Reference

VPN Issues

# Check VPN connection
./scripts/manage-access.sh test-vpn

# Check WireGuard status
docker logs wg-easy

# Test internal connectivity
ping 172.18.0.10  # Pi-hole DNS

# Check firewall rules
sudo iptables -L -n

Service Access Issues

# Check if service is running
docker-compose ps

# Check Traefik routing
docker logs traefik | grep ERROR

# Test service directly
curl -H "Host: monitoring.olanna.ai" http://172.18.0.X:3000

# Check DNS resolution
nslookup monitoring.olanna.ai 172.18.0.10

Security Verification

# Verify ports are blocked
nmap -p 3000,5601,8080 YOUR_SERVER_IP

# Check public service access
curl -I https://status.olanna.ai  # Should work

# Check private service blocking
curl -I https://monitoring.olanna.ai  # Should fail without VPN

🎉 Getting Started Checklist

Production Deployment

Development Setup

Install Docker and Docker Compose
Create Docker network: docker network create olanna-network
Start local stack: docker-compose -f docker-compose-local.yml up -d
Initialize OpenSearch: ./opensearch/setup-indices.sh
Access services on localhost ports

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/vpn-setup
Make your changes
Test thoroughly with both local and VPN setups
Update documentation
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Prometheus API Examples

Metrics Queries

# Instant query
curl "http://localhost:9090/api/v1/query?query=up"

# Range query
curl "http://localhost:9090/api/v1/query_range?query=cpu_usage&start=2024-01-01T00:00:00Z&end=2024-01-01T01:00:00Z&step=60"

# Get all metrics
curl "http://localhost:9090/api/v1/label/__name__/values"

Vault API Examples

Secret Management

# Authenticate
curl -X POST "http://localhost:8200/v1/auth/userpass/login/admin" \
  -d '{"password": "admin-password"}'

# Store secret
curl -X POST "http://localhost:8200/v1/secret/data/myapp" \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -d '{"data": {"password": "secret-value"}}'

# Retrieve secret
curl "http://localhost:8200/v1/secret/data/myapp" \
  -H "X-Vault-Token: $VAULT_TOKEN"

Java Spring Boot Integration

Spring Boot Auto-Configuration (Recommended)

// build.gradle - Clean and simple
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.cloud:spring-cloud-starter-openfeign'
    // One dependency for complete tracing
    implementation 'io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter:1.29.0-alpha'
    implementation 'org.opensearch.client:opensearch-rest-high-level-client:2.11.1'
    implementation 'org.springframework.vault:spring-vault-core:3.0.4'
}

# application.yml - Simple configuration
otel:
  service:
    name: spring-app
    version: 1.0.0
  exporter:
    otlp:
      endpoint: http://localhost:4318
  traces:
    exporter: otlp

Why Spring Boot Auto-Configuration is Better: - ✅ Simpler setup - one dependency instead of external agent - ✅ Spring-native - integrates with Spring profiles and properties - ✅ Type-safe config - IDE autocomplete and validation - ✅ Easier deployment - no agent file management - ✅ Better for containers - smaller Docker images

Alternative: Java Agent (For Non-Spring Apps)

# Use for legacy apps or when you can't modify dependencies
java -javaagent:./opentelemetry-javaagent.jar \
     -Dotel.service.name=my-app \
     -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
     -jar your-app.jar

// No tracing code needed - everything is automatic!
@RestController
@RequestMapping("/api/users")
public class UserController {

    @Autowired
    private UserService userService;

    // Automatically captures: HTTP method, URL, headers, response status, timing
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        return ResponseEntity.ok(userService.findById(id));
    }

    // Automatically captures request/response payloads
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        User saved = userService.save(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(saved);
    }
}

@Service
public class UserService {

    @Autowired
    private UserRepository userRepository;

    @Autowired
    private RestTemplate restTemplate;

    // Database calls automatically traced
    public User findById(Long id) {
        return userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException("User not found"));
    }

    // External HTTP calls automatically traced
    public String callExternalAPI() {
        return restTemplate.getForObject("http://external-service/api", String.class);
    }
}

What Gets Automatically Captured:

✅ All HTTP Requests/Responses (method, URL, headers, status, timing)
✅ Database Queries (SQL, connection pools, timing)
✅ External HTTP Calls (RestTemplate, WebClient, HttpClient)
✅ Exception Stack Traces (errors automatically linked to traces)
✅ JVM Metrics (memory, GC, thread pools)
✅ Custom Annotations (@Async, @Scheduled, etc.)

Manual Tracing (Optional - for custom business logic)

@Configuration public class ObservabilityConfig {

@Bean
public OpenTelemetry openTelemetry() {
    return OpenTelemetrySDK.builder()
        .setTracerProvider(
            SdkTracerProvider.builder()
                .addSpanProcessor(BatchSpanProcessor.builder(
                    OtlpGrpcSpanExporter.builder()
                        .setEndpoint("http://localhost:4317")
                        .build())
                    .build())
                .setResource(Resource.getDefault()
                    .merge(Resource.builder()
                        .put(ResourceAttributes.SERVICE_NAME, "spring-app")
                        .put(ResourceAttributes.SERVICE_VERSION, "1.0.0")
                        .build()))
                .build())
        .build();
}

}

// Instrumented Service @Service public class UserService {

private final Tracer tracer;

public UserService(OpenTelemetry openTelemetry) {
    this.tracer = openTelemetry.getTracer("user-service");
}

public User findUser(Long id) {
    Span span = tracer.spanBuilder("find-user")
        .setAttribute("user.id", id)
        .startSpan();

    try (Scope scope = span.makeCurrent()) {
        // Business logic
        return userRepository.findById(id);
    } catch (Exception e) {
        span.setStatus(StatusCode.ERROR, e.getMessage());
        throw e;
    } finally {
        span.end();
    }
}

} ```

OpenSearch Integration

java // OpenSearch Client Configuration @Configuration public class OpenSearchConfig { @Value("${opensearch.host:localhost}") private String host; @Value("${opensearch.port:9200}") private int port; @Bean public OpenSearchClient openSearchClient() { final HttpHost httpHost = new HttpHost(host, port, "http"); final OpenSearchTransport transport = new RestClientTransport( RestClient.builder(httpHost).build(), new JacksonJsonpMapper() ); return new OpenSearchClient(transport); } } // Search Service @Service public class LogSearchService { private final OpenSearchClient client; public LogSearchService(OpenSearchClient client) { this.client = client; } public List<LogEntry> searchErrorLogs(String timeRange) { SearchRequest request = SearchRequest.of(s -> s .index("app-logs-*") .query(q -> q .bool(b -> b .must(m -> m.term(t -> t.field("level").value("ERROR"))) .must(m -> m.range(r -> r .field("@timestamp") .gte(JsonData.of("now-" + timeRange)) )) ) ) ); try { SearchResponse<LogEntry> response = client.search(request, LogEntry.class); return response.hits().hits().stream() .map(Hit::source) .collect(Collectors.toList()); } catch (Exception e) { throw new RuntimeException("Search failed", e); } } }

Vault Integration

// Vault Configuration
@Configuration
@EnableVaultRepositories
public class VaultConfig extends AbstractVaultConfiguration {

    @Override
    public VaultEndpoint vaultEndpoint() {
        return new VaultEndpoint()
            .setHost("localhost")
            .setPort(8200)
            .setScheme("http");
    }

    @Override
    public ClientAuthentication clientAuthentication() {
        return new TokenAuthentication("your-vault-token");
    }
}

// Secret Service
@Service
public class SecretService {

    private final VaultTemplate vaultTemplate;

    public SecretService(VaultTemplate vaultTemplate) {
        this.vaultTemplate = vaultTemplate;
    }

    public String getSecret(String path, String key) {
        VaultResponseSupport<Map> response = vaultTemplate.read(path, Map.class);
        if (response != null && response.getData() != null) {
            return (String) response.getData().get(key);
        }
        throw new RuntimeException("Secret not found");
    }

    public void storeSecret(String path, Map<String, Object> secrets) {
        vaultTemplate.write(path, secrets);
    }
}

🔄 Maintenance & Updates

Regular Maintenance Tasks

Weekly Tasks

# Update Docker images
docker-compose pull
docker-compose up -d

# Clean up unused resources
docker system prune -f

# Backup critical data
./scripts/backup-volumes.sh

Monthly Tasks

# Rotate OpenSearch indices
curl -X POST "http://localhost:9200/_rollover/app-logs"

# Update SSL certificates (automatic via Traefik)
# Review and update security policies

Scaling Considerations

Horizontal Scaling

Add multiple OpenSearch nodes for clustering
Implement load balancing for application services
Use external databases for production workloads

Vertical Scaling

Increase memory allocation for memory-intensive services
Add more CPU cores for compute-intensive workloads
Upgrade storage to faster SSDs

📦 Default Credentials

Service Credentials

Service	Username	Password	Notes
Grafana	`admin`	`15qIUK8n6WYc`	Monitoring dashboard
RabbitMQ	`rabbitmq`	`A5kwa5ZO7yDb`	Message queue
PostgreSQL	`admin`	`9tRQF5H2TsNM`	Primary database
pgAdmin	`admin@localhost`	`A48hb6WNdW2D`	Database admin
Keycloak	`admin`	`g6KfLOOH60FIkg`	Identity management
Redis	N/A	`eL352XKjfp3l`	Cache (password auth)
Vault	N/A	`2de40c9495e7260a7814b26ff0710ff5a9b8eb92ec6b800e949dc4a850e33053`	Root token

Security Notes

Change all default passwords before production use
Enable two-factor authentication where possible
Use Vault for secure secret management
Regular credential rotation is recommended

🧪 Local Development

Using docker-compose-local.yml

For local development, use the local configuration:

# Start local stack
docker-compose -f docker-compose-local.yml up -d

# Local service URLs
# OpenSearch Dashboards: http://localhost:5601
# Grafana: http://localhost:3000
# Jenkins: http://localhost:8080
# Traefik Dashboard: http://localhost:81

Development Features

Simplified SSL: Self-signed certificates
Debug logging: Increased log verbosity
Hot reloading: Configuration changes without restart
Local storage: Host-mounted volumes for easy access

📞 Support & Contributing

Getting Help

📧 Email: devops@localhost
📚 Documentation: Local Documentation
🐛 Issues: GitHub Issues

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Security

For security issues, please email security@localhost instead of using public issue trackers.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎯 Roadmap

Upcoming Features

Current Version: v2.0.0

Last Updated: December 2024

🙏 Acknowledgments

OpenSearch Project for the excellent search and analytics platform
Traefik Community for the powerful reverse proxy
HashiCorp for Vault and Consul
Grafana Labs for monitoring solutions
CNCF Projects for cloud-native tools