nexu-io-open-design/docs/install-guide.md

One-Click Install Guide

Parent: spec.md · Siblings: self-hosting.md · network-security.md

Deploy Open Design on Linux or macOS with a single command. The installer wraps the existing Docker Compose stack — no build step required.

Quick reference

Clone the repository and run the installer:

git clone https://github.com/nexu-io/open-design.git
cd open-design
bash deploy/scripts/install.sh

Prerequisites

The only requirement is Docker with the Compose plugin.

Platform	Minimum version	Install
Docker Engine	24.0	docs.docker.com/engine/install
Docker Compose plugin	2.20	Bundled with Docker Desktop; apt install docker-compose-plugin on Linux
Docker Desktop (macOS/Windows)	4.25	docker.com/products/docker-desktop

The installer checks for Docker and offers to install it automatically on Ubuntu/Debian, Fedora, and macOS (via Homebrew). Use --skip-docker-install to skip this step.

MCP note: Docker/Compose installs run the daemon inside the container. The MCP client snippets shown in Settings are stdio/local-path based and require a local/source install for now. Container-friendly MCP transport will be added in a follow-up.

Interactive install walkthrough

Running the installer without flags launches an interactive wizard:

  ╔══════════════════════════════════════╗
  ║         O P E N   D E S I G N        ║
  ║          One-Click Installer         ║
  ╚══════════════════════════════════════╝

[open-design] OS: Linux ubuntu 24.04 (x86_64)
[open-design] Docker: Docker version 26.1.3, build b72abbb
[open-design] Compose: Docker Compose version v2.27.1

Docker image [ghcr.io/nexu-io/od:latest]:
Port [7456]:
Allowed origins (CORS, comma-separated, or empty) []:
Memory limit [384m]:

[open-design] Pulling image: ghcr.io/nexu-io/od:latest
[open-design] Starting Open Design...
[open-design] Waiting for health check (up to 60s)...
[open-design] Daemon is healthy (200 OK)

What each prompt does

Prompt	Default	Notes
Docker image	ghcr.io/nexu-io/od:latest	Use :latest for the newest stable image, :<version> for a pinned release, or @sha256:<digest> for reproducibility
Port	7456	The port the daemon listens on. Must not be in use.
Allowed origins	(empty)	CORS origins for reverse-proxy setups. See network-security.md. Leave empty for localhost-only use.
Memory limit	384m	Container memory cap. Raise for large concurrent agent runs.

After you confirm, the installer:

1. Writes a deploy/.env file (backs up any existing one).
2. Runs docker compose pull to fetch the image.
3. Runs docker compose up -d --no-build to start the container.
4. Polls /api/health for up to 60 seconds to confirm the daemon is ready.
5. On Linux: installs a systemd --user unit so the service starts on login.

Non-interactive install

For CI, headless servers, and automated provisioning:

bash deploy/scripts/install.sh --non-interactive [--port 7456] [--image <ref>] [--no-systemd]

All prompts are skipped and defaults are used. If Docker is not installed, the script exits with an error instead of offering to install it.

All flags

install.sh

Flag	Description
--non-interactive	Skip all prompts
--port <n>	Host port (default: 7456)
--image <ref>	Docker image reference
--skip-docker-install	Never attempt to install Docker
--no-systemd	Skip systemd unit creation

Service management

Linux (systemd)

The installer creates a systemd --user unit that wraps Docker Compose. No sudo required.

# Check status
systemctl --user status open-design

# Start / stop / restart
systemctl --user start open-design
systemctl --user stop open-design
systemctl --user restart open-design

# View logs
journalctl --user -u open-design -f

# Disable auto-start
systemctl --user disable open-design

# Re-enable auto-start
systemctl --user enable open-design

To skip systemd unit creation, pass --no-systemd to the installer.

macOS (Docker Desktop)

Docker Desktop manages the container lifecycle. Use Docker Desktop's dashboard to start, stop, or restart the open-design container, or use the CLI:

# Using docker compose directly
docker compose -f deploy/docker-compose.yml start
docker compose -f deploy/docker-compose.yml stop
docker compose -f deploy/docker-compose.yml logs -f

Update

Pull the latest image and restart with a single command:

bash deploy/scripts/update.sh

To update to a specific image:

bash deploy/scripts/update.sh --image=ghcr.io/nexu-io/od@sha256:<digest>

The update script:

1. Pulls the new image.
2. Restarts the container with docker compose up -d --no-build.
3. Waits for /api/health to return 200.
4. Prunes dangling old images.

Uninstall

# Remove containers and persistent daemon storage
bash deploy/scripts/uninstall.sh

# Remove containers but keep persistent daemon storage
bash deploy/scripts/uninstall.sh --keep-data

The uninstaller:

1. Stops and removes containers (docker compose down), then removes persistent daemon storage separately.
2. On Linux: disables and removes the systemd unit.
3. Removes deploy/.env.

Data: Before documenting, changing, deleting, or preserving persistent daemon storage, you MUST read root AGENTS.md → Daemon data directory contract. This guide MUST NOT restate that contract or define storage paths.

Configuration

All settings live in deploy/.env. Edit it directly or re-run the installer to regenerate it.

Variable	Default	Description
OPEN_DESIGN_IMAGE	ghcr.io/nexu-io/od:latest	Full image reference
OPEN_DESIGN_PORT	7456	Host-side port (bound to 127.0.0.1)
OPEN_DESIGN_ALLOWED_ORIGINS	(empty)	CORS origins for reverse-proxy setups
OPEN_DESIGN_MEM_LIMIT	384m	Container memory cap
NODE_OPTIONS	--max-old-space-size=192	Node.js heap cap inside the container

The container always binds 127.0.0.1:<port>:7456 — the daemon is never directly exposed to the network. To allow remote access, put an authenticated reverse proxy in front. See network-security.md.

Troubleshooting

Problem	Likely cause	Fix
Docker is not installed	Docker not on PATH	Install Docker Desktop or Docker Engine
Docker daemon is not running	Docker Desktop not started	Open Docker Desktop or run sudo systemctl start docker
Port 7456 is already in use	Another service on that port	Re-run with --port 8080
Health check times out	Image pull slow or daemon slow to start	Wait and check docker compose -f deploy/docker-compose.yml logs
Permission denied on install.sh	Script not executable	Run chmod +x deploy/scripts/install.sh
systemd unit not created	systemd not found	Omit --no-systemd if systemd is available, or manage via Docker CLI
.env has wrong port after re-install	Old backup not restored	Edit deploy/.env directly or delete it and re-run
Container exits immediately	Image incompatibility	Check docker compose -f deploy/docker-compose.yml logs for errors
Authorization: Bearer <OD_API_TOKEN> required on macOS	Docker Desktop bridge networking	Enable host networking — see Docker Desktop on macOS

References

• Docker Compose config: deploy/docker-compose.yml
• Environment template: deploy/.env.example
• Self-hosting topologies (PM2, systemd native): docs/self-hosting.md
• Network security and remote access: docs/network-security.md