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
|
||||
@@ -1,83 +1,125 @@
|
||||
# Server Development Integration Complete ✅
|
||||
# Unified Binary Architecture Complete ✅
|
||||
|
||||
## 🎯 **What Was Accomplished**
|
||||
|
||||
Successfully integrated the **insertr-server** into the development workflow, making **full-stack development the primary experience** while maintaining simplicity.
|
||||
Successfully refactored **insertr-cli** and **insertr-server** into a **unified `insertr` binary**, creating a **simpler, more maintainable architecture** while preserving all functionality.
|
||||
|
||||
## 🚀 **Unified Development Experience**
|
||||
## 🚀 **Unified Binary Experience**
|
||||
|
||||
### **Primary Commands**
|
||||
### **Single Binary Commands**
|
||||
```bash
|
||||
./insertr enhance # 🔨 Build-time content injection
|
||||
./insertr serve # 🔌 Runtime API server
|
||||
./insertr --help # 📖 Complete command reference
|
||||
```
|
||||
|
||||
### **Simplified Development**
|
||||
```bash
|
||||
just dev # 🔥 Full-stack development (PRIMARY)
|
||||
just demo-only # Demo site only (special cases)
|
||||
just server # API server only (development)
|
||||
just serve # API server only (development)
|
||||
just enhance # Build-time enhancement only
|
||||
```
|
||||
|
||||
### **Enhanced Build Pipeline**
|
||||
```bash
|
||||
just build # Now builds: Library + CLI + Server (all-in-one)
|
||||
just build # Now builds: Library + Unified Binary (single executable)
|
||||
npm run build # Same - builds complete stack via scripts/build.js
|
||||
```
|
||||
|
||||
### **Smart Development Features**
|
||||
- **Auto Server Detection**: Library detects development vs production environment
|
||||
- **Helpful Error Messages**: Clear guidance when API server isn't running
|
||||
- **Health Monitoring**: `just server-health` checks API server status
|
||||
- **Enhanced Status**: `just status` shows complete project state including server
|
||||
### **Smart Configuration**
|
||||
- **YAML Configuration**: `insertr.yaml` with smart defaults
|
||||
- **Environment Variables**: `INSERTR_*` prefix for all settings
|
||||
- **CLI Flag Precedence**: Command-line flags override config and env vars
|
||||
- **Database Flexibility**: SQLite for development, PostgreSQL for production
|
||||
|
||||
## 📋 **Technical Integration Points**
|
||||
## 📋 **Technical Architecture Changes**
|
||||
|
||||
### **1. Justfile Enhancements**
|
||||
- Added server commands: `server`, `server-build`, `server-dev`, `server-health`
|
||||
- Added unified development: `dev-full` (orchestrates both demo + API server)
|
||||
- Enhanced status command with server information
|
||||
### **1. Unified Command Structure**
|
||||
- **Single Binary**: `insertr` handles both enhance and serve operations
|
||||
- **Cobra CLI**: Professional command structure with subcommands
|
||||
- **Viper Configuration**: YAML + environment + CLI flag precedence
|
||||
- **Shared Database Layer**: Single source of truth for content models
|
||||
|
||||
### **2. Build Script Integration**
|
||||
- `scripts/build.js` now builds server binary alongside library and CLI
|
||||
- Integrated server build into main `npm run build` workflow
|
||||
- Enhanced completion messages with server usage instructions
|
||||
### **2. Preserved Database Architecture**
|
||||
- **sqlc Code Generation**: Maintained type-safe database operations
|
||||
- **Multi-Database Support**: SQLite (development) and PostgreSQL (production)
|
||||
- **Version Control System**: Complete edit history with rollback capabilities
|
||||
- **Database Abstraction**: Runtime database type detection
|
||||
|
||||
### **3. Smart API Client**
|
||||
- Environment detection (localhost = development server, production = same-origin)
|
||||
- Helpful error messages when server unreachable
|
||||
- Development logging for API configuration
|
||||
- Graceful fallback behavior
|
||||
### **3. Enhanced Build Integration**
|
||||
- `scripts/build.js` builds unified binary with embedded library assets
|
||||
- `justfile` updated for unified binary commands
|
||||
- `Air` configuration for hot reload during development
|
||||
- Single binary deployment for all use cases
|
||||
|
||||
### **4. Enhanced Developer Experience**
|
||||
- `npm run dev:check` validates server components
|
||||
- Clear development workflow guidance
|
||||
- Integrated help messages pointing to `just dev-full`
|
||||
### **4. Configuration Flexibility**
|
||||
- **YAML Config**: `insertr.yaml` for declarative configuration
|
||||
- **Environment Variables**: `INSERTR_*` prefixed for all settings
|
||||
- **CLI Precedence**: Command flags override file and env config
|
||||
- **Smart Defaults**: Zero-configuration development workflow
|
||||
|
||||
## 🔄 **Simplified Development Workflow**
|
||||
|
||||
### **Primary Development (Default)**
|
||||
```bash
|
||||
just dev # or npm run dev
|
||||
# Starts: API server (8080) + Demo site (3000)
|
||||
# Complete CMS experience with real content persistence
|
||||
# Starts: insertr serve (8080) + Demo site (3000)
|
||||
# Complete CMS experience with unified binary
|
||||
```
|
||||
|
||||
### **Component Development (Special Cases)**
|
||||
### **Build-Time Enhancement**
|
||||
```bash
|
||||
just server # API server only
|
||||
just demo-only # Demo site only (no persistence)
|
||||
just enhance # Build-time content injection
|
||||
./insertr enhance demo-site/ --output ./dist --mock
|
||||
./insertr enhance src/ --api https://cms.example.com
|
||||
```
|
||||
|
||||
## ✅ **Verification**
|
||||
### **Production Deployment**
|
||||
```bash
|
||||
./insertr serve --db "postgresql://user:pass@host/db"
|
||||
./insertr --config production.yaml serve
|
||||
```
|
||||
|
||||
All integration points tested and working:
|
||||
- ✅ Server builds via `just build`
|
||||
- ✅ Full-stack development via `just dev`
|
||||
- ✅ API client detects environment correctly
|
||||
- ✅ Enhanced status and check commands work
|
||||
- ✅ Clean, focused development experience
|
||||
## ✅ **Migration Benefits Achieved**
|
||||
|
||||
All functionality preserved with architectural improvements:
|
||||
- ✅ **Single Binary**: No more separate CLI and server binaries
|
||||
- ✅ **Shared Codebase**: Database models, validation, and logic unified
|
||||
- ✅ **Flexible Configuration**: YAML, environment, and CLI flag support
|
||||
- ✅ **Development Workflow**: Hot reload with `air` for unified binary
|
||||
- ✅ **Production Ready**: Same binary handles build-time and runtime
|
||||
- ✅ **Database Architecture**: Preserved sophisticated sqlc multi-DB setup
|
||||
|
||||
## 🏗️ **Architecture Diagram**
|
||||
|
||||
### **Before: Separate Binaries**
|
||||
```
|
||||
insertr-cli/ insertr-server/
|
||||
↓ ↓
|
||||
enhance serve
|
||||
↓ ↓
|
||||
Build-time Runtime
|
||||
```
|
||||
|
||||
### **After: Unified Binary**
|
||||
```
|
||||
insertr
|
||||
↙ ↘
|
||||
enhance serve
|
||||
↓ ↓
|
||||
Build-time Runtime
|
||||
↓ ↓
|
||||
Same Database Layer
|
||||
Same Configuration
|
||||
Same Content Models
|
||||
```
|
||||
|
||||
## 🎉 **Result**
|
||||
|
||||
The development experience is now **simplified and powerful**:
|
||||
- **Full-stack by default** - complete CMS experience from day one
|
||||
- **Clean command structure** - no confusion about workflows
|
||||
- **Professional tooling** - integrated build, status, and health checking
|
||||
- **Ready for production** - complete stack with database persistence
|
||||
The architecture is now **unified and maintainable**:
|
||||
- **Single Source of Truth** - No duplicate database or content logic
|
||||
- **Simplified Deployment** - One binary for all use cases
|
||||
- **Better Developer Experience** - Consistent configuration and commands
|
||||
- **Production Flexibility** - Build-time enhancement OR runtime API OR both
|
||||
|
||||
**Insertr is now a complete, production-ready CMS!** 🚀
|
||||
**Insertr unified binary is production-ready with improved maintainability!** 🚀
|
||||
192
README.md
192
README.md
@@ -54,7 +54,7 @@ Containers with `class="insertr"` automatically make their viable children edita
|
||||
- **Professional Editor**: Modal forms, markdown support, authentication system
|
||||
- **Content Persistence**: SQLite database with REST API, version control
|
||||
- **Version History**: Complete edit history with user attribution and one-click rollback
|
||||
- **CLI Enhancement**: Parse HTML, inject database content, build-time optimization
|
||||
- **Build Enhancement**: Parse HTML, inject database content, build-time optimization
|
||||
- **Smart Detection**: Auto-detects content types (text/markdown/link)
|
||||
- **Deterministic IDs**: Content-based ID generation for consistent developer experience
|
||||
- **Full Integration**: Seamless development workflow with hot reload
|
||||
@@ -98,10 +98,10 @@ just --list # Show all available commands
|
||||
# Development (Full-Stack by Default)
|
||||
just dev # Start full-stack development (recommended)
|
||||
just demo-only # Demo site only (no content persistence)
|
||||
just server # API server only (localhost:8080)
|
||||
just serve # API server only (localhost:8080)
|
||||
|
||||
# Building
|
||||
just build # Build library + CLI + server (complete stack)
|
||||
just build # Build library + unified binary (complete stack)
|
||||
just build-lib # Build JavaScript library only
|
||||
|
||||
# Utilities
|
||||
@@ -118,7 +118,7 @@ Running `just dev` gives you the **complete Insertr CMS**:
|
||||
- ✅ **Real-Time Persistence** - SQLite database with REST API
|
||||
- ✅ **Version Control** - Complete edit history with user attribution and rollback
|
||||
- ✅ **Content Management** - Create, read, update content via browser
|
||||
- ✅ **Build Integration** - CLI enhances HTML with database content
|
||||
- ✅ **Build Integration** - Binary enhances HTML with database content
|
||||
- ✅ **Hot Reload** - Changes reflected immediately
|
||||
|
||||
## 📚 **Version Control Features**
|
||||
@@ -145,16 +145,7 @@ Every content change is automatically tracked with:
|
||||
6. All changes are tracked automatically
|
||||
```
|
||||
|
||||
### **Parse Existing Site**
|
||||
```bash
|
||||
# Analyze HTML for editable elements
|
||||
just parse
|
||||
# or: cd insertr-cli && go run main.go parse ../demo-site/
|
||||
|
||||
# Development server with parsing
|
||||
just servedev
|
||||
# or: cd insertr-cli && go run main.go servedev -i ../demo-site -p 3000
|
||||
```
|
||||
|
||||
## 📊 Parser Output Example
|
||||
|
||||
@@ -177,16 +168,23 @@ just servedev
|
||||
services-grid → 6 children (3×h3, 3×p)
|
||||
```
|
||||
|
||||
## 🏗️ Architecture: Build-Time Enhancement
|
||||
## 🏗️ Architecture: Unified Binary
|
||||
|
||||
### **Enhancement Pipeline**
|
||||
```
|
||||
Static Site Build → Insertr CLI Enhancement → Enhanced Deployment
|
||||
Static Site Build → insertr enhance → Enhanced Deployment
|
||||
↓ ↓ ↓
|
||||
Pure HTML Parse + Inject Content Smart Loading
|
||||
Auto-generate IDs (Auth-dependent)
|
||||
Pure HTML Parse + Inject Smart Loading
|
||||
Database Content (Auth-dependent)
|
||||
↓
|
||||
Runtime Content API ← insertr serve ← Database (SQLite/PostgreSQL)
|
||||
```
|
||||
|
||||
**Unified Commands:**
|
||||
- `insertr enhance` - Build-time content injection
|
||||
- `insertr serve` - Runtime API server
|
||||
- Single binary handles both development and production workflows
|
||||
|
||||
### **Smart Loading Strategy**
|
||||
```html
|
||||
<!-- Regular visitors: zero overhead -->
|
||||
@@ -203,6 +201,60 @@ Static Site Build → Insertr CLI Enhancement → Enhanced Deployment
|
||||
- **Zero configuration**: No schema files or content mappings
|
||||
- **Developer friendly**: Stay in HTML markup, no context switching
|
||||
|
||||
## 🔧 Unified Binary Commands
|
||||
|
||||
### **Build-Time Enhancement**
|
||||
```bash
|
||||
# Production build with remote API
|
||||
./insertr enhance src/ --output ./dist --api https://cms.example.com --api-key xyz
|
||||
|
||||
# Development build with local database
|
||||
./insertr enhance demo-site/ --output ./dist --db ./content.db
|
||||
|
||||
# Development build with mock data
|
||||
./insertr enhance demo-site/ --output ./dist --mock
|
||||
|
||||
# Use justfile shortcuts
|
||||
just enhance # Default: demo-site/ → dist/ with mock data
|
||||
just enhance input="src" output="public" # Custom paths
|
||||
```
|
||||
|
||||
### **Runtime API Server**
|
||||
```bash
|
||||
# Production server with PostgreSQL
|
||||
./insertr serve --db "postgresql://user:pass@host:5432/dbname"
|
||||
|
||||
# Development server with SQLite
|
||||
./insertr serve --dev-mode --port 8080 --db ./dev.db
|
||||
|
||||
# Production server with custom config
|
||||
./insertr --config ./production.yaml serve
|
||||
|
||||
# Use justfile shortcuts
|
||||
just serve # Development server on :8080
|
||||
just serve-prod port="443" # Production server
|
||||
```
|
||||
|
||||
### **Configuration Options**
|
||||
```bash
|
||||
# YAML configuration file
|
||||
./insertr --config ./custom.yaml [command]
|
||||
|
||||
# Environment variables
|
||||
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"
|
||||
|
||||
# Command-line flags (highest priority)
|
||||
./insertr --db ./custom.db --site-id staging serve --port 3000
|
||||
|
||||
# Show all options
|
||||
./insertr --help
|
||||
./insertr enhance --help
|
||||
./insertr serve --help
|
||||
```
|
||||
|
||||
## 📚 Integration Examples
|
||||
|
||||
### **GitHub Actions Workflow**
|
||||
@@ -249,23 +301,22 @@ Static Site Build → Insertr CLI Enhancement → Enhanced Deployment
|
||||
|
||||
### **Live Development with Hot Reload**
|
||||
```bash
|
||||
# 🔥 Hot Reload: watches BOTH library AND CLI
|
||||
# 🔥 Hot Reload: watches BOTH library AND unified binary
|
||||
just air
|
||||
# or: cd insertr-cli && air
|
||||
|
||||
# Alternative: Watch library only
|
||||
just watch
|
||||
# or: cd lib && npm run dev
|
||||
|
||||
# Library changes: lib/src/**/*.js → Auto rebuild library + CLI
|
||||
# CLI changes: cmd/**/*.go → Auto rebuild CLI
|
||||
# Library changes: lib/src/**/*.js → Auto rebuild library + binary
|
||||
# Binary changes: cmd/**/*.go, internal/**/*.go → Auto rebuild binary
|
||||
# Both trigger server restart with latest embedded assets
|
||||
# Visit localhost:3000 → Refresh to see changes
|
||||
```
|
||||
|
||||
**What Gets Hot Reloaded:**
|
||||
- JavaScript library changes (`lib/src/`)
|
||||
- Go CLI changes (`insertr-cli/`)
|
||||
- Go unified binary changes (`cmd/`, `internal/`)
|
||||
- Enhanced HTML output (real-time content injection)
|
||||
|
||||
### **Content ID Management**
|
||||
@@ -276,14 +327,54 @@ just watch
|
||||
|
||||
**Production Phase:**
|
||||
- Preserve existing content mappings for stability
|
||||
- CLI warns about orphaned content
|
||||
- Binary warns about orphaned content
|
||||
- Simple migration tools for structural changes
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### **YAML Configuration (insertr.yaml)**
|
||||
```yaml
|
||||
# Database configuration
|
||||
database:
|
||||
path: "./insertr.db" # SQLite file or PostgreSQL connection string
|
||||
|
||||
# API configuration (for remote content API)
|
||||
api:
|
||||
url: "" # Content API URL (leave empty to use local database)
|
||||
key: "" # API authentication key
|
||||
|
||||
# Server configuration
|
||||
server:
|
||||
port: 8080 # HTTP server port
|
||||
dev_mode: false # Enable development mode features
|
||||
|
||||
# Build configuration
|
||||
build:
|
||||
input: "./src" # Default input directory
|
||||
output: "./dist" # Default output directory
|
||||
|
||||
# Global settings
|
||||
site_id: "demo" # Site ID for content lookup
|
||||
mock_content: false # Use mock content instead of real data
|
||||
```
|
||||
|
||||
### **Configuration Precedence**
|
||||
1. **CLI flags** (highest priority) - `./insertr --db ./custom.db serve`
|
||||
2. **Environment variables** - `INSERTR_DB_PATH=./custom.db`
|
||||
3. **YAML config file** - `insertr.yaml` or `--config custom.yaml`
|
||||
4. **Smart defaults** (lowest priority)
|
||||
|
||||
### **Environment Variables**
|
||||
- `INSERTR_DB_PATH` - Database path
|
||||
- `INSERTR_API_URL` - Remote API URL
|
||||
- `INSERTR_API_KEY` - API authentication key
|
||||
- `INSERTR_SITE_ID` - Site identifier
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
- **[Development Guide](DEVELOPMENT.md)** - Setup and contribution workflow
|
||||
- **[Research Document](RESEARCH.md)** - Strategic analysis and market positioning
|
||||
- **[Parser Documentation](insertr-cli/README.md)** - CLI usage and API reference
|
||||
- **[Integration Summary](INTEGRATION-SUMMARY.md)** - Complete architecture overview
|
||||
|
||||
## 🎯 Market Position: "The Tailwind of CMS"
|
||||
|
||||
@@ -303,6 +394,59 @@ just watch
|
||||
- Works with any framework or generator
|
||||
- Developer experience focused
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### **YAML Configuration (insertr.yaml)**
|
||||
```yaml
|
||||
# Database configuration
|
||||
database:
|
||||
path: "./insertr.db" # SQLite file path or PostgreSQL connection string
|
||||
|
||||
# API configuration (for remote content API)
|
||||
api:
|
||||
url: "" # Content API URL (leave empty to use local database)
|
||||
key: "" # API authentication key
|
||||
|
||||
# Server configuration
|
||||
server:
|
||||
port: 8080 # HTTP server port
|
||||
dev_mode: false # Enable development mode features
|
||||
|
||||
# Build configuration
|
||||
build:
|
||||
input: "./src" # Default input directory for enhancement
|
||||
output: "./dist" # Default output directory for enhanced files
|
||||
|
||||
# Global settings
|
||||
site_id: "demo" # Default site ID for content lookup
|
||||
mock_content: false # Use mock content instead of real data
|
||||
```
|
||||
|
||||
### **Environment Variables**
|
||||
- `INSERTR_DB_PATH` - Database path override
|
||||
- `INSERTR_API_URL` - Remote API URL override
|
||||
- `INSERTR_API_KEY` - API authentication key
|
||||
- `INSERTR_SITE_ID` - Site identifier override
|
||||
|
||||
### **Configuration Precedence**
|
||||
1. **CLI flags** (highest priority)
|
||||
2. **Environment variables**
|
||||
3. **YAML config file**
|
||||
4. **Smart defaults** (lowest priority)
|
||||
|
||||
### **Database Options**
|
||||
```bash
|
||||
# SQLite (development)
|
||||
./insertr serve --db "./content.db"
|
||||
|
||||
# PostgreSQL (production)
|
||||
./insertr serve --db "postgresql://user:pass@host:5432/insertr"
|
||||
|
||||
# Environment-based
|
||||
export INSERTR_DB_PATH="postgresql://prod-host/insertr"
|
||||
./insertr serve
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
This project follows the "Tailwind philosophy" of developer-first design:
|
||||
|
||||
@@ -1,8 +1,23 @@
|
||||
# Insertr Content Server
|
||||
# ⚠️ Deprecated: Insertr Content Server
|
||||
|
||||
REST API server for the Insertr CMS system. Provides content management with version control and user attribution.
|
||||
> **This standalone server has been replaced by the unified `insertr` binary.**
|
||||
> **Please see the [main README](../README.md) for updated instructions.**
|
||||
|
||||
## Features
|
||||
## 🔄 Migration to Unified Binary
|
||||
|
||||
The Insertr Content Server functionality has been integrated into the unified `insertr` binary. Instead of running a separate server binary, use:
|
||||
|
||||
```bash
|
||||
# Old approach (deprecated)
|
||||
./insertr-server --port 8080
|
||||
|
||||
# New unified approach
|
||||
./insertr serve --port 8080 --dev-mode
|
||||
```
|
||||
|
||||
## ✅ All Features Preserved
|
||||
|
||||
The unified binary includes all server functionality:
|
||||
|
||||
- **Content Management**: Full CRUD operations for content items
|
||||
- **Version Control**: Complete edit history with rollback functionality
|
||||
@@ -10,9 +25,9 @@ REST API server for the Insertr CMS system. Provides content management with ver
|
||||
- **Type-Safe Database**: Uses sqlc for generated Go code from SQL
|
||||
- **SQLite & PostgreSQL**: Database flexibility for development to production
|
||||
|
||||
## API Endpoints
|
||||
## 🚀 Updated API Endpoints
|
||||
|
||||
### Content Operations
|
||||
### Content Operations (Unchanged)
|
||||
- `GET /api/content?site_id={site}` - Get all content for a 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 content items
|
||||
@@ -20,16 +35,32 @@ REST API server for the Insertr CMS system. Provides content management with ver
|
||||
- `PUT /api/content/{id}?site_id={site}` - Update existing content
|
||||
- `DELETE /api/content/{id}?site_id={site}` - Delete content
|
||||
|
||||
### Version Control
|
||||
### Version Control (Unchanged)
|
||||
- `GET /api/content/{id}/versions?site_id={site}` - Get version history
|
||||
- `POST /api/content/{id}/rollback?site_id={site}` - Rollback to specific version
|
||||
|
||||
### Health & Status
|
||||
### Health & Status (Unchanged)
|
||||
- `GET /health` - Server health check
|
||||
|
||||
## User Attribution
|
||||
## 🚀 New Quick Start (Unified Binary)
|
||||
|
||||
All content operations support user attribution via the `X-User-ID` header:
|
||||
```bash
|
||||
# Build unified binary (from project root)
|
||||
go build -o insertr .
|
||||
|
||||
# Start server with development mode
|
||||
./insertr serve --dev-mode --port 8080
|
||||
|
||||
# Start production server
|
||||
./insertr serve --port 8080 --db "postgresql://user:pass@host/db"
|
||||
|
||||
# Check health (same endpoint)
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
## User Attribution (Unchanged)
|
||||
|
||||
All content operations still support user attribution via the `X-User-ID` header:
|
||||
|
||||
```bash
|
||||
curl -X PUT "http://localhost:8080/api/content/hero-title?site_id=demo" \
|
||||
@@ -38,37 +69,28 @@ curl -X PUT "http://localhost:8080/api/content/hero-title?site_id=demo" \
|
||||
-d '{"value": "Updated content"}'
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
## 🛠️ Development (Updated for Unified Binary)
|
||||
|
||||
```bash
|
||||
# Build server
|
||||
go build -o insertr-server ./cmd/server
|
||||
|
||||
# Start server
|
||||
./insertr-server --port 8080
|
||||
|
||||
# Check health
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Using sqlc
|
||||
### Using sqlc (From Project Root)
|
||||
|
||||
```bash
|
||||
# Install sqlc
|
||||
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
|
||||
|
||||
# Generate Go code from SQL
|
||||
# Generate Go code from SQL (from project root)
|
||||
sqlc generate
|
||||
|
||||
# Build with generated code
|
||||
go build ./cmd/server
|
||||
# Build unified binary
|
||||
go build -o insertr .
|
||||
|
||||
# Development with hot reload
|
||||
just dev # Full-stack development
|
||||
air # Hot reload unified binary only
|
||||
```
|
||||
|
||||
### Database Schema
|
||||
### Database Schema (Location Updated)
|
||||
|
||||
See `db/schema/schema.sql` for the complete schema. Key tables:
|
||||
See `db/sqlite/schema.sql` and `db/postgresql/schema.sql` for database-specific schemas. Key tables:
|
||||
|
||||
- `content` - Current content versions
|
||||
- `content_versions` - Complete version history
|
||||
@@ -103,21 +125,20 @@ curl -X POST "http://localhost:8080/api/content/hero-title/rollback?site_id=demo
|
||||
-d '{"version_id": 1}'
|
||||
```
|
||||
|
||||
## Configuration
|
||||
---
|
||||
|
||||
### Environment Variables
|
||||
- `PORT` - Server port (default: 8080)
|
||||
- `DB_PATH` - SQLite database file path (default: ./insertr.db)
|
||||
## 📖 For Complete Documentation
|
||||
|
||||
### Command Line Flags
|
||||
```bash
|
||||
./insertr-server --help
|
||||
```
|
||||
**➡️ See the [main README](../README.md) for:**
|
||||
- Unified binary installation and usage
|
||||
- Complete configuration options (YAML, environment variables, CLI flags)
|
||||
- Development workflow with `just dev`
|
||||
- Production deployment guidance
|
||||
- Full architecture documentation
|
||||
|
||||
## Production Deployment
|
||||
**➡️ See [INTEGRATION-SUMMARY.md](../INTEGRATION-SUMMARY.md) for:**
|
||||
- Technical architecture details
|
||||
- Database schema information
|
||||
- API integration examples
|
||||
|
||||
1. **Database**: Consider PostgreSQL for production scale
|
||||
2. **Authentication**: Integrate with your auth system via middleware
|
||||
3. **CORS**: Configure appropriate CORS policies
|
||||
4. **SSL**: Serve over HTTPS
|
||||
5. **Monitoring**: Add logging and metrics collection
|
||||
The unified `insertr` binary provides all server functionality with improved developer experience and simplified deployment.
|
||||
Reference in New Issue
Block a user