visionect/visionect-server-v3 repository overview

⁠🚀 Visionect Server 3 (VSS) Deployment Guide

⁠⚠️ Critical Information

IMPORTANT

Firmware Deadlines: As of September 1, 2026, VSS version 8.4.0+ is required to update device firmware.

PostgreSQL 18+ Layout: Modern Postgres images require volume mounting to the parent directory (/var/lib/postgresql) to avoid startup errors. The configuration below is pre-optimized for this.

⁠🏷️ Understanding Image Tags

Our Docker repository uses specific tags to ensure compatibility with your hardware and to maintain stability in production.

Which one should I use?

• For Mac (M-series) or Raspberry Pi: Use the -arm suffix (e.g., visionect/visionect-server-v3:8.5.5-arm).
• For Standard Servers/Windows: Use the standard version number (e.g., visionect/visionect-server-v3:8.5.5).

⁠🛠️ Quick Start (Docker Compose)

The following docker-compose.yml is configured for Postgres 18 compatibility and version stability.

services:
  vserver3:
    container_name: vss
    image: visionect/visionect-server-v3:latest
    privileged: true
    ulimits:
      core: 0
    depends_on:
      - redis
      - postgres_db
    cap_add:
      - MKNOD
      - SYS_ADMIN
    devices:
      - "/dev/fuse:/dev/fuse"
    restart: always
    links:
      - "postgres_db:postgres"
      - "redis:redis"
    ports:
      - 8081:8081
      - 11113:11113
    environment:
      - DB2_1_PORT_5432_TCP_ADDR=postgres
      - DB2_1_PORT_5432_TCP_USER=visionect
      - DB2_1_PORT_5432_TCP_PASS=visionect
      - DB2_1_PORT_5432_TCP_DB=koala
      - REDIS_ADDRESS=redis:6379
      - VISIONECT_SERVER_ADDRESS=localhost
      - VSS_LICENSE_ID="dummy"  # Replace with your production ID
    volumes:
      - /dev/shm:/dev/shm
      - ./logs:/var/log/vss

  postgres_db:
    container_name: pdb
    image: postgres:18
    restart: always
    ports: 
      - 5432:5432
    environment:
      - POSTGRES_USER=visionect
      - POSTGRES_DB=koala
      - POSTGRES_PASSWORD=visionect
      - PGPASSWORD=visionect
      # Essential for Postgres 18+ with volume mounted to parent
      - PGDATA=/var/lib/postgresql/data/main
    volumes:
      # Mount to parent directory for "pg_ctlcluster" compatibility
      - ./pgdata:/var/lib/postgresql

  redis:
    image: redis:latest
    restart: always

⁠🔐 Licensing (VSS 7.7.0+)

VSS now uses a "hard" license enforcement model. Each instance requires a unique ID and a valid subscription for connected devices.

• Trial: New instances start with a trial license linked to your unique VSS ID.
• Expirations: If a license expires, the device limit drops to 0, and devices will disconnect until payment is verified via Chargebee.
• Cloud vs On-Prem: Cloud users are managed automatically. On-premise customers should contact support for their specific docker-compose.yml bundle.

⁠🔄 Upgrading Legacy Systems

• From VSS 2.x: You must first migrate to Docker. Use the VISIONECT_SERVER_CONFIG environment variable to import your old config.json.
• Database Size Warning: If your database is >4GB, the migration to VSS 6.5.x+ can take up to an hour. Do not interrupt the process once it begins.