From 2757e55e2c166d2f078851aa1675fd12fe93d9ec Mon Sep 17 00:00:00 2001 From: Rob Colbert Date: Mon, 11 May 2026 13:49:50 -0400 Subject: [PATCH] docs: add installation guides, config examples, and systemd service files --- docs/install/README.md | 75 +++++++++ docs/install/config-examples/gadget-code.yaml | 143 ++++++++++++++++++ .../install/config-examples/gadget-drone.yaml | 44 ++++++ docs/install/systemd/gadget-code-web.service | 49 ++++++ docs/install/systemd/gadget-drone.service | 44 ++++++ docs/install/systemd/gadget-drone@.service | 53 +++++++ 6 files changed, 408 insertions(+) create mode 100644 docs/install/README.md create mode 100644 docs/install/config-examples/gadget-code.yaml create mode 100644 docs/install/config-examples/gadget-drone.yaml create mode 100644 docs/install/systemd/gadget-code-web.service create mode 100644 docs/install/systemd/gadget-drone.service create mode 100644 docs/install/systemd/gadget-drone@.service diff --git a/docs/install/README.md b/docs/install/README.md new file mode 100644 index 0000000..ad2a47b --- /dev/null +++ b/docs/install/README.md @@ -0,0 +1,75 @@ +# Gadget Code — Installation & Setup + +Gadget Code is a self-hosted **Agentic Engineering Platform (AEP)** — an IDE that drives autonomous AI agents to perform software engineering work on your behalf, running entirely in your own environment. + +## Architecture + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Gadget Code Deployment │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Browser IDE │─────▶│ gadget-code │─────▶│ gadget-drone │ │ +│ │ (React 19) │◀─────│ (Express 5) │◀─────│ (Worker) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ │ │ │ +│ ├ Socket.IO ├ MongoDB ├ Files │ +│ └ JWT Auth ├ Redis Sessions └ Git │ +│ ├ HTTPS/SSL │ +│ ├ Qdrant (semantic search) │ +│ └ │ +│ Infrastructure: │ +│ - Node.js 22+ │ +│ - pnpm 10+ │ +│ - MongoDB │ +│ - Redis │ +│ - SSL Certificates │ +│ - AI Inference (Ollama / OpenAI / Gab AI / etc.) │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Components + +| Component | Role | Runs On | +|---|---|---| +| **Browser IDE** | React 19 web application — project management, chat sessions, file editing, drone monitoring | User's browser | +| **gadget-code:web** | Express 5 API server — REST API, Socket.IO hub, session management, AI provider routing | Server (or localhost) | +| **gadget-drone** | Worker process — runs the Agentic Workflow Loop (AWL), executes tool calls, manages workspaces | Developer workstation (or server) | +| **MongoDB** | Primary database — users, projects, chat sessions, AI providers, drone registrations | Server (or localhost) | +| **Redis** | Session store — Express session persistence, caching | Server (or localhost) | +| **Qdrant** | Vector database — semantic search over chat history and project knowledge (arriving soon) | Server (or localhost) | + +## Which Guide Is For You? + +| I am... | I need to... | Guide | +|---|---|---| +| An **IT administrator** | Deploy and manage the Gadget Code platform for my organization | [IT Admin Guide](./it-admin-guide.md) | +| A **developer / engineer / manager** | Run `gadget-drone` on my workstation to connect to an existing platform | [Drone Operator Guide](./drone-operator-guide.md) | +| A **solo developer / solopreneur** | Run everything on my own machine — platform + drone + database | [Solo Developer Guide](./solo-developer-guide.md) | + +## Common Prerequisites + +All guides require these tools installed on the host: + +- **Node.js 22+** — [nodejs.org](https://nodejs.org/) +- **pnpm 10+** — [pnpm.io](https://pnpm.io/) + +Verify your installation: + +```bash +node --version # v22.x.x or later +pnpm --version # 10.x.x or later +``` + +## Configuration Reference + +All guides share the same YAML configuration system. See the full reference: + +- **[Configuration Guide](../configuration.md)** — complete YAML schema, environment variable substitution, file locations +- **[Example configs](./config-examples/)** — drop-in templates for `gadget-code.yaml` and `gadget-drone.yaml` + +## Support + +- **[Documentation](../)** — architecture, protocols, workspace management +- **[Financial Support & Hosting](../support.md)** — managed hosting, consulting, donations diff --git a/docs/install/config-examples/gadget-code.yaml b/docs/install/config-examples/gadget-code.yaml new file mode 100644 index 0000000..c00c9f8 --- /dev/null +++ b/docs/install/config-examples/gadget-code.yaml @@ -0,0 +1,143 @@ +# ============================================================================ +# Gadget Code Platform — Example Configuration +# ============================================================================ +# Install this file to one of: +# ~/.config/gadget/gadget-code.yaml (user-level, takes precedence) +# /etc/gadget/gadget-code.yaml (system-level) +# +# Secrets MUST be stored in environment variables, NOT in this file. +# Use ${VAR_NAME} syntax to reference environment variables. +# ============================================================================ + +# Timezone for the server (used by dayjs and logging) +timezone: "America/New_York" + +# ── Site Information ──────────────────────────────────────────────────────── +# These values are exposed to the frontend and used in page titles, emails, etc. +site: + company: "Your Company" + companyShort: "YourCo" + name: "Gadget Code" + shortName: "Gadget" + slogan: "Self-hosted Agentic Engineering Platform" + description: "A self-hosted agentic development environment." + domain: "code.example.com" # Primary domain (no port) + domainKey: "code" # Short key used in cookie names, etc. + host: "code.example.com:3443" # Full host:port for URL generation + +# ── Authentication (REQUIRED) ─────────────────────────────────────────────── +# These values are MANDATORY. The server will refuse to start without them. +# Store them in environment variables — never commit secrets to this file. +auth: + jwtSecret: "${DTP_JWT_SECRET}" # JSON Web Token signing key + passwordSalt: "${DTP_USER_PASSWORD_SALT}" # Per-instance password hashing salt + +# ── Session Configuration (REQUIRED) ───────────────────────────────────────── +# Express session stored in Redis via connect-redis. +session: + secret: "${DTP_SESSION_SECRET}" # Session signing key + trustProxy: true # Set true if behind a reverse proxy + cookie: + secure: true # Set true for HTTPS (required for SameSite=strict) + sameSite: "strict" # strict | lax | none + +# ── Google Custom Search Engine (REQUIRED) ────────────────────────────────── +# Used by the drone's search_google tool for web search capabilities. +google: + cse: + apiKey: "${GOOGLE_CSE_API_KEY}" # Google API key with CSE enabled + engineId: "${GOOGLE_CSE_ENGINE_ID}" # Your custom search engine ID + +# ── MongoDB Configuration ─────────────────────────────────────────────────── +# The platform stores projects, chat sessions, users, providers, and drones here. +mongodb: + host: "localhost:27017" # MongoDB host:port + database: "gadget-code" # Database name + +# ── Redis Configuration ───────────────────────────────────────────────────── +# Used for Express session storage (connect-redis) and caching. +redis: + host: "localhost" + port: 6379 + password: "${REDIS_PASSWORD}" # Omit if Redis has no auth + keyPrefix: "gcode:" # Prefix for all keys in this instance + lazyConnect: false # Connect immediately on startup + +# ── HTTPS Configuration ───────────────────────────────────────────────────── +# The platform server runs HTTPS directly. Place your cert and key on disk. +https: + enabled: true + address: "0.0.0.0" # Bind address (0.0.0.0 for all interfaces) + port: 3443 # Default HTTPS port + backlog: 128 # TCP backlog + keyFile: "/etc/ssl/gadget-code/key.pem" # Private key + crtFile: "/etc/ssl/gadget-code/cert.pem" # Certificate (full chain) + uploadPath: "/tmp/gadget-code" # Temp directory for file uploads + +# ── Socket.IO Configuration ───────────────────────────────────────────────── +# Real-time communication between IDE, platform, and drones. +socket: + maxHttpBufferSize: 10485760 # 10 MB — max message size + +# ── Logging Configuration ─────────────────────────────────────────────────── +# Logs follow XDG Base Directory spec by default. +logging: + console: + enabled: true # Print to stdout/stderr + file: + enabled: true + path: "~/.local/state/gadget-code/logs" # Supports ~ expansion + name: "gadget-code" + maxWritesPerFile: 10000 # Rotate after this many writes + maxFiles: 10 # Keep this many rotated files + https: + enabled: true # HTTP access log (morgan format) + name: "gadget-code.https.log" + path: "~/.local/state/gadget-code/logs" + format: "combined" # morgan log format name + levels: + debug: true # Set false in production for less noise + info: true + warn: true + +# ── Email Configuration (OPTIONAL) ────────────────────────────────────────── +# Enable for contact form submissions, password resets, and notifications. +email: + enabled: false + smtp: + host: "smtp.example.com" + port: 587 + secure: false # true for port 465 + from: "Gadget Code " + user: "smtp-user" + password: "${SMTP_PASSWORD}" + pool: + enabled: true + maxConnections: 5 + maxMessages: 100 + contact: + to: "Support " + +# ── MinIO / S3 Configuration (OPTIONAL) ───────────────────────────────────── +# Object storage for uploaded files, images, videos, and audio. +minio: + endpoint: "localhost" + port: 9000 + useSsl: false + accessKey: "minio-access-key" + secretKey: "${MINIO_SECRET_KEY}" + buckets: + uploads: "gadget-uploads" + images: "gadget-images" + videos: "gadget-videos" + audios: "gadget-audios" + +# ── Qdrant Vector Database (COMING SOON) ──────────────────────────────────── +# Used for semantic search over chat history and conversation context. +# Enable when the Qdrant integration is released. +# +# qdrant: +# host: "localhost" +# port: 6333 +# apiKey: "${QDRANT_API_KEY}" +# collection: "gadget-chat-embeddings" diff --git a/docs/install/config-examples/gadget-drone.yaml b/docs/install/config-examples/gadget-drone.yaml new file mode 100644 index 0000000..bbb2b54 --- /dev/null +++ b/docs/install/config-examples/gadget-drone.yaml @@ -0,0 +1,44 @@ +# ============================================================================ +# Gadget Drone Worker — Example Configuration +# ============================================================================ +# Install this file to one of: +# ~/.config/gadget/gadget-drone.yaml (user-level, takes precedence) +# /etc/gadget/gadget-drone.yaml (system-level) +# +# Secrets MUST be stored in environment variables, NOT in this file. +# Use ${VAR_NAME} syntax to reference environment variables. +# ============================================================================ + +# Timezone for the drone worker (used by dayjs and logging) +timezone: "America/New_York" + +# ── Platform Connection (REQUIRED) ────────────────────────────────────────── +# The drone connects to the Gadget Code platform via Socket.IO over HTTPS. +# These values are MANDATORY. The drone will refuse to start without them. +platform: + baseUrl: "https://code.example.com:3443" # Platform URL (HTTPS) + gadgetKey: "${GADGET_PLATFORM_KEY}" # API key for authentication + +# ── Google Custom Search Engine (OPTIONAL) ─────────────────────────────────── +# If provided, the drone's search_google tool will use these credentials. +# If omitted, web search capabilities will be unavailable. +google: + cse: + apiKey: "${GOOGLE_CSE_API_KEY}" # Google API key with CSE enabled + engineId: "${GOOGLE_CSE_ENGINE_ID}" # Your custom search engine ID + +# ── Logging Configuration ─────────────────────────────────────────────────── +# Logs follow XDG Base Directory spec by default. +logging: + console: + enabled: true # Print to stdout/stderr + file: + enabled: true + path: "~/.local/state/gadget-drone/logs" # Supports ~ expansion + name: "gadget-drone" + maxWritesPerFile: 10000 # Rotate after this many writes + maxFiles: 10 # Keep this many rotated files + levels: + debug: true # Set false in production for less noise + info: true + warn: true diff --git a/docs/install/systemd/gadget-code-web.service b/docs/install/systemd/gadget-code-web.service new file mode 100644 index 0000000..d9efeef --- /dev/null +++ b/docs/install/systemd/gadget-code-web.service @@ -0,0 +1,49 @@ +# Gadget Code Platform — Systemd Service Unit +# ============================================================================ +# Install to: /etc/systemd/system/gadget-code-web.service +# +# Then: +# sudo systemctl daemon-reload +# sudo systemctl enable gadget-code-web +# sudo systemctl start gadget-code-web +# +# View logs: +# journalctl -u gadget-code-web -f +# ============================================================================ + +[Unit] +Description=Gadget Code — Agentic Engineering Platform +Documentation=https://github.com/dtp-technologies/gadget-code +After=network.target mongod.service redis.service +Wants=mongod.service redis.service + +[Service] +Type=simple +User=gadget +Group=gadget + +# Environment variables for secrets (see docs/install/env-examples/) +EnvironmentFile=/etc/gadget/gadget-code-web.env + +# Binary path (adjust if installed globally via npm) +ExecStart=/usr/local/bin/gadget-code-web +Restart=on-failure +RestartSec=5 + +# Security hardening +NoNewPrivileges=true +ProtectSystem=strict +ProtectHome=read-only +ReadWritePaths=/tmp/gadget-code +PrivateTmp=true + +# Resource limits +LimitNOFILE=65536 + +# Logging +StandardOutput=journal +StandardError=journal +SyslogIdentifier=gadget-code-web + +[Install] +WantedBy=multi-user.target diff --git a/docs/install/systemd/gadget-drone.service b/docs/install/systemd/gadget-drone.service new file mode 100644 index 0000000..4424c1b --- /dev/null +++ b/docs/install/systemd/gadget-drone.service @@ -0,0 +1,44 @@ +# Gadget Drone Worker — Systemd User Service Unit +# ============================================================================ +# Install as a USER service for solo developers running drones on their +# own workstations. +# +# Install to: ~/.config/systemd/user/gadget-drone.service +# +# Then: +# systemctl --user daemon-reload +# systemctl --user enable gadget-drone +# systemctl --user start gadget-drone +# +# Start at login: +# loginctl enable-linger $USER +# +# View logs: +# journalctl --user -u gadget-drone -f +# ============================================================================ + +[Unit] +Description=Gadget Drone Worker +Documentation=https://github.com/dtp-technologies/gadget-code +After=network.target + +[Service] +Type=simple + +# The drone runs from the user's chosen workspace directory. +# Update this path to match your setup. +WorkingDirectory=%h/gadget-workspace +ExecStart=%h/.local/bin/gadget-drone +Restart=on-failure +RestartSec=5 + +# Resource limits +LimitNOFILE=65536 + +# Logging +StandardOutput=journal +StandardError=journal +SyslogIdentifier=gadget-drone + +[Install] +WantedBy=default.target diff --git a/docs/install/systemd/gadget-drone@.service b/docs/install/systemd/gadget-drone@.service new file mode 100644 index 0000000..81123b0 --- /dev/null +++ b/docs/install/systemd/gadget-drone@.service @@ -0,0 +1,53 @@ +# Gadget Drone Worker — Systemd Template Service Unit +# ============================================================================ +# This is a TEMPLATE unit. Create instances per workspace: +# /etc/systemd/system/gadget-drone@my-workspace.service +# +# The %I placeholder is replaced with the instance name. +# The drone's working directory is set to /home/gadget/drones/%I +# +# Enable and start: +# sudo systemctl enable gadget-drone@my-workspace +# sudo systemctl start gadget-drone@my-workspace +# +# View logs: +# journalctl -u gadget-drone@my-workspace -f +# ============================================================================ + +[Unit] +Description=Gadget Drone Worker — %I +Documentation=https://github.com/dtp-technologies/gadget-code +After=network.target gadget-code-web.service +Wants=gadget-code-web.service + +[Service] +Type=simple +User=gadget +Group=gadget + +# Environment variables for secrets +EnvironmentFile=/etc/gadget/gadget-drone.env + +# Each drone instance runs in its own workspace directory +WorkingDirectory=/home/gadget/drones/%I +ExecStart=/usr/local/bin/gadget-drone +Restart=on-failure +RestartSec=5 + +# Security hardening +NoNewPrivileges=true +ProtectSystem=strict +ProtectHome=read-only +ReadWritePaths=/home/gadget/drones/%I +PrivateTmp=true + +# Resource limits +LimitNOFILE=65536 + +# Logging +StandardOutput=journal +StandardError=journal +SyslogIdentifier=gadget-drone@%I + +[Install] +WantedBy=multi-user.target