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)

```bash
# 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

```bash
# 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

```bash
# 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
# 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"]
```

```yaml
# 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
# 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"]
```

```yaml
# 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
# 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"]
```

```yaml
# 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
# 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"]
```

```yaml
# 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):

```go
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

```bash
# 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:

```bash
# 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:

```env
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:

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

Or connect manually:

```bash
docker network connect ophion-network my-container
```

---

## 🔍 Troubleshooting

### No traces appearing?

1. Check collector logs:
   ```bash
   docker logs ophion-otel-collector
   ```

2. Verify network connectivity:
   ```bash
   docker exec my-container curl http://ophion-otel-collector:4318/v1/traces
   ```

3. Check environment variables are set:
   ```bash
   docker exec my-container env | grep OTEL
   ```

### Container can't reach collector?

Make sure your container is on the `ophion-network`:

```bash
docker network connect ophion-network my-container
```

### Server returns 401?

Check `AGENT_KEY` matches in server and agent:

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

---

## 📚 Next Steps

- Read [MANUAL_COMPLETO.md](./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