OOCSI Server

The OOCSI server is the central hub and message broker of an OOCSI network. It receives messages from connected clients, routes direct communications, broadcasts channel events, manages presence tracking, and executes server-side filter and transform expressions.

Before setting up your own server: check whether an existing OOCSI server is already running in your institution or lab (e.g., oocsi.id.tue.nl). If not, you can run an OOCSI server locally on your development machine or deploy it to a cloud server using Docker.

---

Server Versions

The OOCSI server is available in two main distributions:

Distribution	Supported Protocols	Included Tools & Web Features	Recommended Use
oocsi-web (Docker / Podman)	TCP (4444) + WebSockets (9000) + HTTP/SSE	Full Web Dashboard (/dashboard), Network Visualizer (/network), Metrics (/metrics), OOCSI Things, and HTTP Call-Response	Recommended: Production setups, classrooms, and projects involving web browsers.
Mini Server (OOCSI_server.jar)	Native TCP socket (4444)	Lightweight headless console application; no WebSockets or web tools.	Quick local testing on computers with Java installed.

---

Quickstart with Docker or Podman

flowchart TD
    subgraph Container["oocsi-web Container (Docker / Podman)"]
        subgraph Inbound["Inbound Network Adapters"]
            TCP["NIO TCP Server<br/>Port 4444"]
            WS["WebSocket Handler<br/>Port 9000 /ws"]
            REST["REST & SSE Controller<br/>Port 9000 /send, /subscribe"]
        end

        subgraph Dispatch["Core Broker Dispatcher"]
            REGISTRY["Client & Channel Registry"]
            BUS["Internal Event Bus"]
            FILTER_ENGINE["Filter & Transform Pipeline"]
        end

        subgraph Services["Background Services"]
            HEARTBEAT["Ping & Heartbeat<br/>(5s ping, 120s timeout)"]
            RETENTION["Message Retention Cache<br/>(max 48h)"]
            DELAY_QUEUE["Delayed & Scheduled Queue<br/>(_DELAY & _SCHEDULE)"]
            PRESENCE_SRV["Presence Service<br/>(presence(channel))"]
        end

        subgraph WebTools["Integrated Web Tools"]
            DASH["Dashboard (/dashboard)"]
            NETVIS["Network Visualizer (/network)"]
            CANVAS["Data Canvas (/datacanvas)"]
            THINGS["Things Hub (/things)"]
        end
    end

    Inbound <--> BUS
    BUS <--> REGISTRY
    BUS <--> FILTER_ENGINE
    BUS <--> Services
    BUS <--> WebTools

The easiest and most reliable way to run the full oocsi-web server is using the official container image hosted on GitHub Container Registry: ghcr.io/iddi/oocsi-web:latest.

Running with Docker

docker run -d \
  --name oocsi-server \
  -p 9000:9000 \
  -p 4444:4444 \
  --restart unless-stopped \
  ghcr.io/iddi/oocsi-web:latest

Running with Podman

podman run -d \
  --name oocsi-server \
  -p 9000:9000 \
  -p 4444:4444 \
  ghcr.io/iddi/oocsi-web:latest

Port Mappings

• 9000: HTTP server, Web Dashboard, and WebSocket endpoint (ws://localhost:9000/ws).
• 4444: Native OOCSI TCP socket port (for Java, Python, and ESP/Arduino clients).

Once running, access the web tools in your browser:

• Web Dashboard: http://localhost:9000/dashboard
• Real-time Network Visualizer: http://localhost:9000/network
• Server Metrics: http://localhost:9000/metrics
• WebSocket Endpoint: ws://localhost:9000/ws

---

Mini Server (Java Standalone JAR)

The Mini Server is a single .jar file that runs headless on any machine with Java (JRE 11 or higher) installed. It supports all native TCP clients (Java, Processing, Python, C++, MicroPython).

Download

Download the latest OOCSI_server.jar from the GitHub Releases.

Command Line Options

Run with default settings (port 4444):

java -jar OOCSI_server.jar

Run on a custom port:

java -jar OOCSI_server.jar -port 4545

Enable file logging:

java -jar OOCSI_server.jar -logging

Set maximum concurrent client connections (e.g. 100):

java -jar OOCSI_server.jar -clients 100

Combine options:

java -jar OOCSI_server.jar -port 4444 -clients 150 -logging

---

Server Configuration (oocsi-web)

When deploying oocsi-web from source or configuring container environment settings, the server behavior can be fine-tuned via conf/application.conf or JVM system properties:

• Maximum Clients: oocsi.clients = 1000 sets the total concurrent client capacity.
• Rate Limiting:
  • oocsi.ratelimit.enabled = true enables token bucket rate limiting on HTTP endpoints.
  • oocsi.ratelimit.capacity = 300 defines the maximum burst capacity per IP address.
  • oocsi.ratelimit.refillTokens = 300 and oocsi.ratelimit.refillDurationSeconds = 60 configure token refill rates.
• HTTP Port: Configured at launch using -Dhttp.port=8080.

---

Server Monitoring & Introspection

The oocsi-web distribution includes endpoints to monitor health and inspect network traffic:

• /metrics: Outputs real-time JSON metrics including total connected client count, active channel count, JVM memory allocation, and rate-limiting status.
• /network.json: Provides an instant graph snapshot of active channels and connected client nodes for custom visualizations.