Files
DataStack/docs/users/getting-started.md
T
Team Dark Devil 40a6855724 feat(sdk): refactor Python SDK documentation
- Standardize Python SDK (`datastack`) documentation with a new multi-file suite.
- Update `datastack-sdk` to serve as a backward-compatible shim for the canonical `datastack` package.
- Update project manifest and memory map to reflect current SDK structure and v2.2.0 features.
2026-11-18 10:03:40 +06:00

4.5 KiB

Getting Started with DataStack

This fast-track tutorial guides you from a fresh server to a fully running DataStack instance collecting live telemetry in under 5 minutes.


Step 1: Deploy with Docker Compose

Clone the repository and copy the environment template:

git clone https://github.com/vibtoolshq/datastack.git
cd datastack
cp .env.example .env

Generate 32+ character secrets for production:

# Generate random keys in Linux or macOS:
openssl rand -hex 32

In .env, set your secrets and admin email:

DATASTACK_ADMIN_SESSION_SECRET=your-32-char-session-secret-here
DATASTACK_JWT_SECRET=your-32-char-jwt-secret-here
DATASTACK_ADMIN_SETUP_KEY=your-32-char-setup-key-here
DATASTACK_INTERNAL_SECRET=your-32-char-internal-secret-here
DATASTACK_ADMIN_EMAIL=admin@example.com

Launch the stack:

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

Verify that all 5 services are healthy:

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

Step 2: Complete Initial Administrator Setup

  1. Open your browser and navigate to:
    http://localhost/vcon/setup
    # Or https://your-domain.example/vcon/setup
    
  2. Enter:
    • Administrator Email: Must match DATASTACK_ADMIN_EMAIL (or your chosen admin email).
    • Administrator Password: Minimum 8 characters.
    • Setup Security Key: Enter the exact string from DATASTACK_ADMIN_SETUP_KEY.
  3. Click Complete Initial Setup. You are automatically logged in and redirected to /vcon/dashboard.

Step 3: Register Your First SDK Client

  1. In the sidebar, click Clients (/vcon/clients).
  2. Click + Register Client.
  3. Fill in the fields:
    • Client Identifier: sensor_gateway_01 (lowercase alphanumeric and underscores).
    • Client Name: Primary Sensor Gateway.
    • Rate Limit: 100 (max events per second).
  4. Click Register Client.
  5. Copy the generated Bearer JWT Token. Store it securely.

Step 4: Dispatch Your First Event via curl

Send a test telemetry event to the REST ingestion API:

curl -X POST "http://localhost/api/events" \
  -H "Authorization: Bearer YOUR_GENERATED_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "test_event_001",
    "timestamp": "2026-11-17T12:00:00Z",
    "data": {
      "temperature": 23.4,
      "humidity": 45,
      "status": "ONLINE"
    }
  }'

Expected Response:

{
  "success": true,
  "eventId": "test_event_001",
  "event": {
    "clientId": "sensor_gateway_01",
    "eventId": "test_event_001",
    "timestamp": "2026-11-17T12:00:00Z",
    "payload": "{\"temperature\":23.4,\"humidity\":45,\"status\":\"ONLINE\"}"
  }
}

Step 5: Connect with the Python Client SDK

Install the official Python SDK:

pip install datastack

In your Python project directory, create config.datastack.py:

DATASTACK_CONFIG = {
    "SERVER_URL": "http://localhost",
    "CLIENT_TOKEN": "YOUR_GENERATED_JWT_TOKEN",
    "AUTO_CONNECT": True,
}

Create main.py and run it:

from datastack import DataStack
import time

# Auto-discovers config.datastack.py in the current directory
client = DataStack()

print(f"Connected to DataStack as client: {client.client_id}")

# Stream 5 test events
for i in range(5):
    res = client.send(
        data={"reading_index": i, "voltage": 3.3 + (i * 0.05)},
        event_id=f"reading_{i}_{int(time.time())}"
    )
    print(f"Dispatched event {i}: {res.get('eventId')} via {res.get('transport')}")
    time.sleep(1)

client.disconnect()

Step 6: Verify Data in the Admin Console

  1. Dashboard Overview (/vcon/dashboard):
    • Check the Active Buffer gauge — incoming events are queued in Redis / memory.
    • Observe the Live Activity Stream updating in real time.
  2. Data Browser (/vcon/data):
    • Filter by client sensor_gateway_01.
    • View your ingested events with exact timestamps and formatted JSON payloads.
  3. Data Export (/vcon/export):
    • Click Export Dataset to download a clean, consolidated CSV file ready for Excel or Python analysis.

Next Steps