09 Deployment Strategy

UDIP – Deployment & Bundling Strategy

This document explains how UDIP is packaged, deployed, and configured for easy installation and operation.

Design Goals

Single-command installation: Users should install and run UDIP with minimal steps
No external dependencies: UDIP should run without requiring Docker, Kubernetes, or cloud services (though it can use them)
Localhost-only by default: UDIP should not expose services to the public internet unless explicitly configured
Portable: UDIP should run on Windows, macOS, and Linux
Upgradable: Users should be able to upgrade UDIP without losing data or configuration

Bundling Strategy

UDIP is distributed as a single executable bundle that contains:

Node.js orchestration core: Backend services (process manager, API gateway, logs, deployment engine, terminal server)
Python AI subsystem: Packaged as a standalone binary (using PyInstaller or similar)
Frontend (React/Vite): Pre-built static assets served by the Node.js backend
Embedded database: SQLite (no external database required)

Bundling Tools

Node.js backend: Packaged using pkg or nexe
Python AI subsystem: Packaged using PyInstaller or Nuitka
Frontend: Pre-built using Vite (npm run build)

Single Binary vs. Multi-Binary

Option 1: Single Binary (Recommended for simplicity) - All components bundled into one executable - User runs: udip start - Orchestration core spawns AI subsystem as a child process

Option 2: Multi-Binary (Recommended for flexibility) - Separate binaries for orchestration core and AI subsystem - User runs: udip start (orchestration core) → automatically starts AI subsystem - Allows users to disable/replace AI subsystem if desired

Chosen Approach: Multi-binary with auto-start - udip (main orchestration core) - udip-ai (AI subsystem, started automatically by udip)

Installation Methods

1. Pre-Built Binary (Recommended)

Users download a platform-specific binary:

# Download
curl -fsSL https://udip.dev/install.sh | sh

# Or direct download
wget https://github.com/udip/udip/releases/download/v1.0.0/udip-linux-x64

# Make executable
chmod +x udip-linux-x64

# Run
./udip-linux-x64 start

Advantages: - No dependencies (Node.js, Python not required on host) - Single download, works immediately - Easy to distribute

Disadvantages: - Larger binary size (includes runtime)

2. NPM Package (For Node.js Users)

npm install -g udip

# Run
udip start

Advantages: - Familiar to Node.js developers - Easy to update (npm update -g udip)

Disadvantages: - Requires Node.js and Python to be installed - More complex dependency management

3. Docker (Optional)

docker pull udip/udip:latest
docker run -p 3000:3000 -v /path/to/projects:/workspace udip/udip:latest

Advantages: - Isolated environment - Easy to deploy on servers

Disadvantages: - Requires Docker - Adds overhead

4. Source Installation (For Developers)

git clone https://github.com/udip/udip.git
cd udip
npm install
npm run build
npm start

Advantages: - Full control over customization

Disadvantages: - Requires manual setup

How UDIP Runs as a Single Bundled System

Architecture at Runtime

┌─────────────────────────────────────────────────────────────┐
│                     UDIP PLATFORM                            │
└─────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────┐
│                  Main Process (udip)                       │
│                                                            │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Node.js Orchestration Core                        │  │
│  │                                                     │  │
│  │  - Process Manager                                 │  │
│  │  - API Gateway (Express/Fastify)                   │  │
│  │  - WebSocket Server (Socket.io)                    │  │
│  │  - Terminal Server (node-pty)                      │  │
│  │  - Log Aggregation Service                         │  │
│  │  - Deployment Engine                               │  │
│  │  - Event Bus                                       │  │
│  │  - Static File Server (serves frontend)            │  │
│  └────────────────────────────────────────────────────┘  │
│                                                            │
│  Spawns Child Process:                                    │
│  ┌────────────────────────────────────────────────────┐  │
│  │  AI Subsystem (udip-ai)                            │  │
│  │                                                     │  │
│  │  - FastAPI Server                                  │  │
│  │  - Context Manager                                 │  │
│  │  - LLM Interface                                   │  │
│  │  - Action Executor                                 │  │
│  └────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

Startup Sequence

User runs: udip start
Orchestration core starts:
Reads config file (~/.udip/config.yaml)
Initializes SQLite database
Starts API Gateway (Express/Fastify)
Starts WebSocket server
Starts terminal server
AI subsystem starts (spawned as child process):
Binds to localhost-only port (e.g., http://127.0.0.1:8001)
Registers with orchestration core
Frontend served:
Static files served from http://localhost:3000
User opens browser to http://localhost:3000

Internal vs External Ports

Internal Ports (Localhost-Only)

By default, UDIP binds services to 127.0.0.1 (localhost) to prevent external access.

Service	Default Port	Accessible From
Frontend + API	`3000`	Localhost only
WebSocket	`3000` (same as API)	Localhost only
AI Subsystem	`8001`	Localhost only (internal communication)

External Access (Optional)

Users can configure UDIP to bind to 0.0.0.0 (all interfaces) for remote access:

# ~/.udip/config.yaml
server:
  host: 0.0.0.0  # Expose to network (use with caution)
  port: 3000

Security Recommendations: - If exposing externally, use VPN (Tailscale, WireGuard) or SSH tunnel - Enable authentication (JWT tokens, OAuth) - Use HTTPS (reverse proxy with Nginx + Let's Encrypt)

Optional Use of Unix Sockets (Linux/macOS)

For local-only communication, UDIP can use Unix sockets instead of TCP ports:

# ~/.udip/config.yaml
ai:
  socket: /tmp/udip-ai.sock  # Unix socket (faster, more secure)

Advantages: - No TCP overhead - Cannot be accessed externally (even with firewall misconfiguration)

Disadvantages: - Not supported on Windows (requires TCP)

Docker vs Non-Docker Installation

Non-Docker (Default)

UDIP runs as a native process
Directly accesses host file system
Easier to manage host services (Node.js apps, databases, etc.)

Docker (Optional)

UDIP runs in a container
Requires volume mounts to access host file system
Useful for isolated environments or multi-user deployments

Docker Compose Example:

version: '3.8'
services:
  udip:
    image: udip/udip:latest
    ports:
      - "3000:3000"
    volumes:
      - /path/to/projects:/workspace
      - udip-data:/data
    environment:
      - UDIP_HOST=0.0.0.0
      - UDIP_PORT=3000

volumes:
  udip-data:

Configuration File

UDIP uses a YAML configuration file stored at ~/.udip/config.yaml (or /etc/udip/config.yaml for system-wide installs).

Example Config:

# UDIP Configuration

server:
  host: 127.0.0.1  # Bind to localhost (use 0.0.0.0 for external access)
  port: 3000

ai:
  enabled: true
  provider: openai  # Options: openai, anthropic, local
  api_key: sk-...  # API key for cloud LLMs (optional if using local)
  model: gpt-4
  local_model_path: /path/to/local/model  # For local LLMs

database:
  path: ~/.udip/data/udip.db  # SQLite database

logs:
  level: info  # Options: debug, info, warn, error
  retention_days: 30  # Delete logs older than 30 days

projects:
  workspace: ~/projects  # Default project directory

plugins:
  enabled: true
  directory: ~/.udip/plugins

Data Storage Locations

Data Type	Default Location	Description
Config	`~/.udip/config.yaml`	User configuration
Database	`~/.udip/data/udip.db`	SQLite database (process state, logs, deployment history)
Logs	`~/.udip/data/logs/`	Archived log files
Plugins	`~/.udip/plugins/`	User-installed plugins
AI Context	`~/.udip/data/ai-context/`	Vector embeddings, cached context

Upgrading UDIP

Binary Installation

# Download new version
curl -fsSL https://udip.dev/install.sh | sh

# Stop old version
udip stop

# Start new version
udip start

Data Preservation: - Config and database are preserved (stored in ~/.udip/) - Migrations run automatically on first start of new version

NPM Installation

npm update -g udip
udip restart

Uninstalling UDIP

# Stop UDIP
udip stop

# Remove binary
rm /usr/local/bin/udip

# Remove data (optional)
rm -rf ~/.udip

Multi-User Deployments (Future)

For teams, UDIP can be deployed on a central server:

Server setup:
Install UDIP on a server (VPS, on-premise)
Configure host: 0.0.0.0 for network access
Enable authentication (JWT, OAuth)
Users access via browser:
https://udip.example.com
Each user logs in with credentials
RBAC controls access to projects and operations

Platform-Specific Considerations

Windows

Use TCP ports (Unix sockets not supported)
Install as a Windows Service (using node-windows or NSSM)

macOS

Code signing required for distribution (avoid Gatekeeper warnings)
Optional: Use launchd for auto-start on boot

Linux

Use systemd for auto-start on boot
Example systemd service file:

[Unit]
Description=UDIP Developer Platform
After=network.target

[Service]
Type=simple
User=youruser
ExecStart=/usr/local/bin/udip start
Restart=on-failure

[Install]
WantedBy=multi-user.target

Conclusion

UDIP is designed for easy installation and operation:

Single binary or NPM package: No complex setup
Localhost-only by default: Secure out of the box
Config-driven: Flexible without being overwhelming
Portable: Works on Windows, macOS, and Linux
Upgradable: Seamless version updates without data loss

Users can install UDIP in under 5 minutes and start managing projects immediately.

Document Version: 1.0
Last Updated: January 2026