docs: add installation guides, config examples, and systemd service files
This commit is contained in:
Rob Colbert
parent
07a760c7b5
commit
2757e55e2c
75
docs/install/README.md
Normal file
75
docs/install/README.md
Normal file
@ -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
|
||||
143
docs/install/config-examples/gadget-code.yaml
Normal file
143
docs/install/config-examples/gadget-code.yaml
Normal file
@ -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 <noreply@example.com>"
|
||||
user: "smtp-user"
|
||||
password: "${SMTP_PASSWORD}"
|
||||
pool:
|
||||
enabled: true
|
||||
maxConnections: 5
|
||||
maxMessages: 100
|
||||
contact:
|
||||
to: "Support <support@example.com>"
|
||||
|
||||
# ── 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"
|
||||
44
docs/install/config-examples/gadget-drone.yaml
Normal file
44
docs/install/config-examples/gadget-drone.yaml
Normal file
@ -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
|
||||
49
docs/install/systemd/gadget-code-web.service
Normal file
49
docs/install/systemd/gadget-code-web.service
Normal file
@ -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
|
||||
44
docs/install/systemd/gadget-drone.service
Normal file
44
docs/install/systemd/gadget-drone.service
Normal file
@ -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
|
||||
53
docs/install/systemd/gadget-drone@.service
Normal file
53
docs/install/systemd/gadget-drone@.service
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user