wehub-resource-sync
070959e133
landing-page-staging / Deploy landing page to staging (push) Has been skipped
landing-page-ci / Validate landing page (push) Failing after 4s
visual-baseline / Capture visual baselines (push) Has been cancelled
bake-plugin-previews / Bake plugin previews (push) Has been cancelled
204 lines
8.1 KiB
Markdown
204 lines
8.1 KiB
Markdown
# One-Click Install Guide
|
|
|
|
**Parent:** [`spec.md`](spec.md) · **Siblings:** [`self-hosting.md`](self-hosting.md) · [`network-security.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:
|
|
|
|
```bash
|
|
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](https://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](https://www.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`](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
|
|
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.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
bash deploy/scripts/update.sh
|
|
```
|
|
|
|
To update to a specific image:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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`](../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`](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](../deploy/README.md#docker-desktop-on-macos) |
|
|
|
|
## References
|
|
|
|
- Docker Compose config: [`deploy/docker-compose.yml`](../deploy/docker-compose.yml)
|
|
- Environment template: [`deploy/.env.example`](../deploy/.env.example)
|
|
- Self-hosting topologies (PM2, systemd native): [`docs/self-hosting.md`](self-hosting.md)
|
|
- Network security and remote access: [`docs/network-security.md`](network-security.md)
|