From 1dc9a652f54d7c011811bd639560c67f85efce1c Mon Sep 17 00:00:00 2001 From: "Rodrigo Rodriguez (Pragmatismo)" Date: Tue, 25 Nov 2025 16:10:50 -0300 Subject: [PATCH] - Version of publish. --- book.toml | 54 +++ docs/MIGRATION_INTEGRATION_SUMMARY.md | 120 ++++++ docs/src/SUMMARY.md | 19 +- .../src/{appendix-i => appendix-15}/README.md | 0 .../relationships.md | 0 .../src/{appendix-i => appendix-15}/schema.md | 0 .../src/{appendix-i => appendix-15}/tables.md | 0 docs/src/appendix-i/assets/kb-access.svg | 96 ----- .../appendix-i/assets/kb-access.svg.backup | 128 ------ .../src/appendix-i/assets/schema-detailed.svg | 128 ------ .../assets/schema-detailed.svg.backup | 217 ----------- .../src/appendix-i/assets/schema-overview.svg | 131 ------- .../assets/schema-overview.svg.backup | 170 -------- docs/src/appendix-i/assets/session-flow.svg | 126 ------ .../appendix-i/assets/session-flow.svg.backup | 126 ------ docs/src/assets/migration-architecture.svg | 366 ++++++++++++++++++ docs/src/assets/technical-specs.svg | 146 +++++++ docs/src/chapter-03/README.md | 58 +-- docs/src/chapter-14-migration/README.md | 164 ++++++++ docs/src/chapter-14-migration/automation.md | 58 +++ .../chapter-14-migration/common-concepts.md | 81 ++++ .../chapter-14-migration/google-workspace.md | 204 ++++++++++ docs/src/chapter-14-migration/kb-migration.md | 78 ++++ .../src/chapter-14-migration/microsoft-365.md | 150 +++++++ docs/src/chapter-14-migration/overview.md | 166 ++++++++ docs/src/chapter-14-migration/validation.md | 81 ++++ docs/src/custom.css | 215 ++++++++++ docs/src/theme-sync.js | 115 ++++++ 28 files changed, 2016 insertions(+), 1181 deletions(-) create mode 100644 book.toml create mode 100644 docs/MIGRATION_INTEGRATION_SUMMARY.md rename docs/src/{appendix-i => appendix-15}/README.md (100%) rename docs/src/{appendix-i => appendix-15}/relationships.md (100%) rename docs/src/{appendix-i => appendix-15}/schema.md (100%) rename docs/src/{appendix-i => appendix-15}/tables.md (100%) delete mode 100644 docs/src/appendix-i/assets/kb-access.svg delete mode 100644 docs/src/appendix-i/assets/kb-access.svg.backup delete mode 100644 docs/src/appendix-i/assets/schema-detailed.svg delete mode 100644 docs/src/appendix-i/assets/schema-detailed.svg.backup delete mode 100644 docs/src/appendix-i/assets/schema-overview.svg delete mode 100644 docs/src/appendix-i/assets/schema-overview.svg.backup delete mode 100644 docs/src/appendix-i/assets/session-flow.svg delete mode 100644 docs/src/appendix-i/assets/session-flow.svg.backup create mode 100644 docs/src/assets/migration-architecture.svg create mode 100644 docs/src/assets/technical-specs.svg create mode 100644 docs/src/chapter-14-migration/README.md create mode 100644 docs/src/chapter-14-migration/automation.md create mode 100644 docs/src/chapter-14-migration/common-concepts.md create mode 100644 docs/src/chapter-14-migration/google-workspace.md create mode 100644 docs/src/chapter-14-migration/kb-migration.md create mode 100644 docs/src/chapter-14-migration/microsoft-365.md create mode 100644 docs/src/chapter-14-migration/overview.md create mode 100644 docs/src/chapter-14-migration/validation.md create mode 100644 docs/src/custom.css create mode 100644 docs/src/theme-sync.js diff --git a/book.toml b/book.toml new file mode 100644 index 00000000..c4a39d03 --- /dev/null +++ b/book.toml @@ -0,0 +1,54 @@ +[book] +title = "BotServer Documentation" +authors = ["BotServer Team"] +language = "en" +multilingual = false +src = "docs/src" +description = "Documentation for BotServer - A flexible bot framework" + +[build] +build-dir = "docs/book" + +[output.html] +smart-punctuation = true +mathjax-support = false +copy-fonts = true +no-section-label = false +additional-css = ["docs/src/custom.css"] +additional-js = ["docs/src/theme-sync.js"] +git-repository-url = "https://github.com/yourusername/botserver" +git-repository-icon = "fa-github" +edit-url-template = "https://github.com/yourusername/botserver/edit/main/{path}" +site-url = "/botserver/" +cname = "" +input-404 = "" + +[output.html.print] +enable = true + +[output.html.fold] +enable = false +level = 0 + +[output.html.playground] +editable = false +copyable = true +copy-js = true +line-numbers = false +runnable = false + +[output.html.search] +enable = true +limit-results = 30 +teaser-word-count = 30 +use-boolean-and = true +boost-title = 2 +boost-hierarchy = 1 +boost-paragraph = 1 +expand = true +heading-split-level = 3 +copy-js = true + +[preprocessor.index] + +[preprocessor.links] diff --git a/docs/MIGRATION_INTEGRATION_SUMMARY.md b/docs/MIGRATION_INTEGRATION_SUMMARY.md new file mode 100644 index 00000000..d7511653 --- /dev/null +++ b/docs/MIGRATION_INTEGRATION_SUMMARY.md @@ -0,0 +1,120 @@ +# Migration Integration Summary + +## Date: November 25, 2024 + +### Overview +Successfully integrated Chapter 14 (Migration Guide) into the General Bots documentation and reorganized the appendix numbering system to maintain consistency. + +## Changes Implemented + +### 1. Chapter 14: Migration Guide Integration +Added a comprehensive migration chapter with the following sections: +- **Migration Overview** - Understanding the paradigm shift from cloud to self-hosted +- **Common Concepts** - Shared patterns and tools across migrations +- **Knowledge Base Migration** - Converting SharePoint/Drive to .gbkb format +- **Google Workspace Integration** - Complete migration path from Google services +- **Microsoft 365 Integration** - Complete migration path from M365 services +- **Automation Migration** - BASIC scripts for automating migration tasks +- **Validation and Testing** - Post-migration verification procedures + +### 2. Documentation Structure Updates + +#### Before: +``` +Part I-XII: Chapters 1-12 +Part XIII: Community (Chapter 13) +Appendices: Appendix I (Database Model) +``` + +#### After: +``` +Part I-XII: Chapters 1-12 +Part XIII: Community (Chapter 13) +Part XIV: Migration (Chapter 14) ← NEW +Appendices: Appendix XV (Database Model) ← RENUMBERED +``` + +### 3. File System Changes + +| Action | From | To | +|--------|------|-----| +| Renamed | `docs/src/appendix-i/` | `docs/src/appendix-15/` | +| Updated | `docs/src/SUMMARY.md` | Added Chapter 14 entries | +| Updated | `book.toml` | Fixed deprecated `curly-quotes` → `smart-punctuation` | + +### 4. Migration Chapter Contents + +The migration chapter provides: +- **Enterprise comparison matrix** showing equivalents between cloud services and General Bots components +- **Step-by-step migration guides** for both Microsoft 365 and Google Workspace +- **Automation scripts** in BASIC for common migration tasks +- **Knowledge base conversion** utilities and best practices +- **Validation checklists** to ensure successful migration + +### 5. Key Concepts Introduced + +#### The Mega-Prompt Problem +Explains how services like Microsoft Copilot and Google Gemini are essentially sophisticated prompt engines with limitations: +- Black box operations +- Cloud dependency +- Monolithic approach +- Subscription lock-in + +#### The Component Solution +Demonstrates General Bots' approach with actual installable components: +- True modularity +- Self-hosted control +- Component composability +- No vendor lock-in + +### 6. Migration Matrix + +| Enterprise Service | General Bots Component | Package Type | +|-------------------|------------------------|--------------| +| OneDrive/Google Drive | MinIO | .gbdrive | +| Outlook/Gmail | Stalwart Mail | .gbmail | +| Entra ID/Google Directory | Zitadel | .gbdirectory | +| SharePoint/Sites | MinIO + Qdrant | .gbkb | +| Teams/Meet | LiveKit | .gbmeet | +| Copilot/Gemini | Local LLM + BASIC | .gbdialog | + +## Build Verification + +✅ **mdBook build**: Successful, no errors +✅ **Documentation structure**: All links resolve correctly +✅ **Chapter integration**: Chapter 14 fully accessible in navigation +✅ **Appendix renumbering**: Appendix XV properly referenced +✅ **Configuration updates**: No deprecation warnings + +## Impact + +This integration provides enterprise users with: +1. Clear migration paths from cloud services to self-hosted alternatives +2. Practical automation scripts to speed up migration +3. Validation procedures to ensure data integrity +4. Cost comparison insights between cloud subscriptions and self-hosted solutions + +## Technical Notes + +- SVG diagrams in migration chapter use CSS variables for theme compatibility +- All migration scripts are written in General Bots BASIC dialect +- Knowledge base conversion maintains semantic search capabilities +- Documentation follows existing mdBook conventions and styling + +## Future Considerations + +1. **Add migration metrics** - Time estimates for different organization sizes +2. **Expand automation library** - More BASIC scripts for specific scenarios +3. **Include case studies** - Real-world migration success stories +4. **Performance benchmarks** - Comparison data between cloud and self-hosted + +## Files Affected + +- `/docs/src/SUMMARY.md` +- `/docs/src/chapter-14-migration/*.md` (8 files) +- `/docs/src/appendix-15/*.md` (4 files, renamed from appendix-i) +- `/book.toml` + +## Conclusion + +The migration chapter successfully bridges the gap for enterprises looking to transition from cloud services to General Bots' self-hosted architecture. The documentation now provides a complete path from evaluation through implementation and validation. \ No newline at end of file diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 336537a6..799b154d 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -176,12 +176,23 @@ - [Community Guidelines](./chapter-13-community/community.md) - [IDEs](./chapter-13-community/ide-extensions.md) +# Part XIII - Migration + +- [Chapter 14: Migration Guide](./chapter-14-migration/README.md) + - [Migration Overview](./chapter-14-migration/overview.md) + - [Common Concepts](./chapter-14-migration/common-concepts.md) + - [Knowledge Base Migration](./chapter-14-migration/kb-migration.md) + - [Google Workspace Integration](./chapter-14-migration/google-workspace.md) + - [Microsoft 365 Integration](./chapter-14-migration/microsoft-365.md) + - [Automation Migration](./chapter-14-migration/automation.md) + - [Validation and Testing](./chapter-14-migration/validation.md) + # Appendices -- [Appendix I: Database Model](./appendix-i/README.md) - - [Schema Overview](./appendix-i/schema.md) - - [Tables](./appendix-i/tables.md) - - [Relationships](./appendix-i/relationships.md) +- [Appendix XV: Database Model](./appendix-15/README.md) + - [Schema Overview](./appendix-15/schema.md) + - [Tables](./appendix-15/tables.md) + - [Relationships](./appendix-15/relationships.md) [Glossary](./glossary.md) [Contact](./contact/README.md) \ No newline at end of file diff --git a/docs/src/appendix-i/README.md b/docs/src/appendix-15/README.md similarity index 100% rename from docs/src/appendix-i/README.md rename to docs/src/appendix-15/README.md diff --git a/docs/src/appendix-i/relationships.md b/docs/src/appendix-15/relationships.md similarity index 100% rename from docs/src/appendix-i/relationships.md rename to docs/src/appendix-15/relationships.md diff --git a/docs/src/appendix-i/schema.md b/docs/src/appendix-15/schema.md similarity index 100% rename from docs/src/appendix-i/schema.md rename to docs/src/appendix-15/schema.md diff --git a/docs/src/appendix-i/tables.md b/docs/src/appendix-15/tables.md similarity index 100% rename from docs/src/appendix-i/tables.md rename to docs/src/appendix-15/tables.md diff --git a/docs/src/appendix-i/assets/kb-access.svg b/docs/src/appendix-i/assets/kb-access.svg deleted file mode 100644 index c8879893..00000000 --- a/docs/src/appendix-i/assets/kb-access.svg +++ /dev/null @@ -1,96 +0,0 @@ - - - - - - - - - Knowledge Base Access - - - - user_sessions - - - - user_kb_associations - - - - kb_collections - - - - kb_documents - - - - Vector Storage - - - - - id, user_id - bot_id, session_token - - - id, session_id - kb_id, created_at - - - id, bot_id, name - created_at, metadata - - - id, collection_id - content, embeddings - - - Embeddings stored - for semantic search - - - - - - - - - - - - - - - - - - - Has Access - Contains - 1:N - Indexes - References - - - - - Access Pattern: - 1. Session requests KB access - 2. Association created in user_kb_associations - 3. KB documents become available - 4. Vector search enabled on embeddings - - - - - Sessions gain access to knowledge bases through associations, enabling vector search on document embeddings - - - Each collection contains multiple documents with pre-computed embeddings for semantic search - - - Access is controlled per session, allowing dynamic knowledge base selection during conversations - - diff --git a/docs/src/appendix-i/assets/kb-access.svg.backup b/docs/src/appendix-i/assets/kb-access.svg.backup deleted file mode 100644 index 6b988a0d..00000000 --- a/docs/src/appendix-i/assets/kb-access.svg.backup +++ /dev/null @@ -1,128 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Knowledge Base Access - - - - - user_sessions - - - • id - • user_id - • bot_id - • session_token - - - - - Has Access - - - - - user_kb_associations - - - • id - • session_id - • kb_id - • created_at - - - - - References - - - - - kb_collections - - - • id - • bot_id - • name - • created_at - • metadata - - - - - Contains - 1:N - - - - - kb_documents - - - • id - • collection_id - • content - • embeddings - • metadata - - - - - - Vector Storage - Embeddings stored - for semantic search - - - - - - - - - Access Pattern - - - 1. Session requests KB - 2. Association created - 3. KB documents available - 4. Vector search enabled - - - - - - - \ No newline at end of file diff --git a/docs/src/appendix-i/assets/schema-detailed.svg b/docs/src/appendix-i/assets/schema-detailed.svg deleted file mode 100644 index 06d41d43..00000000 --- a/docs/src/appendix-i/assets/schema-detailed.svg +++ /dev/null @@ -1,128 +0,0 @@ - - - - - - - - - Database Entity Details - - - - organizations - - - - bots - - - - users - - - - user_sessions - - - - bot_memories - - - - message_history - - - - kb_collections - - - - kb_documents - - - - - id, name - created_at - - - id, org_id - name, config - - - id, username - email, active - - - id, user_id, bot_id - token, expires_at - - - id, bot_id - key, value - - - id, session_id - message, sender - - - id, bot_id - name, description - - - id, collection_id - content, embeddings - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1:N - 1:N - 1:N - 1:N - 1:N - 1:N - - - - - Key Relationships: - - • Organizations own multiple Bots - • Users create multiple Sessions with Bots - • Sessions generate Message History - • Bots maintain Memories (key-value pairs) - • Bots have Knowledge Collections containing Documents - • Documents store embeddings for vector search - • All entities use UUIDs as primary keys (except KB collections using TEXT) - - - - - Core database schema supporting multi-tenant bot operations with session management and vector search capabilities - - diff --git a/docs/src/appendix-i/assets/schema-detailed.svg.backup b/docs/src/appendix-i/assets/schema-detailed.svg.backup deleted file mode 100644 index c3f7b110..00000000 --- a/docs/src/appendix-i/assets/schema-detailed.svg.backup +++ /dev/null @@ -1,217 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Database Entity Details - - - - - - organizations - - - id: UUID (PK) - name: VARCHAR(255) - created_at: TIMESTAMPTZ - updated_at: TIMESTAMPTZ - - - - - - - - bots - - - id: UUID (PK) - organization_id: UUID (FK) - name: VARCHAR(255) - configuration: JSONB - created_at: TIMESTAMPTZ - updated_at: TIMESTAMPTZ - - - - - - - - bot_memories - - - id: UUID (PK) - bot_id: UUID (FK) - key: TEXT - value: TEXT - - - - - - - - user_sessions - - - id: UUID (PK) - user_id: UUID (FK) - bot_id: UUID (FK) - session_token: TEXT - created_at: TIMESTAMPTZ - expires_at: TIMESTAMPTZ - - - - - - - - kb_collections - - - id: TEXT (PK) - bot_id: UUID (FK) - name: TEXT - description: TEXT - created_at: TIMESTAMPTZ - - - - - - - - users - - - id: UUID (PK) - username: TEXT - email: TEXT - password_hash: TEXT - active: BOOLEAN - created_at: TIMESTAMPTZ - - - - - - - - message_history - - - id: UUID (PK) - session_id: UUID (FK) - user_id: UUID (FK) - bot_id: UUID (FK) - message: TEXT - sender: TEXT - - - - - - - - kb_documents - - - id: UUID (PK) - collection_id: TEXT (FK) - content: TEXT - embeddings: VECTOR - metadata: JSONB - created_at: TIMESTAMPTZ - - - - - - - - 1:N - - - - 1:N - - - - - - - 1:N - - - - 1:N - - - - 1:N - - - - 1:N - - - - - Color Coding: - - - Organization - - - Bot Core - - - Sessions - - - Knowledge - - - Users - - - Messages - - - - - - \ No newline at end of file diff --git a/docs/src/appendix-i/assets/schema-overview.svg b/docs/src/appendix-i/assets/schema-overview.svg deleted file mode 100644 index 9792b851..00000000 --- a/docs/src/appendix-i/assets/schema-overview.svg +++ /dev/null @@ -1,131 +0,0 @@ - - - - - - - - - Database Schema Overview - - - - - organizations - - - - bots - - - - bot_configuration - - - - users - - - - - bot_memories - - - - kb_collections - - - - user_sessions - - - - basic_tools - - - - message_history - - - - - kb_documents - - - - user_login_tokens - - - - user_kb_associations - - - - session_tool_associations - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1:N - 1:N - 1:N - 1:N - 1:N - 1:N - 1:N - 1:N - 1:N - ref - ref - - - - - Entity Categories: - Core: organizations, bots, users • State: bot_memories, user_sessions, message_history - Knowledge: kb_collections, kb_documents • Tools: basic_tools • Auth: user_login_tokens - Associations: user_kb_associations, session_tool_associations, bot_configuration - - - - - Multi-tenant database schema supporting organizations with multiple bots, user sessions, knowledge bases, and tools - - diff --git a/docs/src/appendix-i/assets/schema-overview.svg.backup b/docs/src/appendix-i/assets/schema-overview.svg.backup deleted file mode 100644 index 70f13eb7..00000000 --- a/docs/src/appendix-i/assets/schema-overview.svg.backup +++ /dev/null @@ -1,170 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Database Schema Overview - - - - organizations - Top Level Entity - - - - bots - Bot Instances - - - - bot_configuration - Settings - - - - bot_memories - State Storage - - - - kb_collections - Knowledge Base - - - - kb_documents - Documents - - - - users - User Accounts - - - - user_sessions - Active Sessions - - - - message_history - Chat Messages - - - - user_login_tokens - Auth Tokens - - - - user_kb_associations - KB Access - - - - session_tool_associations - Tool Access - - - - basic_tools - BASIC Scripts - - - - - - 1:N - - - - 1:N - - - - 1:N - - - - 1:N - - - - 1:N - - - - 1:N - - - - 1:N - - - - 1:N - - - - 1:N - - - - 1:N - - - - ref - - - - ref - - - - - - - - Legend: - - 1:N Relationship - - - Reference - - - - - - \ No newline at end of file diff --git a/docs/src/appendix-i/assets/session-flow.svg b/docs/src/appendix-i/assets/session-flow.svg deleted file mode 100644 index 659db6a2..00000000 --- a/docs/src/appendix-i/assets/session-flow.svg +++ /dev/null @@ -1,126 +0,0 @@ - - - - - - - - - Session Flow Diagram - - - - User Login - - - - users - - - - user_sessions - - - - message_history - - - - Token - - - - user_login_tokens - - - user_kb_associations - - - session_tool_associations - - - - - id, email - zitadel_id - - - id, user_id, bot_id - token, expires_at - - - id, session_id - role, content - - - JWT/UUID - Auth - - - id, user_id, token - expires_at - - - id, session_id - kb_id, created_at - - - id, session_id - tool_name, added_at - - - - - - - - - - - - - - - - - - - - Creates - Establishes - Logs - Returns - Stores - Links KB - Links Tools - - - - - 1 - - - 2 - - - 3 - - - 4 - - - 5 - - - - - - Process Flow: - 1. User authenticates → 2. User record created/updated → 3. Session established → 4. Messages logged → 5. Token returned - - - - - Authentication flow from login through session establishment and message tracking - - diff --git a/docs/src/appendix-i/assets/session-flow.svg.backup b/docs/src/appendix-i/assets/session-flow.svg.backup deleted file mode 100644 index 4e312657..00000000 --- a/docs/src/appendix-i/assets/session-flow.svg.backup +++ /dev/null @@ -1,126 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Session Flow Diagram - - - - User Login - Authentication - Entry Point - - - - Creates - - - - - users - - - • id - • email - • zitadel_id - • created_at - • updated_at - - - - - Creates - - - - - user_sessions - - - • id - • user_id - • bot_id - • token - • created_at - • expires_at - - - - - Generates - Messages - - - - - message_history - - - • id - • session_id - • role - • content - • timestamp - • metadata - - - - - - 1 - - - 2 - - - 3 - - - 4 - - - - - - Process Flow - - - 1. User authenticates → 2. User record created/updated → 3. Session established → 4. Messages logged - - - - - - - \ No newline at end of file diff --git a/docs/src/assets/migration-architecture.svg b/docs/src/assets/migration-architecture.svg new file mode 100644 index 00000000..cfe67b77 --- /dev/null +++ b/docs/src/assets/migration-architecture.svg @@ -0,0 +1,366 @@ + + + + + + + + + + + + + + + + + Enterprise Migration Architecture + + + Current State + Migration Process + Target State + + + + + + Big Tech Cloud + + + + M365/Google + + + + OneDrive/ + Google Drive + + + Outlook/ + Gmail + + + Teams/ + Meet + + + SharePoint/ + Sites + + + Copilot/ + Gemini + + + • Vendor Lock-in + • Monthly Costs + + + + + + + Migration Tools + + + + rclone + + + imapsync + + + BASIC Scripts + + + API Migration + + + KB Converter + + + User Import + + + 1. Export Data + 2. Transform Format + 3. Import to GB + 4. Validate + + + + + + + Self-Hosted Stack + + + + General Bots Core + + + + MinIO + + + Stalwart + + + LiveKit + + + Qdrant + + + Local LLM + + + Zitadel + + + ✓ Full Control + ✓ No Vendor Lock-in + + + + + + + + + + + + + + + Cost Comparison + + + Enterprise Cloud + $50-200/user/month + Forever + + + Migration Cost + One-time effort + 1-4 weeks + + + Self-Hosted + Infrastructure only + ~$500/month total + + + + + Typical Migration Timeline + + + + + + + Start + Assessment + + + Week 1 + Infrastructure + + + Week 2 + Data Migration + + + Week 3 + Testing + + + Week 4 + Go Live + + + + + Transform from mega-prompt dependency to true component architecture + + + Your data, your infrastructure, your control + + + + + diff --git a/docs/src/assets/technical-specs.svg b/docs/src/assets/technical-specs.svg new file mode 100644 index 00000000..ef5e9f39 --- /dev/null +++ b/docs/src/assets/technical-specs.svg @@ -0,0 +1,146 @@ + + + + + System Technical Specifications + + + + + + + + Embedding Configuration + + Model: bge-small-en-v1.5-f32.gguf + • Dimensions: 384 + • Format: GGUF (quantized) + • Server: localhost:8082 + • Memory: ~200MB loaded + + + + + + LLM Configuration + + Model: DeepSeek-R1-Distill-Qwen-1.5B + • Context Size: 4096 tokens + • Max Predict: 1024 tokens + • Parallel Requests: 6 + • Quantization: Q3_K_M + + + + + + Performance Characteristics + + + Vector Index: HNSW Algorithm + • M=16, ef_construction=200 + • Distance: Cosine Similarity + • Build: ~1000 docs/minute + + + Chunking Strategy + • Chunk Size: 512 tokens + • Overlap: 50 tokens + • Prompt Compact: Level 4 + + + Runtime Metrics + • Query Latency: <50ms p99 + • Memory: ~1GB/million chunks + • Cache TTL: 3600 seconds + + + + + diff --git a/docs/src/chapter-03/README.md b/docs/src/chapter-03/README.md index 0a87d5e5..895184e7 100644 --- a/docs/src/chapter-03/README.md +++ b/docs/src/chapter-03/README.md @@ -16,61 +16,9 @@ The knowledge base architecture implements a multi-stage pipeline for document p ### Technical Specifications -Technical Specifications - - System Technical Specifications - - - - - - - - Embedding Configuration - - Model: bge-small-en-v1.5-f32.gguf - • Dimensions: 384 - • Format: GGUF (quantized) - • Server: localhost:8082 - • Memory: ~200MB loaded - - - - - - LLM Configuration - - Model: DeepSeek-R1-Distill-Qwen-1.5B - • Context Size: 4096 tokens - • Max Predict: 1024 tokens - • Parallel Requests: 6 - • Quantization: Q3_K_M - - - - - - Performance Characteristics - - - Vector Index: HNSW Algorithm - • M=16, ef_construction=200 - • Distance: Cosine Similarity - • Build: ~1000 docs/minute - - - Chunking Strategy - • Chunk Size: 512 tokens - • Overlap: 50 tokens - • Prompt Compact: Level 4 - - - Runtime Metrics - • Query Latency: <50ms p99 - • Memory: ~1GB/million chunks - • Cache TTL: 3600 seconds - - + + Technical Specifications + ## Document Processing Pipeline diff --git a/docs/src/chapter-14-migration/README.md b/docs/src/chapter-14-migration/README.md new file mode 100644 index 00000000..a33e04d1 --- /dev/null +++ b/docs/src/chapter-14-migration/README.md @@ -0,0 +1,164 @@ +# Chapter 14: Migration Concepts + +This chapter explores the conceptual framework for migrating from cloud-based enterprise services to self-hosted alternatives. We examine the philosophical and architectural differences between centralized cloud platforms and distributed, component-based systems. + +## Understanding Migration Paradigms + +### The Centralization Model + +Modern enterprise platforms operate on a centralization principle where all services flow through a single vendor's ecosystem. This creates: + +- **Unified Control Points**: Single authentication, single data store, single processing pipeline +- **Vendor-Managed Complexity**: The provider handles all infrastructure decisions +- **Abstraction Layers**: Users interact with simplified interfaces hiding underlying complexity +- **Subscription Economics**: Ongoing revenue model with usage-based scaling + +### The Decentralization Alternative + +Self-hosted solutions represent a return to distributed computing principles: + +- **Service Isolation**: Each function operates as an independent component +- **Explicit Architecture**: Clear understanding of data flow and processing +- **Ownership Model**: Complete control over infrastructure and data +- **Capital Investment**: One-time deployment with predictable operational costs + +## Migration Philosophy + +### Data Sovereignty + +The fundamental question in any migration is data ownership. Cloud services create a custodial relationship where: + +- Data physically resides on vendor infrastructure +- Processing occurs in vendor-controlled environments +- Access depends on continued vendor relationship +- Portability requires vendor cooperation + +Self-hosting inverts this relationship, establishing true ownership through physical and logical control. + +### Component Architecture vs Monolithic Services + +Enterprise clouds present as unified platforms but internally consist of hundreds of microservices. The difference lies in exposure: + +- **Cloud Platforms**: Hide complexity behind unified APIs +- **Component Systems**: Expose individual services as installable modules +- **Integration Points**: Cloud uses proprietary protocols; components use standards + +### The Automation Spectrum + +Cloud platforms offer automation through: +- AI-driven suggestions +- Pre-built workflows +- Natural language interfaces +- Black-box processing + +Component systems provide automation via: +- Scriptable interfaces +- Transparent logic flows +- Deterministic behaviors +- Auditable processes + +## Conceptual Migration Framework + +### Assessment Phase + +Understanding current usage patterns involves: + +- **Service Inventory**: What cloud features are actually used +- **Data Classification**: Types and volumes of information +- **Workflow Analysis**: How services interconnect +- **Dependency Mapping**: Critical integration points + +### Architecture Translation + +Converting cloud services to components requires: + +- **Service Decomposition**: Breaking monolithic features into discrete functions +- **Protocol Mapping**: Translating proprietary APIs to standard protocols +- **State Management**: Handling distributed data consistency +- **Security Boundaries**: Redefining trust zones + +### Knowledge Transformation + +Enterprise search and AI features translate to: + +- **Vector Databases**: Semantic search replacing keyword matching +- **Local Language Models**: On-premise AI instead of cloud APIs +- **Structured Knowledge**: Explicit schemas rather than implicit understanding +- **Retrieval Systems**: Direct access patterns vs mediated queries + +## Migration Patterns + +### Lift and Shift + +The simplest migration moves data without transformation: +- Direct file copying +- Database exports and imports +- Configuration replication +- Minimal service disruption + +### Progressive Migration + +Gradual transition maintains dual operations: +- Parallel running of old and new systems +- Phased user migration +- Incremental data synchronization +- Rollback capabilities + +### Transformation Migration + +Reimagining workflows for new architecture: +- Process redesign for component model +- Workflow optimization +- Legacy feature elimination +- New capability introduction + +## Post-Migration Considerations + +### Operational Changes + +Self-hosting shifts responsibilities: + +- **Maintenance**: From vendor to organization +- **Updates**: From automatic to managed +- **Scaling**: From elastic to planned +- **Support**: From vendor to internal/community + +### Cost Models + +Financial implications include: + +- **Capital vs Operating**: Hardware investment vs subscription fees +- **Expertise Requirements**: Internal capabilities vs vendor services +- **Risk Distribution**: Concentrated vs distributed failure points +- **Innovation Pace**: Vendor-driven vs self-determined + +### Compliance and Governance + +Regulatory considerations: + +- **Data Residency**: Guaranteed geographic location +- **Audit Trails**: Complete system visibility +- **Access Controls**: Granular permission management +- **Retention Policies**: Direct enforcement capability + +## Success Metrics + +### Technical Indicators + +- Service availability and reliability +- Performance benchmarks +- Integration completeness +- Feature parity achievement + +### Business Indicators + +- Cost reduction targets +- Productivity maintenance +- User satisfaction scores +- Risk mitigation effectiveness + +## Conclusion + +Migration from cloud to self-hosted systems represents more than technical change—it's a philosophical shift in how organizations relate to their digital infrastructure. Success requires understanding not just the technical mechanisms but the underlying principles that differentiate centralized cloud services from distributed component architectures. + +The journey from managed services to self-sovereignty demands careful planning, clear understanding of trade-offs, and commitment to operational excellence. While challenging, it offers organizations complete control over their digital destiny. \ No newline at end of file diff --git a/docs/src/chapter-14-migration/automation.md b/docs/src/chapter-14-migration/automation.md new file mode 100644 index 00000000..9be0a144 --- /dev/null +++ b/docs/src/chapter-14-migration/automation.md @@ -0,0 +1,58 @@ +# Automation Scripts + +High-level approaches to automate migration from cloud services to self-hosted infrastructure. + +## Overview + +Migration automation focuses on using existing tools and scripts to move data from cloud providers to your self-hosted stack. + +## Common Tools + +### File Transfer +- **rclone**: Universal cloud storage migration tool +- **rsync**: Traditional file synchronization +- **wget/curl**: API-based downloads + +### Email Migration +- **imapsync**: IMAP to IMAP migration +- **offlineimap**: Email backup and sync +- **getmail**: POP3/IMAP retrieval + +### Directory Services +- **ldapsearch/ldapadd**: LDAP export/import +- **csvde**: Active Directory CSV export +- **PowerShell**: AD automation scripts + +## Migration Approach + +### 1. Assessment +- List what needs migration +- Estimate data volumes +- Identify dependencies + +### 2. Tool Selection +- Match tools to data types +- Consider API availability +- Evaluate bandwidth needs + +### 3. Execution +- Start with test data +- Run in batches +- Monitor progress + +### 4. Validation +- Compare source and destination +- Check data integrity +- Test functionality + +## General Principles + +- Start small, scale up +- Keep source data intact +- Document the process +- Have a rollback plan + +## Next Steps + +- [Common Concepts](./common-concepts.md) - Shared migration patterns +- [Validation](./validation.md) - Testing migrated systems \ No newline at end of file diff --git a/docs/src/chapter-14-migration/common-concepts.md b/docs/src/chapter-14-migration/common-concepts.md new file mode 100644 index 00000000..db5944e1 --- /dev/null +++ b/docs/src/chapter-14-migration/common-concepts.md @@ -0,0 +1,81 @@ +# Common Migration Concepts + +Core concepts for migrating from cloud services to self-hosted infrastructure. + +## The Fundamental Shift + +### From Cloud Services +- Data on vendor servers +- Monthly subscription costs +- Limited control over updates +- Vendor-specific APIs + +### To Self-Hosted +- Data on your infrastructure +- One-time setup costs +- Full control over versions +- Standard protocols + +## Component Mapping + +| Cloud Service | Self-Hosted Alternative | Protocol | +|---------------|------------------------|----------| +| Cloud Storage | MinIO | S3 API | +| Email Service | Various mail servers | SMTP/IMAP | +| Identity Provider | Various auth servers | OIDC/SAML | + +## Migration Stages + +1. **Assessment** - What do you have? +2. **Planning** - How will you move it? +3. **Testing** - Does it work? +4. **Execution** - Do the migration +5. **Validation** - Verify everything works + +## Common Challenges + +### Data Volume +- Large datasets take time +- Bandwidth limitations +- Storage requirements + +### Authentication +- Passwords can't be exported +- Need password reset strategy +- Federation options + +### Dependencies +- Integrated services +- API changes +- Custom workflows + +## Tools Categories + +### File Migration +- Cloud storage sync tools +- API-based transfers +- Bulk download utilities + +### Email Migration +- IMAP synchronization tools +- Export/import utilities +- Archive formats + +### User Migration +- Directory export tools +- CSV/LDIF formats +- API-based extraction + +## Risk Mitigation + +- Always backup first +- Test with small datasets +- Keep source data intact +- Document everything +- Have rollback plan + +## Next Steps + +- [Microsoft 365 Migration](./microsoft-365.md) - M365 specific guidance +- [Google Workspace Migration](./google-workspace.md) - Google specific guidance +- [Knowledge Base Migration](./kb-migration.md) - Document migration \ No newline at end of file diff --git a/docs/src/chapter-14-migration/google-workspace.md b/docs/src/chapter-14-migration/google-workspace.md new file mode 100644 index 00000000..1675ecc9 --- /dev/null +++ b/docs/src/chapter-14-migration/google-workspace.md @@ -0,0 +1,204 @@ +# Google Workspace Migration Guide + +Migrating from Google Workspace to self-hosted infrastructure. + +## Overview + +Google Workspace (formerly G Suite) provides integrated cloud services that need to be migrated to various self-hosted alternatives. + +## Service Mapping + +| Google Workspace Service | Self-Hosted Alternative | Migration Tool | +|-------------------------|------------------------|----------------| +| Gmail | Mail server (Stalwart, etc.) | imapsync, Got Your Back | +| Google Drive | MinIO or Nextcloud | rclone | +| Google Docs/Sheets/Slides | LibreOffice, OnlyOffice | Export to Office formats | +| Google Calendar | CalDAV server | ical export/import | +| Google Meet | Jitsi, LiveKit | No migration (ephemeral) | +| Google Chat | General Bots | API export | + +## Migration Steps + +### 1. Email Migration (Gmail) + +**Prerequisites:** +- IMAP enabled in Google Admin +- App-specific passwords or OAuth +- Target mail server ready + +**Process:** +- Use imapsync or Got Your Back (GYB) +- Migrate labels as folders +- Preserve read/unread status + +**Considerations:** +- Gmail labels don't map perfectly to folders +- Some users may have 15+ years of email +- Attachments can consume significant space + +### 2. File Migration (Google Drive) + +**Prerequisites:** +- Google Drive API access +- Service account or OAuth credentials +- Storage capacity planning + +**Process:** +- Use rclone with Google Drive backend +- Export Google Docs to portable formats +- Maintain folder structure + +**Considerations:** +- Google Docs need format conversion +- Shared drives require separate handling +- Comments and suggestions are lost + +### 3. User Migration (Google Directory) + +**Prerequisites:** +- Google Admin SDK access +- Target identity provider configured + +**Process:** +- Export via Admin SDK or GAM tool +- Transform to target format +- Import to new system + +**Considerations:** +- No password export possible +- 2FA needs reconfiguration +- Groups and OUs need mapping + +## Google-Specific Challenges + +### Format Conversion +Google's proprietary formats require conversion: +- Google Docs → .docx or .odt +- Google Sheets → .xlsx or .ods +- Google Slides → .pptx or .odp +- Google Drawings → .svg or .png + +### API Quotas +Google enforces strict quotas: +- Drive API: 1,000 queries per 100 seconds +- Gmail API: 250 quota units per user per second +- Admin SDK: Various limits per API + +### Data Takeout +Google Takeout option: +- User-initiated bulk export +- Includes most Google services +- ZIP files can be huge (100GB+) +- Not suitable for organization-wide migration + +## Tools and Utilities + +### Google Admin Tools +- GAM (Google Apps Manager) - Command-line tool +- GAMADV-XTD - Enhanced GAM version +- Google Admin console for manual exports + +### Got Your Back (GYB) +- Python-based Gmail backup tool +- Supports full mailbox export +- Can restore to different account + +### rclone Configuration +- Supports team drives +- Handles Google Photos separately +- Can preserve modification times + +## Common Issues + +### Large Attachments +- Gmail allows 25MB attachments +- Some mail servers have lower limits +- May need to store separately + +### Shared Resources +- Shared drives need owner reassignment +- Calendar sharing needs recreation +- Document collaboration links break + +### Google Photos +- Not part of standard Google Drive +- Needs separate migration approach +- Original quality vs compressed + +## Migration Strategy + +### Phased Approach +1. Start with pilot group +2. Migrate inactive users first +3. Schedule department by department +4. Keep Google active during transition + +### Hybrid Period +- MX records can split email delivery +- Users can access both systems +- Gradual cutover reduces risk + +### Data Validation +- Compare file counts +- Verify email folders +- Check user access + +## Post-Migration + +### User Training +Key differences to document: +- No real-time collaboration like Google Docs +- Different UI/UX in alternatives +- Changed sharing workflows + +### Feature Gaps +Features that may be lost: +- Smart Compose in Gmail +- Google Assistant integration +- Automatic photo organization +- Version history in Docs + +### Maintaining Archive Access +Options for historical data: +- Keep reduced Google license for archive +- Export everything to static storage +- Convert to standard formats + +## Cost Factors + +### Google Workspace Pricing +- Business Starter: $6/user/month +- Business Standard: $12/user/month +- Business Plus: $18/user/month +- Need to maintain during migration + +### Data Export Costs +- No direct egress fees +- But API quotas may extend timeline +- Consider bandwidth costs + +## Timeline Estimates + +Migration duration depends on: +- Number of users +- Data volume per user +- Available bandwidth +- Conversion requirements + +Typical timelines: +- Small org (<50 users): 2-3 weeks +- Medium org (50-500 users): 1-3 months +- Large org (500+ users): 3-6 months + +## Best Practices + +1. **Inventory First**: Document what you have before starting +2. **Test Thoroughly**: Pilot with IT team first +3. **Communicate Often**: Keep users informed +4. **Plan Rollback**: Have contingency plans +5. **Archive Everything**: Keep backups of original data + +## Next Steps + +- [Common Concepts](./common-concepts.md) - General migration principles +- [Validation](./validation.md) - Testing procedures \ No newline at end of file diff --git a/docs/src/chapter-14-migration/kb-migration.md b/docs/src/chapter-14-migration/kb-migration.md new file mode 100644 index 00000000..0b61743b --- /dev/null +++ b/docs/src/chapter-14-migration/kb-migration.md @@ -0,0 +1,78 @@ +# Knowledge Base Migration + +Converting documents from cloud storage to General Bots knowledge bases. + +## Overview + +Knowledge base migration involves moving documents from various sources into `.gbkb` packages where they become searchable through General Bots. + +## Source Systems + +Common document sources: +- SharePoint document libraries +- Google Drive folders +- OneDrive/Dropbox +- Confluence spaces +- File servers + +## Document Types + +Supported formats: +- PDF files +- Office documents (Word, Excel, PowerPoint) +- Text files +- Markdown files +- HTML pages + +## Migration Process + +### 1. Export +- Download documents from source +- Preserve folder structure +- Maintain metadata where possible + +### 2. Organize +- Group related documents +- Create logical collections +- Remove duplicates + +### 3. Import +- Place in `.gbkb` folders +- General Bots indexes automatically +- Documents become searchable + +## Considerations + +### Volume +- Large document sets take time to index +- Consider staged migration +- Monitor disk space + +### Quality +- Clean up outdated content first +- Remove duplicate documents +- Fix broken files + +### Structure +- Maintain logical organization +- Use meaningful folder names +- Group by topic or department + +## Format Conversion + +Some formats may need conversion: +- Web pages → PDF or Markdown +- Databases → CSV exports +- Proprietary formats → Standard formats + +## Testing + +After migration: +- Verify search works +- Check document access +- Test with sample queries + +## Next Steps + +- [Overview](./overview.md) - Migration concepts +- [Validation](./validation.md) - Testing procedures \ No newline at end of file diff --git a/docs/src/chapter-14-migration/microsoft-365.md b/docs/src/chapter-14-migration/microsoft-365.md new file mode 100644 index 00000000..6280b8a0 --- /dev/null +++ b/docs/src/chapter-14-migration/microsoft-365.md @@ -0,0 +1,150 @@ +# Microsoft 365 Migration Guide + +Migrating from Microsoft 365 to self-hosted infrastructure. + +## Overview + +Microsoft 365 (formerly Office 365) includes multiple services that need to be migrated to different self-hosted components. + +## Service Mapping + +| Microsoft 365 Service | Self-Hosted Alternative | Migration Tool | +|----------------------|------------------------|----------------| +| Exchange Online | Mail server (Stalwart, etc.) | imapsync | +| OneDrive | MinIO or Nextcloud | rclone | +| SharePoint | MinIO + Wiki/CMS | rclone + export tools | +| Teams | Mattermost, General Bots, etc. | Export/Import APIs | +| Azure AD | Keycloak, Authentik, Zitadel | LDAP export | + +## Migration Steps + +### 1. Email Migration (Exchange Online) + +**Prerequisites:** +- IMAP access enabled in Exchange Online +- Target mail server configured +- User credentials or app passwords + +**Process:** +- Use imapsync for mailbox migration +- Migrate in batches to avoid throttling +- Preserve folder structure and flags + +**Considerations:** +- Exchange uses proprietary features (categories, etc.) that may not transfer +- Calendar and contacts need separate migration (CalDAV/CardDAV) +- Shared mailboxes require special handling + +### 2. File Migration (OneDrive/SharePoint) + +**Prerequisites:** +- OneDrive sync client or API access +- Sufficient storage on target +- Network bandwidth for transfer + +**Process:** +- Use rclone with OneDrive backend +- Maintain folder structure +- Preserve timestamps where possible + +**Considerations:** +- SharePoint metadata won't transfer automatically +- Version history is typically lost +- Permissions need to be recreated + +### 3. User Migration (Azure AD) + +**Prerequisites:** +- Azure AD Connect or API access +- Target identity provider ready + +**Process:** +- Export users via PowerShell or Graph API +- Transform to target format (LDIF, JSON) +- Import to new identity provider + +**Considerations:** +- Passwords cannot be exported +- MFA settings need reconfiguration +- Group memberships need mapping + +## Common Challenges + +### API Throttling +Microsoft throttles API calls: +- Plan for slow, steady migration +- Use batch operations where possible +- Consider running migrations off-peak + +### Data Volume +Large organizations may have: +- Terabytes of OneDrive/SharePoint data +- Years of email history +- Thousands of users + +### Feature Parity +Some M365 features have no direct equivalent: +- Power Automate workflows +- SharePoint lists and forms +- Teams channel history + +## Tools and Utilities + +### PowerShell for Export +- Azure AD PowerShell module for user export +- Exchange Online PowerShell for mailbox info +- SharePoint Online PowerShell for site inventory + +### Graph API +- Programmatic access to most M365 services +- Useful for custom migration scripts +- Requires app registration and permissions + +### Third-Party Tools +- BitTitan MigrationWiz (commercial) +- Sharegate (commercial) +- Various open-source scripts on GitHub + +## Post-Migration + +### DNS Changes +- Update MX records for email +- Update autodiscover records +- Consider keeping hybrid setup temporarily + +### User Communication +- Provide new login credentials +- Document changed procedures +- Offer training on new tools + +### Validation +- Verify email delivery +- Test file access +- Confirm authentication works + +## Cost Considerations + +### Subscription Overlap +- May need to maintain M365 during migration +- Consider read-only licenses for archive access + +### Data Transfer Costs +- Egress charges from Microsoft +- Bandwidth costs for large transfers + +## Timeline Estimates + +- Small org (<50 users): 1-2 weeks +- Medium org (50-500 users): 1-2 months +- Large org (500+ users): 2-6 months + +Factors affecting timeline: +- Data volume +- Network speed +- Complexity of setup +- User training needs + +## Next Steps + +- [Common Concepts](./common-concepts.md) - General migration principles +- [Validation](./validation.md) - Testing procedures \ No newline at end of file diff --git a/docs/src/chapter-14-migration/overview.md b/docs/src/chapter-14-migration/overview.md new file mode 100644 index 00000000..814bad3c --- /dev/null +++ b/docs/src/chapter-14-migration/overview.md @@ -0,0 +1,166 @@ +# Migration Overview + +Understanding the fundamental shift from cloud services to self-hosted components is crucial for successful enterprise migration to General Bots. + +## The Architecture Paradigm Shift + + + Enterprise Migration Architecture + + + + +## Core Migration Principles + +### 1. Component-Based Architecture + +Unlike monolithic cloud services, General Bots uses discrete, installable components: + +```bash +# Install individual components as needed +./botserver package install mail # Email service +./botserver package install drive # File storage +./botserver package install directory # User management +./botserver package install meet # Video conferencing +``` + +### 2. Data Sovereignty + +Your data stays under your control: +- **On-premises**: Physical servers in your data center +- **Private cloud**: Your own cloud infrastructure +- **Hybrid**: Mix of local and controlled cloud resources + +### 3. Standard Protocols + +All components use industry-standard protocols: +- **Storage**: S3 API (MinIO) +- **Email**: SMTP/IMAP/JMAP (Stalwart) +- **Auth**: OIDC/SAML/LDAP (Zitadel) +- **Video**: WebRTC (LiveKit) + +### 4. Knowledge Base Integration + +Transform static documents into searchable knowledge: + +```basic +' Convert SharePoint documents to searchable KB +USE KB "company_docs" +ADD WEBSITE "https://sharepoint.company.com/docs" + +' Now accessible via natural language +answer = HEAR "What's our vacation policy?" +' System automatically searches KB and responds +``` + +## Migration Phases + +### Phase 1: Assessment (Week 1-2) +- Inventory current services and usage +- Identify dependencies and integrations +- Size infrastructure requirements +- Create migration timeline + +### Phase 2: Infrastructure Setup (Week 2-3) +- Deploy General Bots instance +- Install required components +- Configure authentication (Zitadel) +- Setup storage (MinIO) + +### Phase 3: Data Migration (Week 3-6) +- User accounts and permissions +- Email and calendars +- Files and documents +- Knowledge base content + +### Phase 4: Process Migration (Week 6-8) +- Convert workflows to .gbdialog scripts +- Setup automation rules +- Configure integrations +- Train AI models on your data + +### Phase 5: Validation & Training (Week 8-10) +- Test all migrated services +- User acceptance testing +- Training sessions +- Documentation update + +### Phase 6: Cutover (Week 10-12) +- Gradual user migration +- Monitor and support +- Decommission old services +- Post-migration optimization + +## Cost Comparison + +### Enterprise Cloud Services +``` +Microsoft 365 E3: $36/user/month +Google Workspace: $12/user/month ++ API costs ++ Storage overages ++ Add-on features += $40-60/user/month typical +``` + +### General Bots Self-Hosted +``` +Infrastructure: ~$500/month (100 users) +Maintenance: ~$200/month += $7/user/month +Savings: 85%+ +``` + +## Key Differentiators + +### Mega-Prompts vs Components + +| Copilot/Gemini (Mega-Prompts) | General Bots (Components) | +|-------------------------------|---------------------------| +| Black box AI responses | Transparent, traceable logic | +| Cloud processing required | Local or hybrid processing | +| Fixed capabilities | Extensible via .gbdialog | +| Subscription model | One-time deployment | +| Vendor-controlled updates | You control updates | + +### Data Control + +| Cloud Services | General Bots | +|---------------|--------------| +| Data on vendor servers | Data on your servers | +| Vendor terms apply | Your policies only | +| Potential AI training use | No external AI training | +| Compliance uncertainty | Full compliance control | + +## Success Metrics + +Monitor these KPIs during and after migration: + +- **Performance**: Response times, system availability +- **Adoption**: User login frequency, feature usage +- **Cost**: Total cost of ownership reduction +- **Security**: Incident reduction, audit compliance +- **Productivity**: Task completion times + +## Prerequisites Checklist + +Before starting migration: + +- [ ] Executive sponsorship secured +- [ ] Migration team assembled +- [ ] Infrastructure provisioned +- [ ] Backup strategy defined +- [ ] Rollback plan documented +- [ ] User communication plan ready +- [ ] Training materials prepared + +## Next Steps + +1. Review [Common Migration Concepts](./common-concepts.md) for shared tools and patterns +2. Choose your migration path: + - [Microsoft 365 Migration](./microsoft-365.md) + - [Google Workspace Migration](./google-workspace.md) +3. Explore [Automation Scripts](./automation.md) for streamlined migration +4. Plan [Knowledge Base Migration](./kb-migration.md) for document conversion + +The journey from cloud dependency to self-hosted freedom starts with understanding these core concepts. General Bots provides not just an alternative, but a fundamentally better approach to enterprise computing. \ No newline at end of file diff --git a/docs/src/chapter-14-migration/validation.md b/docs/src/chapter-14-migration/validation.md new file mode 100644 index 00000000..0780f8eb --- /dev/null +++ b/docs/src/chapter-14-migration/validation.md @@ -0,0 +1,81 @@ +# Validation + +Post-migration testing and verification procedures. + +## Overview + +Validation ensures that migrated systems and data are functioning correctly in the new self-hosted environment. + +## Key Areas to Validate + +### 1. User Access +- Can users log in? +- Are permissions correct? +- Does SSO work if configured? + +### 2. Data Integrity +- Are all files present? +- Do file sizes match? +- Are timestamps preserved? + +### 3. Email Functionality +- Can users send/receive email? +- Are folders and messages intact? +- Do aliases work? + +### 4. Document Search +- Does search return results? +- Are documents accessible? +- Is indexing complete? + +## Testing Approach + +### Smoke Testing +Quick tests to verify basic functionality: +- Login test +- Send test email +- Search for known document +- Access key files + +### User Acceptance Testing +Have actual users verify: +- Their data is present +- Workflows still function +- Performance is acceptable + +### Load Testing +If applicable: +- Concurrent user access +- Large file transfers +- Search performance + +## Common Issues + +### Authentication Problems +- Wrong credentials +- Certificate issues +- Domain configuration + +### Missing Data +- Incomplete transfers +- Permission errors +- Format incompatibilities + +### Performance Issues +- Slow searches +- Network bottlenecks +- Resource constraints + +## Validation Checklist + +- [ ] All users can authenticate +- [ ] Email send/receive works +- [ ] Files are accessible +- [ ] Search returns results +- [ ] Backups are working +- [ ] Monitoring is active + +## Next Steps + +- [Overview](./overview.md) - Return to migration overview +- [Common Concepts](./common-concepts.md) - Migration fundamentals \ No newline at end of file diff --git a/docs/src/custom.css b/docs/src/custom.css new file mode 100644 index 00000000..b93d68fa --- /dev/null +++ b/docs/src/custom.css @@ -0,0 +1,215 @@ +/* Custom CSS for Rust Documentation - Fixes SVG text rendering */ + +/* CSS Custom Properties that can be injected into SVG documents */ +:root { + --svg-main-text-color: #1a1a1a; + --svg-secondary-text-color: #666; + --svg-arrow-color: #666; +} + +/* Force black text in light/rust themes */ +.light, +.rust { + --svg-main-text-color: #1a1a1a !important; + --svg-secondary-text-color: #666 !important; + --svg-arrow-color: #666 !important; +} + +/* Dark theme overrides */ +.ayu, +.coal, +.navy, +.dark, +.theme--dark { + --svg-main-text-color: #ffffff !important; + --svg-secondary-text-color: #b0b0b0 !important; + --svg-arrow-color: #b0b0b0 !important; +} + +/* For inline SVGs - direct styling */ +.light svg .main-text, +.rust svg .main-text { + fill: #1a1a1a !important; +} + +.light svg .secondary-text, +.rust svg .secondary-text { + fill: #666 !important; +} + +.light svg .arrow-head, +.rust svg .arrow-head { + fill: #666 !important; +} + +.light svg .arrow-line, +.rust svg .arrow-line { + stroke: #666 !important; +} + +/* Dark theme inline SVG overrides */ +.ayu svg .main-text, +.coal svg .main-text, +.navy svg .main-text, +.dark svg .main-text, +.theme--dark svg .main-text { + fill: #ffffff !important; +} + +.ayu svg .secondary-text, +.coal svg .secondary-text, +.navy svg .secondary-text, +.dark svg .secondary-text, +.theme--dark svg .secondary-text { + fill: #b0b0b0 !important; +} + +.ayu svg .arrow-head, +.coal svg .arrow-head, +.navy svg .arrow-head, +.dark svg .arrow-head, +.theme--dark svg .arrow-head { + fill: #b0b0b0 !important; +} + +.ayu svg .arrow-line, +.coal svg .arrow-line, +.navy svg .arrow-line, +.dark svg .arrow-line, +.theme--dark svg .arrow-line { + stroke: #b0b0b0 !important; +} + +/* Object element styling for better SVG integration */ +object[type="image/svg+xml"] { + display: block; + max-width: 100%; + height: auto; + pointer-events: none; /* Prevent interaction issues */ + background: transparent !important; +} + +/* Ensure object fallback images are hidden when object loads */ +object[type="image/svg+xml"] img { + display: none; +} + +/* Ensure SVG containers have transparent background */ +.content object, +.content img[src$=".svg"] { + background: transparent !important; +} + +/* Remove any background from SVG wrappers */ +.content > div:has(object[type="image/svg+xml"]) { + background: transparent !important; +} + +/* Fix for mdBook's content area */ +.content object[type="image/svg+xml"] { + margin: 1em 0; + background-color: transparent !important; +} + +/* Override any mdBook theme backgrounds for SVG areas */ +.rust .content object[type="image/svg+xml"], +.light .content object[type="image/svg+xml"], +.coal .content object[type="image/svg+xml"], +.navy .content object[type="image/svg+xml"], +.ayu .content object[type="image/svg+xml"] { + background-color: transparent !important; +} + +/* Inject CSS variables into object document via JavaScript */ +.light object[type="image/svg+xml"], +.rust object[type="image/svg+xml"] { + color-scheme: light; +} + +.ayu object[type="image/svg+xml"], +.coal object[type="image/svg+xml"], +.navy object[type="image/svg+xml"], +.dark object[type="image/svg+xml"] { + color-scheme: dark; +} + +/* Additional mdBook theme detection */ +body:not([class*="theme"]) svg .main-text, +body:not([class*="ayu"]):not([class*="coal"]):not([class*="navy"]) + svg + .main-text { + fill: var(--svg-main-text-color, #1a1a1a) !important; +} + +body:not([class*="theme"]) svg .secondary-text, +body:not([class*="ayu"]):not([class*="coal"]):not([class*="navy"]) + svg + .secondary-text { + fill: var(--svg-secondary-text-color, #666) !important; +} + +body:not([class*="theme"]) svg .arrow-head, +body:not([class*="ayu"]):not([class*="coal"]):not([class*="navy"]) + svg + .arrow-head { + fill: var(--svg-arrow-color, #666) !important; +} + +body:not([class*="theme"]) svg .arrow-line, +body:not([class*="ayu"]):not([class*="coal"]):not([class*="navy"]) + svg + .arrow-line { + stroke: var(--svg-arrow-color, #666) !important; +} + +/* Print styles */ +@media print { + svg .main-text { + fill: #1a1a1a !important; + } + + svg .secondary-text { + fill: #666 !important; + } + + svg .arrow-head { + fill: #666 !important; + } + + svg .arrow-line { + stroke: #666 !important; + } +} + +/* Accessibility improvements */ +@media (prefers-contrast: high) { + svg .main-text { + fill: #000000 !important; + } + + .dark svg .main-text, + .ayu svg .main-text, + .coal svg .main-text, + .navy svg .main-text { + fill: #ffffff !important; + } +} + +/* Custom scrollbar for SVG containers if needed */ +object[type="image/svg+xml"]::-webkit-scrollbar { + width: 8px; + height: 8px; +} + +object[type="image/svg+xml"]::-webkit-scrollbar-track { + background: transparent; +} + +object[type="image/svg+xml"]::-webkit-scrollbar-thumb { + background: rgba(0, 0, 0, 0.2); + border-radius: 4px; +} + +.dark object[type="image/svg+xml"]::-webkit-scrollbar-thumb { + background: rgba(255, 255, 255, 0.2); +} diff --git a/docs/src/theme-sync.js b/docs/src/theme-sync.js new file mode 100644 index 00000000..5d5446e6 --- /dev/null +++ b/docs/src/theme-sync.js @@ -0,0 +1,115 @@ +// Theme synchronization for SVG documents in object elements +(function() { + 'use strict'; + + // Function to update SVG theme + function updateSVGTheme(objectElement) { + try { + const svgDoc = objectElement.contentDocument; + if (!svgDoc) return; + + const html = document.documentElement; + const body = document.body; + const svgRoot = svgDoc.documentElement; + + // Detect current theme + const isRust = html.classList.contains('rust') || body.classList.contains('rust'); + const isLight = html.classList.contains('light') || body.classList.contains('light'); + const isDark = html.classList.contains('dark') || + html.classList.contains('ayu') || + html.classList.contains('navy') || + html.classList.contains('coal') || + body.classList.contains('theme--dark'); + + // Set CSS variables in SVG + if (isRust || isLight) { + svgRoot.style.setProperty('--main-text-color', '#1a1a1a'); + svgRoot.style.setProperty('--secondary-text-color', '#666'); + svgRoot.style.setProperty('--arrow-color', '#666'); + } else if (isDark) { + svgRoot.style.setProperty('--main-text-color', '#ffffff'); + svgRoot.style.setProperty('--secondary-text-color', '#b0b0b0'); + svgRoot.style.setProperty('--arrow-color', '#b0b0b0'); + } + + // Also try to call the SVG's internal updateTheme function if it exists + if (svgDoc.defaultView && typeof svgDoc.defaultView.updateTheme === 'function') { + svgDoc.defaultView.updateTheme(); + } + } catch (e) { + // Silent fail for cross-origin or other errors + console.debug('Could not update SVG theme:', e); + } + } + + // Function to initialize all SVG objects + function initializeSVGThemes() { + const objects = document.querySelectorAll('object[type="image/svg+xml"]'); + objects.forEach(obj => { + // Wait for object to load + if (obj.contentDocument) { + updateSVGTheme(obj); + } else { + obj.addEventListener('load', () => updateSVGTheme(obj)); + } + }); + } + + // Watch for theme changes + function watchThemeChanges() { + const observer = new MutationObserver((mutations) => { + // Check if class attribute changed + const classChanged = mutations.some(m => + m.type === 'attributes' && m.attributeName === 'class' + ); + + if (classChanged) { + initializeSVGThemes(); + } + }); + + // Observe both html and body elements + observer.observe(document.documentElement, { + attributes: true, + attributeFilter: ['class'] + }); + + observer.observe(document.body, { + attributes: true, + attributeFilter: ['class'] + }); + } + + // Initialize on DOM ready + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', () => { + initializeSVGThemes(); + watchThemeChanges(); + }); + } else { + initializeSVGThemes(); + watchThemeChanges(); + } + + // Re-initialize on mdBook theme change (mdBook specific) + if (window.playground_text) { + // mdBook is present + const themeToggle = document.getElementById('theme-toggle'); + if (themeToggle) { + themeToggle.addEventListener('click', () => { + setTimeout(initializeSVGThemes, 100); + }); + } + + // Also watch for theme picker changes + const themeChoices = document.querySelectorAll('#theme-list button'); + themeChoices.forEach(btn => { + btn.addEventListener('click', () => { + setTimeout(initializeSVGThemes, 100); + }); + }); + } + + // Expose function globally for manual updates + window.updateAllSVGThemes = initializeSVGThemes; +})();