docs: update all documentation for unified binary architecture
📚 **Complete Documentation Overhaul** **Updated Files:** ✅ **README.md** - Updated commands, configuration, and workflow ✅ **COMMANDS.md** - New comprehensive command reference ✅ **INTEGRATION-SUMMARY.md** - Updated architecture overview ✅ **insertr-server/README.md** - Redirect to unified binary docs **Key Documentation Changes:** 🔧 **Unified Binary Commands:** - Updated all examples to use `./insertr enhance` and `./insertr serve` - Removed references to separate CLI/server binaries - Added comprehensive configuration documentation ⚙️ **Configuration Section:** - Added YAML configuration examples (`insertr.yaml`) - Documented environment variables (`INSERTR_*`) - Explained configuration precedence (CLI → env → YAML → defaults) 📖 **Command Reference (COMMANDS.md):** - Complete reference for all commands and flags - Usage patterns for development and production - API endpoint documentation - Error handling and debugging guides - CI/CD integration examples 🏗️ **Architecture Updates:** - Updated development workflow instructions - Fixed CLI → Binary terminology - Updated hot reload and build process documentation **Migration Notes:** - All functionality preserved in unified binary - Simplified development workflow with `just dev` - Single executable for all operations
This commit is contained in:
269
COMMANDS.md
Normal file
269
COMMANDS.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# Insertr Command Reference
|
||||
|
||||
Complete reference for the unified `insertr` binary commands, configuration, and usage patterns.
|
||||
|
||||
## 🔧 Command Overview
|
||||
|
||||
```bash
|
||||
insertr [global-flags] <command> [command-flags] [arguments]
|
||||
```
|
||||
|
||||
## 📚 Global Flags
|
||||
|
||||
Available for all commands:
|
||||
|
||||
| Flag | Environment Variable | Description | Default |
|
||||
|------|---------------------|-------------|---------|
|
||||
| `--config` | N/A | Config file path | `./insertr.yaml` |
|
||||
| `--db` | `INSERTR_DB_PATH` | Database path or connection string | `./insertr.db` |
|
||||
| `--api-url` | `INSERTR_API_URL` | Remote content API URL | `""` |
|
||||
| `--api-key` | `INSERTR_API_KEY` | API authentication key | `""` |
|
||||
| `--site-id` | `INSERTR_SITE_ID` | Site identifier for content | `"demo"` |
|
||||
| `--help` | N/A | Show help information | N/A |
|
||||
| `--version` | N/A | Show version information | N/A |
|
||||
|
||||
## 🔨 enhance Command
|
||||
|
||||
Build-time content injection - processes HTML files and injects database content.
|
||||
|
||||
```bash
|
||||
insertr enhance [input-dir] [flags]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
- `input-dir` - Directory containing HTML files to enhance (required)
|
||||
|
||||
### Flags
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--output`, `-o` | Output directory for enhanced files | `./dist` |
|
||||
| `--mock` | Use mock content for development | `true` |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Basic enhancement with mock data
|
||||
./insertr enhance demo-site/
|
||||
|
||||
# Production build with custom output
|
||||
./insertr enhance src/ --output ./build --mock=false
|
||||
|
||||
# Use remote API for content
|
||||
./insertr enhance src/ --api-url https://cms.example.com --api-key xyz123
|
||||
|
||||
# Use local database
|
||||
./insertr enhance src/ --db ./content.db
|
||||
|
||||
# Custom site ID
|
||||
./insertr enhance src/ --site-id production
|
||||
```
|
||||
|
||||
### Content Sources Priority
|
||||
1. Remote API (if `--api-url` provided)
|
||||
2. Local database (if `--db` points to valid database)
|
||||
3. Mock content (if `--mock=true` or fallback)
|
||||
|
||||
## 🔌 serve Command
|
||||
|
||||
Runtime API server - provides HTTP endpoints for content management.
|
||||
|
||||
```bash
|
||||
insertr serve [flags]
|
||||
```
|
||||
|
||||
### Flags
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--port`, `-p` | HTTP server port | `8080` |
|
||||
| `--dev-mode` | Enable development mode features | `false` |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Development server
|
||||
./insertr serve --dev-mode
|
||||
|
||||
# Production server
|
||||
./insertr serve --port 80
|
||||
|
||||
# Custom database
|
||||
./insertr serve --db ./production.db
|
||||
|
||||
# PostgreSQL database
|
||||
./insertr serve --db "postgresql://user:pass@localhost:5432/insertr"
|
||||
|
||||
# Custom configuration
|
||||
./insertr --config production.yaml serve
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
When running `insertr serve`, these endpoints are available:
|
||||
|
||||
#### Health Check
|
||||
- `GET /health` - Server health status
|
||||
|
||||
#### Content Management
|
||||
- `GET /api/content?site_id={site}` - Get all content for site
|
||||
- `GET /api/content/{id}?site_id={site}` - Get single content item
|
||||
- `GET /api/content/bulk?site_id={site}&ids[]={id1}&ids[]={id2}` - Get multiple items
|
||||
- `POST /api/content` - Create new content
|
||||
- `PUT /api/content/{id}` - Update existing content
|
||||
|
||||
#### Version Control
|
||||
- `GET /api/content/{id}/versions?site_id={site}` - Get content history
|
||||
- `POST /api/content/{id}/rollback` - Rollback to previous version
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### YAML Configuration File
|
||||
|
||||
Default file: `insertr.yaml`
|
||||
|
||||
```yaml
|
||||
# Database configuration
|
||||
database:
|
||||
path: "./insertr.db" # SQLite file or PostgreSQL connection
|
||||
|
||||
# Remote API configuration
|
||||
api:
|
||||
url: "" # Content API URL
|
||||
key: "" # API key
|
||||
|
||||
# Server configuration
|
||||
server:
|
||||
port: 8080 # HTTP port
|
||||
dev_mode: false # Development mode
|
||||
|
||||
# Build configuration
|
||||
build:
|
||||
input: "./src" # Default input directory
|
||||
output: "./dist" # Default output directory
|
||||
|
||||
# Global settings
|
||||
site_id: "demo" # Site identifier
|
||||
mock_content: false # Use mock data
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
All configuration can be set via environment variables:
|
||||
|
||||
```bash
|
||||
export INSERTR_DB_PATH="./content.db"
|
||||
export INSERTR_API_URL="https://api.example.com"
|
||||
export INSERTR_API_KEY="your-api-key"
|
||||
export INSERTR_SITE_ID="production"
|
||||
|
||||
./insertr serve
|
||||
```
|
||||
|
||||
### Configuration Precedence
|
||||
|
||||
1. **CLI flags** (highest priority)
|
||||
2. **Environment variables**
|
||||
3. **YAML configuration file**
|
||||
4. **Built-in defaults** (lowest priority)
|
||||
|
||||
## 📋 Usage Patterns
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# Start full development environment
|
||||
just dev # Uses justfile for convenience
|
||||
|
||||
# Manual development setup
|
||||
./insertr serve --dev-mode --db ./dev.db &
|
||||
npm run demo # Start demo site
|
||||
|
||||
# Hot reload development
|
||||
air # Uses .air.toml configuration
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
```bash
|
||||
# Build static site with content
|
||||
./insertr enhance ./src --output ./dist --api-url https://api.prod.com
|
||||
|
||||
# Start production API server
|
||||
./insertr serve --db "postgresql://user:pass@db:5432/prod"
|
||||
|
||||
# With custom configuration
|
||||
./insertr --config ./production.yaml serve
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Build with Insertr
|
||||
run: |
|
||||
./insertr enhance ./public --output ./dist
|
||||
|
||||
- name: Deploy enhanced site
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
publish_dir: ./dist
|
||||
```
|
||||
|
||||
## 🚨 Error Handling
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Database Connection Errors:**
|
||||
```bash
|
||||
# Check database path
|
||||
./insertr --db ./nonexistent.db serve
|
||||
# Error: failed to initialize database
|
||||
|
||||
# Solution: Verify database path or use --mock for development
|
||||
./insertr serve --dev-mode # Creates ./insertr.db automatically
|
||||
```
|
||||
|
||||
**Port Already in Use:**
|
||||
```bash
|
||||
# Error: listen tcp :8080: bind: address already in use
|
||||
|
||||
# Solution: Use different port
|
||||
./insertr serve --port 3001
|
||||
```
|
||||
|
||||
**Missing Input Directory:**
|
||||
```bash
|
||||
# Error: Input directory does not exist
|
||||
|
||||
# Solution: Verify path exists
|
||||
ls -la ./src
|
||||
./insertr enhance ./src
|
||||
```
|
||||
|
||||
## 🔍 Debugging
|
||||
|
||||
### Verbose Logging
|
||||
|
||||
```bash
|
||||
# Enable development mode for more detailed output
|
||||
./insertr serve --dev-mode
|
||||
|
||||
# Check server health
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
### Configuration Validation
|
||||
|
||||
```bash
|
||||
# Test configuration loading
|
||||
./insertr --config ./test.yaml --help
|
||||
|
||||
# Verify environment variables
|
||||
./insertr serve --help # Shows resolved configuration values
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
For more examples and integration patterns, see:
|
||||
- [Main README](README.md) - Getting started and overview
|
||||
- [Integration Summary](INTEGRATION-SUMMARY.md) - Architecture details
|
||||
- [Development Guide](DEVELOPMENT.md) - Contributing and setup
|
||||
Reference in New Issue
Block a user