OKTO Terminal - Docker Deployment Guide¶

This guide covers deploying OKTO Terminal on standalone devices with direct cloud connectivity - no factory server required.

Table of Contents¶

Quick Start
System Requirements
Installation Methods
One-Line Install
Docker Compose
Manual Docker
Kiosk Mode
Configuration
Hardware Setup
Troubleshooting
Updating

Quick Start¶

One-Line Installation (Recommended)¶

For a fresh Linux machine (Debian/Ubuntu):

curl -sSL https://get.okto.ru/terminal | sudo bash

This will: 1. Install Docker 2. Download OKTO Terminal 3. Configure auto-start 4. Open the web interface

System Requirements¶

Minimum Hardware¶

CPU: x86_64 or ARM64, 2+ cores
RAM: 1 GB (2 GB recommended)
Storage: 8 GB (SSD recommended)
Network: Ethernet or WiFi with internet access

Recommended Hardware¶

Intel NUC, Raspberry Pi 4 (4GB+), or similar mini PC
Touch screen display (optional)
Barcode scanner (USB or network)
Label printer (optional)

Supported Operating Systems¶

Ubuntu 20.04 / 22.04 LTS
Debian 11 / 12
Raspberry Pi OS (64-bit)
Any Linux with Docker support

Installation Methods¶

One-Line Install¶

# Basic installation
curl -sSL https://get.okto.ru/terminal | sudo bash

# With custom options
curl -sSL https://get.okto.ru/terminal | sudo OKTO_URL=http://localhost bash

Docker Compose (Recommended for Production)¶

Clone the repository (or download docker-compose.terminal.yml):

git clone https://github.com/okto/terminal.git
cd terminal

Start the container:

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

Open in browser: http://localhost

Manual Docker¶

# Pull the image
docker pull dmitryaksenov/okto-terminal:latest

# Run the container
docker run -d \
  --name okto-terminal \
  --restart unless-stopped \
  -p 80:80 \
  -v okto-data:/app/data \
  -v okto-logs:/app/logs \
  -e TZ=Europe/Moscow \
  dmitryaksenov/okto-terminal:latest

Build From Source¶

# Clone repository
git clone https://github.com/okto/terminal.git
cd terminal

# Build the Docker image
docker build -f docker/Dockerfile.terminal -t okto/terminal:local .

# Run
docker run -d --name okto-terminal -p 80:80 okto/terminal:local

Kiosk Mode¶

Turn any Linux machine into a dedicated OKTO terminal kiosk.

Full Kiosk Installation¶

# Download and run kiosk installer
curl -sSL https://get.okto.ru/kiosk | sudo bash

This will: - Install all dependencies - Configure auto-login - Launch Chromium in fullscreen kiosk mode - Set up auto-updates - Disable unnecessary services

Manual Kiosk Setup¶

Install dependencies:

sudo apt install chromium xorg openbox lightdm unclutter

Create kiosk user:

sudo useradd -m -s /bin/bash okto
sudo usermod -aG docker okto

Configure autologin (/etc/lightdm/lightdm.conf):

[Seat:*]
autologin-user=okto
autologin-user-timeout=0
user-session=openbox

Create autostart (/home/okto/.config/openbox/autostart):

#!/bin/bash
xset s off && xset -dpms
unclutter -idle 3 -root &
chromium --kiosk --noerrdialogs http://localhost &

Kiosk Features¶

Auto-start: System boots directly into OKTO Terminal
Fullscreen: No browser chrome, maximized UI
Auto-recovery: Restarts browser if it crashes
Hidden cursor: Cursor hides after 3 seconds
No screensaver: Display stays on 24/7
Auto-update: Updates nightly at 3 AM

Configuration¶

Environment Variables¶

Variable	Default	Description
`TZ`	`Europe/Moscow`	Timezone
`OKTO_CLOUD_URL`	`https://app.okto.ru/api/v1/`	Cloud API URL
`OKTO_DEVICE_ID`	(auto-generated)	Unique device identifier
`OKTO_DEVICE_TOKEN`	(after provisioning)	Authentication token
`OKTO_LOG_LEVEL`	`INFO`	Logging level

Configuration File¶

Mount a custom config file:

docker run -d \
  --name okto-terminal \
  -p 80:80 \
  -v /path/to/config.yaml:/app/config/edge-service.yaml:ro \
  dmitryaksenov/okto-terminal:latest

Example Configuration (`edge-service.yaml`)¶

server:
  port: 8080

cloud:
  baseUrl: "https://app.okto.ru/api/v1/"
  connectionTimeout: 25000
  requestTimeout: 25000

database:
  path: "/app/data/okto.db"

scanner:
  type: "network"
  host: "192.168.1.100"
  port: 9100

printer:
  type: "network"
  host: "192.168.1.101"
  port: 9100

logging:
  level: "INFO"
  file: "/app/logs/edge-service.log"

Hardware Setup¶

Barcode Scanner¶

Network Scanner (Recommended)¶

scanner:
  type: "network"
  host: "192.168.1.100"
  port: 9100

USB Scanner¶

# Add to docker-compose.yml:
devices:
  - /dev/ttyUSB0:/dev/ttyUSB0

scanner:
  type: "serial"
  port: "/dev/ttyUSB0"
  baudRate: 115200

Label Printer¶

Supported Printer Types¶

Type	Default Port	Protocol
VIDEOJET	8888	Text commands
MARKEM	21000	Binary STX/ETX
SOLMARK	2030	JSON
LINEKO	2030	Custom separators
DOMINO	2030	Binary SOH/STX/ETX/ETB
ZPL	9100	Zebra Programming Language

Network Printer¶

printer:
  type: VIDEOJET  # or MARKEM, SOLMARK, LINEKO, DOMINO, ZPL
  host: "192.168.1.101"
  port: 8888      # Uses default if not specified

USB Printer¶

# Add to docker-compose.yml:
devices:
  - /dev/usb/lp0:/dev/usb/lp0

Touch Screen¶

For touch screen terminals, no additional configuration is needed. The UI is optimized for touch interaction.

Troubleshooting¶

Container Won't Start¶

# Check logs
docker logs okto-terminal

# Check health
docker inspect --format='{{.State.Health.Status}}' okto-terminal

Cannot Connect to Cloud¶

Check internet connectivity:

docker exec okto-terminal ping -c 3 app.okto.ru

Verify cloud URL:

docker exec okto-terminal curl -v https://app.okto.ru/api/v1/health

Scanner Not Working¶

Check scanner is detected:

# For USB
lsusb

# For serial
ls -la /dev/ttyUSB*

Check permissions:

# Add user to dialout group
sudo usermod -aG dialout $USER

Browser Issues in Kiosk Mode¶

Check X server:
```
systemctl status lightdm
```
Check browser logs:
```
journalctl -u lightdm -f
```

Test manually:

sudo -u okto DISPLAY=:0 chromium http://localhost

Reset Terminal¶

# Stop container
docker-compose -f docker-compose.terminal.yml down

# Remove data (WARNING: deletes all local data!)
docker volume rm okto-terminal-data

# Restart
docker-compose -f docker-compose.terminal.yml up -d

Updating¶

Automatic Updates (Kiosk Mode)¶

If installed via kiosk installer, updates happen automatically at 3 AM.

Manual Update¶

# Pull latest image
docker-compose -f docker-compose.terminal.yml pull

# Restart with new image
docker-compose -f docker-compose.terminal.yml up -d

# Clean up old images
docker image prune -f

Update Script¶

#!/bin/bash
cd /opt/okto
docker-compose pull
docker-compose up -d
docker system prune -f

Security Considerations¶

Network Security¶

Run on isolated VLAN if possible
Use firewall to restrict outbound traffic to OKTO cloud only
Enable HTTPS for web interface (nginx config)

Physical Security¶

Enable BIOS password
Disable USB boot
Lock kiosk enclosure

Data Security¶

Local database is encrypted at rest
Device tokens are securely stored
All cloud communication is over HTTPS

Frequently Asked Questions¶

Can I run multiple terminals on one machine?¶

Yes, use different ports:

docker run -d --name okto-terminal-1 -p 8081:80 dmitryaksenov/okto-terminal:latest
docker run -d --name okto-terminal-2 -p 8082:80 dmitryaksenov/okto-terminal:latest

How do I backup terminal data?¶

# Create backup
docker run --rm -v okto-data:/data -v $(pwd):/backup alpine tar czf /backup/okto-backup.tar.gz /data

# Restore backup
docker run --rm -v okto-data:/data -v $(pwd):/backup alpine tar xzf /backup/okto-backup.tar.gz -C /

Can I use ARM devices (Raspberry Pi)?¶

Yes! The Docker image supports ARM64. Use Raspberry Pi 4 with 4GB+ RAM.

How do I access the API directly?¶

The API is available at http://localhost/api/v1/. For example:

curl http://localhost/api/v1/health

Support¶

Documentation: https://docs.okto.ru
GitHub Issues: https://github.com/okto/terminal/issues
Email: support@okto.ru