ophion/docs/QUICK_START.md

🐍 OPHION - Quick Start Guide

Get full observability (traces, metrics, logs) for your applications in minutes.

📋 Prerequisites

• Docker & Docker Compose v2+
• 4GB RAM minimum
• Ports available: 3000, 4317, 4318, 8080

---

🚀 1. Install Ophion (Single Command)

# Clone and start
git clone https://github.com/bigtux/ophion.git
cd ophion
docker compose up -d

That's it! Wait ~2 minutes for all services to start.

Verify Installation

# Check all services are running
docker compose ps

# Should see:
# ophion-server       running (healthy)
# ophion-dashboard    running
# ophion-otel-collector running (healthy)
# ophion-postgres     running (healthy)
# ophion-redis        running (healthy)

Access Points

Service	URL	Description
Dashboard	http://localhost:3000	Web UI for traces, metrics, logs
API	http://localhost:8080	REST API
OTLP gRPC	localhost:4317	OpenTelemetry gRPC endpoint
OTLP HTTP	localhost:4318	OpenTelemetry HTTP endpoint

---

🔧 2. Instrument Your Application

Quick Method: Use the Universal Script

# Auto-detect language
./instrument.sh my-container

# Or specify language
./instrument.sh my-container nodejs
./instrument.sh my-container python
./instrument.sh my-container java
./instrument.sh my-container dotnet

Manual Configuration by Language

Node.js

# Dockerfile
FROM node:20-alpine

# Add OTel packages
RUN npm install @opentelemetry/auto-instrumentations-node @opentelemetry/sdk-node

COPY . .

# Run with auto-instrumentation
CMD ["node", "--require", "@opentelemetry/auto-instrumentations-node/register", "app.js"]

# docker-compose.yml
services:
  myapp:
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion-otel-collector:4318
      - OTEL_SERVICE_NAME=my-nodejs-app
    networks:
      - ophion-network

networks:
  ophion-network:
    external: true

Python

# Dockerfile
FROM python:3.11-slim

RUN pip install opentelemetry-distro opentelemetry-exporter-otlp
RUN opentelemetry-bootstrap -a install

COPY . .

CMD ["opentelemetry-instrument", "python", "app.py"]

# docker-compose.yml
services:
  myapp:
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion-otel-collector:4318
      - OTEL_SERVICE_NAME=my-python-app
      - OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    networks:
      - ophion-network

Java

# Dockerfile
FROM eclipse-temurin:21-jre

# Download OTel Java agent
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar /otel/agent.jar

COPY target/app.jar /app.jar

CMD ["java", "-javaagent:/otel/agent.jar", "-jar", "/app.jar"]

# docker-compose.yml
services:
  myapp:
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion-otel-collector:4318
      - OTEL_SERVICE_NAME=my-java-app
      - JAVA_TOOL_OPTIONS=-javaagent:/otel/agent.jar
    networks:
      - ophion-network

.NET

# Dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0

# Download OTel .NET instrumentation
ADD https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/opentelemetry-dotnet-instrumentation-linux-glibc-x64.zip /tmp/otel.zip
RUN apt-get update && apt-get install -y unzip && \
    unzip /tmp/otel.zip -d /otel && rm /tmp/otel.zip

COPY --from=build /app/publish .

ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658571}
ENV CORECLR_PROFILER_PATH=/otel/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
ENV DOTNET_ADDITIONAL_DEPS=/otel/AdditionalDeps
ENV DOTNET_SHARED_STORE=/otel/store
ENV DOTNET_STARTUP_HOOKS=/otel/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
ENV OTEL_DOTNET_AUTO_HOME=/otel

CMD ["dotnet", "MyApp.dll"]

# docker-compose.yml
services:
  myapp:
    environment:
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion-otel-collector:4318
      - OTEL_SERVICE_NAME=my-dotnet-app
    networks:
      - ophion-network

Go

Go requires code changes (compile-time instrumentation):

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

func main() {
    // Initialize tracer
    exporter, _ := otlptracehttp.New(context.Background())
    tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
    otel.SetTracerProvider(tp)
    
    // Wrap HTTP handlers
    http.Handle("/", otelhttp.NewHandler(myHandler, "myHandler"))
}

---

📊 3. View Your Data

Dashboard

Open http://localhost:3000 in your browser.

Default Login:

• Email: admin@ophion.io
• Password: OphionAdmin123!

API Examples

# Get traces
curl http://localhost:8080/api/v1/traces \
  -H "Authorization: Bearer <your-token>"

# Get metrics
curl "http://localhost:8080/api/v1/metrics?service=my-app&name=http.request.duration" \
  -H "Authorization: Bearer <your-token>"

# Get logs
curl "http://localhost:8080/api/v1/logs?service=my-app&level=error" \
  -H "Authorization: Bearer <your-token>"

---

🔑 Authentication

For the Dashboard (Users)

Register and login at http://localhost:3000

For Applications (OTLP)

Applications send telemetry to the otel-collector (ports 4317/4318) which doesn't require auth by default.

For the API (Agents)

Use the AGENT_KEY environment variable:

# Default key (change in production!)
AGENT_KEY=ophion-secret-agent-key-2024

# Custom key
export AGENT_KEY=my-super-secret-key
docker compose up -d

---

📁 Environment Variables

Variable	Default	Description
AGENT_KEY	ophion-secret-agent-key-2024	Key for agent authentication
JWT_SECRET	ophion-jwt-secret-...	Secret for JWT tokens
DATABASE_URL	postgres://...	PostgreSQL connection
REDIS_URL	redis://redis:6379	Redis connection

Create a .env file in the project root:

AGENT_KEY=my-production-key-here
JWT_SECRET=my-production-jwt-secret

---

🐳 Docker Network

Your instrumented applications need to be on the same network as Ophion:

# Your app's docker-compose.yml
networks:
  ophion-network:
    external: true

Or connect manually:

docker network connect ophion-network my-container

---

🔍 Troubleshooting

No traces appearing?

1. Check collector logs:

   docker logs ophion-otel-collector
   

2. Verify network connectivity:

   docker exec my-container curl http://ophion-otel-collector:4318/v1/traces
   

3. Check environment variables are set:

   docker exec my-container env | grep OTEL
   

Container can't reach collector?

Make sure your container is on the ophion-network:

docker network connect ophion-network my-container

Server returns 401?

Check AGENT_KEY matches in server and agent:

docker exec ophion-server env | grep AGENT_KEY
docker exec ophion-agent env | grep OPHION_API_KEY

---

📚 Next Steps

• Read MANUAL_COMPLETO.md for advanced configuration
• Set up alerts at /alerts in the dashboard
• Configure AI insights with your OpenAI key
• Deploy to production with proper secrets

---

🆘 Support

• Issues: https://github.com/bigtux/ophion/issues
• Docs: https://ophion.io/docs