Getting Started

🎉 Welcome! Let's get your observability stack running in 5 minutes.

📋 Prerequisites

Before you begin, make sure you have:

Requirement	Version	Download
Docker Desktop	20.10+	Download
Git	2.0+	Download
Terminal	Any	Built-in on Mac/Linux

Docker Desktop Tips

Mac: Docker Desktop for Mac
Windows: Docker Desktop for Windows (enable WSL2)
Linux: Install via your package manager

Make sure Docker is running before proceeding!

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/MdAshiqurRahmanZayed/django-observability.git
cd django-observability

Step 2: Configure Environment

cp django_app/.env.example django_app/.env

The .env file contains all configuration. Here's what each setting does:

# Database Configuration
DB_NAME=todo_db          # Your database name
DB_USER=postgres         # Database username
DB_PASSWORD=postgres     # Database password (change this in production!)
DB_HOST=obs-postgres     # Internal Docker hostname
DB_PORT=5432             # Database port

# Grafana Configuration
GF_ADMIN_USER=admin      # Grafana admin username
GF_ADMIN_PASSWORD=admin  # Grafana admin password (change this!)

# Slack Alerts (optional - leave empty to disable)
SLACK_WEBHOOK_URL=

# Sentry (optional - leave empty to disable)
SENTRY_DSN=

How to get Slack Webhook URL

Go to https://api.slack.com/apps
Click Create New App → From scratch
Name it (e.g., "Django Alerts") and select workspace
Go to Incoming Webhooks → Toggle On
Click Add New Webhook to Workspace
Select channel (e.g., #alerts)
Copy the webhook URL

Format: See https://api.slack.com/apps to get your webhook URL

How to get Sentry DSN

Go to https://sentry.io (create account if needed)
Click Create Project → Select Django
Copy the DSN from the setup page
Or go to Settings → Projects → Your Project → Client Keys (DSN)

Format: https://<key>@o<org>.ingest.sentry.io/<project>

Leave empty to disable

If you don't need Slack alerts or Sentry error tracking, leave these values empty. Invalid values will cause errors.

Step 3: Start All Services

docker compose -f django_app/docker-compose.yml up -d --build

This starts 10 containers:

Container	Purpose
obs-django	Django application
obs-postgres	PostgreSQL database
obs-prometheus	Metrics collection
obs-grafana	Visualization
obs-loki	Log aggregation
obs-promtail	Log shipping
obs-alertmanager	Alert routing
obs-nginx	Reverse proxy
obs-node-exporter	System metrics
obs-pgadmin	Database admin

Step 4: Verify Everything is Running

docker compose -f django_app/docker-compose.yml ps

Expected output:

NAME                 STATUS          PORTS
obs-django           Up              0.0.0.0:9000->9000/tcp
obs-postgres         Up              0.0.0.0:5439->5432/tcp
obs-prometheus       Up              0.0.0.0:9090->9090/tcp
obs-grafana          Up              0.0.0.0:3000->3000/tcp
obs-loki             Up              0.0.0.0:3100->3100/tcp
obs-promtail         Up              -
obs-alertmanager     Up              0.0.0.0:9093->9093/tcp
obs-nginx            Up              0.0.0.0:80->80/tcp
obs-node-exporter    Up              0.0.0.0:9100->9100/tcp
obs-pgadmin          Up              0.0.0.0:5050->80/tcp

🌐 Access Your Stack

Open these URLs in your browser:

Service	URL	Credentials	What You'll See
🌐 Django App	http://localhost	-	Todo application
📊 Grafana	http://localhost:3000	admin / admin	Dashboards & graphs
📈 Prometheus	http://localhost:9090	-	Metrics & queries
🔔 Alertmanager	http://localhost:9093	-	Alert status
🗄️ pgAdmin	http://localhost:5050	admin@admin.com / admin	Database admin

✅ Verify Your Setup

Test 1: Django Application

curl http://localhost/

You should see HTML response from the Django app.

Test 2: Metrics Endpoint

curl http://localhost:9000/metrics | head

You should see Prometheus metrics like:

# HELP python_gc_objects_collected_total Objects collected during gc
# TYPE python_gc_objects_collected_total counter
python_gc_objects_collected_total{generation="0"} 1234.0

Test 3: Prometheus Health

curl http://localhost:9090/-/healthy

Expected: Prometheus Server is Healthy.

Test 4: Grafana Health

curl http://localhost:3000/api/health

Expected: {"database":"ok"}

🎉 What's Next?

Now that your stack is running, explore these tutorials:

Beginner Path

Architecture Overview - Understand how everything connects
Django App Module - See how metrics are collected
Grafana Module - Create your first dashboard

Intermediate Path

Prometheus Module - Learn PromQL queries
Loki Module - Search logs with LogQL
Alertmanager Module - Set up Slack alerts

Advanced Path

MCP Server Module - AI integration
Custom Dashboards - Build your own
Custom Alerts - Create custom alert rules

🔧 Common Commands

# Start all services
docker compose -f django_app/docker-compose.yml up -d

# Stop all services
docker compose -f django_app/docker-compose.yml down

# Restart a specific service
docker compose -f django_app/docker-compose.yml restart obs-django

# View logs for a service
docker logs -f obs-django

# Access container shell
docker exec -it obs-django /bin/sh

# Rebuild and restart (after code changes)
docker compose -f django_app/docker-compose.yml up -d --build obs-django

❓ Troubleshooting

Docker not running

Make sure Docker Desktop is running:

docker ps

If you get an error, start Docker Desktop and try again.

Port already in use

If you get "port is already allocated" error:

# Find what's using the port
lsof -i :3000

# Stop the conflicting service or change the port in docker-compose.yml

Services not starting

Check logs for errors:

docker compose -f django_app/docker-compose.yml logs

Common issues: - Database not ready (wait a few seconds) - Environment variables not set (check .env) - Docker resources insufficient (increase memory in Docker Desktop)

Cannot connect to localhost

Try these URLs instead:

http://127.0.0.1:3000 (Grafana)
http://0.0.0.0:3000 (Grafana)

Or check if containers are running:

docker ps

📚 More Resources

Ready to learn more? 👇

Architecture Overview →