Skip to content

OKTO Traceability System - User Guide

Complete guide for operators, managers, and administrators.

Руководство пользователя на русском

Table of Contents

  1. Getting Started
  2. Connection Modes
  3. Device Provisioning
  4. Daily Operations
  5. Mock Mode (Testing)
  6. Administration
  7. Troubleshooting

Getting Started

System Requirements

Hardware: - x86_64 Linux system (Ubuntu 20.04+, Debian 11+, or similar) - Minimum 2GB RAM, 4GB recommended - 10GB disk space - Network connectivity (Ethernet recommended)

Optional Hardware: - Barcode scanner (Matrix, Honeywell, or compatible) - Label printer (Videojet, Markem, or ZPL-compatible) - PLC with MODBUS TCP support

Software: - Docker and Docker Compose (recommended) - Or: JDK 17+, Node.js 20+ (for native installation)

Installation

# Clone or download the system
cd /opt
git clone <repository-url> okto-traceability
cd okto-traceability

# Start all services
docker-compose up -d

# Check status
docker-compose ps

Native Installation

# Build the system
make build

# Start edge service
./gradlew :edge-service:run

# In another terminal, start operator UI
cd operator-ui && npm run dev

First-Time Access

  1. Open a web browser
  2. Navigate to http://localhost:3000 (Operator UI)
  3. Login with default credentials:
  4. Username: operator
  5. Password: operator123

⚠️ Security: Change default passwords immediately in production!

Connection Modes

The system supports two connection modes for different deployment scenarios.

Via Local Server Mode

Best for: Factories with central infrastructure, multiple production lines

[Edge Devices] → [Factory Server] → [OKTO Cloud]

Advantages: - Centralized management - Better network resilience - Local data aggregation - Reduced cloud bandwidth

Setup: 1. Deploy Factory Server 2. Configure edge services to point to factory server 3. Factory server handles cloud synchronization

Direct Cloud Mode

Best for: Standalone deployments, remote locations, pilot programs

[Edge Device] → [OKTO Cloud]

Advantages: - Simpler deployment - No factory server required - Direct cloud integration

Setup: 1. Deploy edge service only 2. Configure for Direct Cloud mode 3. Provision device with OKTO Cloud credentials

Checking Current Mode

In the Operator UI: 1. Go to Settings (gear icon) 2. Look for Connection Mode section 3. Current mode displayed: "Direct Cloud" or "Via Local Server"

Switching Modes

If mode switching is enabled:

  1. Go to Settings → Connection Mode
  2. Select desired mode
  3. Click Apply
  4. System will reconnect

Note: Mode switching may require re-provisioning in Direct Cloud mode.

Device Provisioning

Device provisioning is required for Direct Cloud mode to authenticate your device with OKTO Cloud.

Prerequisites

  • Valid OKTO Cloud account
  • Device registered in your company's OKTO Cloud portal
  • Network access to app.okto.ru

Provisioning Steps

Step 1: Open Provisioning Page

Navigate to http://localhost:3000/provision

You'll see the provisioning wizard.

Step 2: Sign In

  1. Enter your OKTO Cloud email
  2. Enter your password
  3. Click Sign In
┌────────────────────────────────────────┐
│         Sign in to OKTO Cloud          │
│                                        │
│  Email: [your.email@company.com    ]   │
│                                        │
│  Password: [••••••••••             ]   │
│                                        │
│           [ Sign In ]                  │
└────────────────────────────────────────┘

Step 3: Select Device

After signing in, you'll see available devices:

┌────────────────────────────────────────┐
│         Select Your Device             │
│                                        │
│  ○ Production Line 1                   │
│    Company: Demo Factory LLC           │
│                                        │
│  ● Production Line 2                   │  ← Selected
│    Company: Demo Factory LLC           │
│                                        │
│  ○ Quality Control Station             │
│    Company: Demo Factory LLC           │
│                                        │
│           [ Activate ]                 │
└────────────────────────────────────────┘

Select your device and click Activate.

Step 4: Confirmation

Upon successful activation:

┌────────────────────────────────────────┐
│      ✓ Device Provisioned!             │
│                                        │
│  Device: Production Line 2             │
│  Company: Demo Factory LLC             │
│  Industry: Milk                        │
│                                        │
│  Your device is now connected to       │
│  OKTO Cloud and ready for operation.   │
│                                        │
│      [ Go to Dashboard ]               │
└────────────────────────────────────────┘

Deprovisioning

To reset provisioning (e.g., to switch devices):

  1. Go to Provisioning page
  2. Click Deprovision (if already provisioned)
  3. Confirm the action
  4. Re-provision with new device

Daily Operations

Starting a Production Shift

  1. Login to Operator UI
  2. Verify Connection: Check status indicator (green = connected)
  3. Select Production Line (if multiple)
  4. Begin Scanning

Scanning Codes

The system processes barcode scans automatically:

┌────────────────────────────────────────────────────────┐
│                    Scan Status                          │
├────────────────────────────────────────────────────────┤
│  Scanner: ● Connected                                   │
│  Mode: Production                                       │
│                                                         │
│  Last Scan: 010460000000001721ABC123...                │
│  Status: ✓ Accepted                                    │
│                                                         │
│  Today's Statistics:                                    │
│  ├── Scanned: 1,234                                    │
│  ├── Accepted: 1,220                                   │
│  ├── Rejected: 10                                      │
│  └── Duplicates: 4                                     │
└────────────────────────────────────────────────────────┘

Scan Statuses

Status Meaning Action
✓ Accepted Code valid and recorded Continue scanning
✗ Rejected Invalid code format Check product/label
⚠ Duplicate Code already scanned Remove duplicate item
? Unknown Processing error Retry or check system

Creating Batches

Bottles are grouped into batches:

  1. Start New Batch: Click New Batch or scan triggers auto-creation
  2. Scan Bottles: Add bottles to current batch
  3. Complete Batch: Click Close Batch when full
┌────────────────────────────────────────────────────────┐
│              Current Batch: B-2024-001234              │
├────────────────────────────────────────────────────────┤
│  Status: In Progress                                    │
│  Bottles: 45 / 50 (90%)                                │
│                                                         │
│  [■■■■■■■■■■■■■■■■■■░░]                                │
│                                                         │
│  [ Close Batch ]  [ Cancel Batch ]                     │
└────────────────────────────────────────────────────────┘

Creating Pallets

Batches are grouped into pallets:

  1. Start New Pallet: Click New Pallet
  2. Scan Batches: Scan batch labels to add
  3. Complete Pallet: Click Close Pallet when full

Handling Errors

Invalid Code

Error: Code rejected - Invalid GTIN

Cause: Code doesn't match expected product GTIN
Action: Check that you're scanning the correct product

Duplicate Code

Warning: Duplicate code detected

Cause: This code was already scanned
Action: Remove the duplicate item from production

Connection Lost

Warning: Offline mode - data will sync when connected

Cause: Network connection lost
Action: Continue working, data syncs automatically when reconnected

Mock Mode (Testing)

Mock mode allows testing all functionality without OKTO Cloud connectivity.

Activating Mock Mode

  1. Navigate to Provisioning page (/provision)
  2. Type tttt quickly (within 2 seconds)
  3. You'll see: "Mock mode activated"
  4. Demo credentials appear automatically
  5. Click Sign In
┌────────────────────────────────────────┐
│     🔧 MOCK MODE ACTIVATED 🔧          │
│                                        │
│  Email: [demo@okto.ru            ]     │
│  Password: [demo123              ]     │
│                                        │
│  ⚠ This is a test environment.        │
│  No data will be sent to cloud.        │
│                                        │
│           [ Sign In ]                  │
└────────────────────────────────────────┘

Mock Mode Indicator

When mock mode is active, you'll see a banner:

┌────────────────────────────────────────────────────────┐
│  ⚠ MOCK MODE - No cloud connection - Testing only     │
│                                          [Exit Mock]   │
└────────────────────────────────────────────────────────┘

Scanner Simulator

Mock mode includes a scanner simulator for testing:

┌─────────────────────────────────┐
│      Scanner Simulator          │
├─────────────────────────────────┤
│  Code: [                    ]   │
│                                 │
│  [ Generate Random ]            │
│  [ Simulate Scan   ]            │
│                                 │
│  ─────────────────────────────  │
│  Industry: [ Milk        ▼]     │
│  Mode:     ○ Single  ● Burst    │
│  Speed:    [████░░░░░░] 5/sec   │
└─────────────────────────────────┘

Features: - Manual Entry: Type a code and click "Simulate Scan" - Generate Random: Create valid codes for selected industry - Burst Mode: Simulate rapid scanning for stress testing

Mock Data

Mock mode includes pre-configured data:

Data Value
Company Demo Factory LLC
Industry Milk
Devices 3 demo devices
Production Lines 2 lines
Product GTIN 04600000000001

Exiting Mock Mode

Click Exit Mock in the banner, or: 1. Go to Settings 2. Disable Mock Mode 3. Re-provision with real credentials

Administration

User Management

Roles:

Role Permissions
Admin Full access, user management
Manager Reports, batch management
Operator Scanning, basic operations
Viewer Read-only access

Creating Users (Admin only):

  1. Go to Management Dashboard (localhost:3001)
  2. Navigate to Users
  3. Click Create
  4. Fill in details and assign role
  5. Save

Terminal Management

Registering Terminals:

  1. Management Dashboard → Terminals
  2. Click Add Terminal
  3. Enter terminal details
  4. Assign to production line
  5. Save

Terminal Status:

Status Meaning
🟢 Online Connected and active
🟡 Idle Connected but inactive
🔴 Offline Not connected
⚪ Unknown Status unavailable

Connection Settings

Global Settings (affects all devices):

  1. Management Dashboard → Settings → Connection
  2. Set default connection mode
  3. Configure failover behavior
  4. Save

Per-Device Override:

  1. Management Dashboard → Terminals
  2. Select terminal
  3. Edit connection mode
  4. Save

Viewing Logs

System Logs: 

# Docker
docker-compose logs -f edge-service

# Native
tail -f logs/edge-service.log

Audit Logs: - Management Dashboard → Audit Log - Filter by user, action, date

Troubleshooting

Connection Issues

"Cloud connection failed"

Symptoms: Red connection indicator, sync errors

Solutions: 1. Check network connectivity: ping app.okto.ru 2. Verify firewall allows HTTPS (port 443) 3. Check device provisioning status 4. Verify cloud credentials haven't expired

"Factory server unreachable"

Symptoms: Cannot sync with local server

Solutions: 1. Check factory server is running 2. Verify network path to server 3. Check server hostname/IP in config 4. Verify firewall rules

Scanner Issues

"Scanner not detected"

Solutions: 1. Check physical connection 2. Verify scanner is powered on 3. Check serial port permissions 4. Restart edge service

"Invalid codes from scanner"

Solutions: 1. Clean scanner lens 2. Check scanner programming 3. Verify barcode symbology settings 4. Test with known good barcode

Sync Issues

"Sync queue growing"

Symptoms: Queue size increasing, data not syncing

Solutions: 1. Check connection status 2. Verify cloud/server credentials 3. Check for server errors in logs 4. Restart edge service if stuck

"Duplicate sync errors"

Solutions: 1. Check for network instability 2. Verify only one sync process running 3. Clear sync queue if corrupted (caution: may lose data)

Performance Issues

"Slow response times"

Solutions: 1. Check system resources (CPU, RAM) 2. Verify database isn't full 3. Check network latency 4. Review log files for errors

"High CPU usage"

Solutions: 1. Check for runaway processes 2. Reduce logging verbosity 3. Verify no infinite loops in scanner 4. Restart services

Getting Help

Terminal Help: 

./docs/cli/okto-help troubleshoot

Log Collection: 

# Collect all logs for support
make collect-logs

System Status: 

# Quick system check
./test-suite/quick-check.sh

Keyboard Shortcuts

Shortcut Action
tttt Activate mock mode (on provisioning page)
Ctrl+L Toggle language
Ctrl+S Open settings
Escape Close dialogs

Quick Reference Card

URLs

Service URL
Operator UI http://localhost:3000
Management Dashboard http://localhost:3001
Grafana http://localhost:3002

Default Credentials

User Password Role
admin admin123 Administrator
manager manager123 Manager
operator operator123 Operator

API Endpoints

Endpoint Description
GET /health System health
GET /api/v1/scanner/status Scanner status
GET /api/v1/connection/status Connection status
GET /api/v1/sync/status Sync queue status

Terminal Commands

make docker-up      # Start all services
make docker-down    # Stop all services
make docker-logs    # View logs
make docs           # Open documentation

Back to README | API Reference | Deployment Guide