DeepSite v2 Setup and Usage Guide

1. Ensure all prerequisites are installed and up to date

   • Node.js ≥ v14.17.0 (download from https://nodejs.org)
   • Python ≥ 3.8 (download from https://www.python.org)
   • Git ≥ v2.30 (https://git-scm.com)
   • A POSIX-compliant shell (bash, zsh) or PowerShell on Windows
   • At least 4 GB of RAM and 1 GB free disk space

2. Install DeepSite v2 globally via npm

   Bash
   1# Using npm
   2npm install --global deepsite@latest
   3
   4# Or via Yarn
   5yarn global add deepsite@latest
   6

3. Verify installation and environment health

   Bash
   1deepsite doctor --output=json | jq .
   2

   • The doctor command runs environment diagnostics, checking: • Node.js/Python versions • Git availability • Network connectivity to default AI endpoints • Permissions for reading/writing the project folder

   Expected JSON schema:

   Json
   1{
   2  "status": "ok",
   3  "checks": [
   4    { "name": "node_version", "status": "pass", "value": "v16.5.0" },
   5    { "name": "python_version", "status": "pass", "value": "3.9.2" },
   6    { "name": "git", "status": "pass", "value": "2.33.1" },
   7    { "name": "network", "status": "pass", "details": "api.fireworks.ai reachable" }
   8  ]
   9}
   10

   • To auto-fix common issues (missing deps, outdated config):

   Bash
   1deepsite doctor --fix
   2

4. Scaffold a new project

   Bash
   1mkdir my-site
   2cd my-site
   3deepsite scaffold \
   4  --template=blog \
   5  --lang=en \
   6  --output-format=md
   7

   • --template=blog selects the official blog starter. • Generated folder structure:

   Text
   1my-site/
   2├── content/
   3│   └── index.md
   4├── .deepsite.yml
   5├── package.json
   6└── deepsite.lock
   7

5. Migrate an existing DeepSite v1 project • Preview changes (dry run):

   Bash
   1deepsite migrate \
   2  --from=1.x \
   3  --to=2.x \
   4  --dry-run \
   5  --output=summary.txt
   6

   • Apply migration:

   Bash
   1deepsite migrate \
   2  --from=1.x \
   3  --to=2.x \
   4  --config=.deepsite.yml
   5

   • Migration updates:

   • .deepsite.yml schema changes (keys renamed, new defaults)
   • CLI flags adjustments
   • Template file rewrites (Handlebars → Enhanced Templating)
   • Lockfile upgrades

6. Initialize Git and commit scaffold

   Bash
   1git init
   2git add .
   3git commit -m "chore: scaffold DeepSite v2 blog"
   4

7. First build and local serve

   Bash
   1deepsite serve --headless --port=4000
   2

   • Open http://localhost:4000 in your browser for live preview • Default live-reload watches content/ and .deepsite.yml

8. Troubleshooting common setup errors

   • “doctor: network unreachable”: confirm proxy and firewall allow outbound to *.fireworks.ai.
   • “scaffold: template not found”: list available templates via deepsite scaffold --list.
   • “serve: EADDRINUSE”: change port with --port=PORT_NUMBER.
   • Missing Python: install via package manager or pyenv, then rerun deepsite doctor --fix.

9. CI-friendly installation (example: GitHub Actions)

   Yaml
   1name: Build and Preview
   2
   3on: [push]
   4
   5jobs:
   6  build:
   7    runs-on: ubuntu-latest
   8    steps:
   9      - uses: actions/checkout@v3
   10
   11      - name: Install Node.js
   12        uses: actions/setup-node@v3
   13        with:
   14          node-version: '16'
   15
   16      - name: Install Python
   17        uses: actions/setup-python@v4
   18        with:
   19          python-version: '3.9'
   20
   21      - name: Install DeepSite
   22        run: npm install -g deepsite@latest
   23
   24      - name: Run doctor
   25        run: deepsite doctor
   26
   27      - name: Build site
   28        run: deepsite build --output=dist
   29
   30      - name: Upload site
   31        uses: actions/upload-artifact@v3
   32        with:
   33          name: site-dist
   34          path: dist
   35

10. Continuous setup validation

• Schedule weekly doctor checks in CI for dependency drift.
• Incorporate deepsite audit into build pipeline for content best-practices.

---

Core Architecture & Model Integration

1. Inference pipeline overview • DeepSite v2 relies on a layered model strategy:

   1. Local embeddings store (SQLite + FAISS)
   2. Default AI engine: Fireworks AI v3 (configured via --model=fireworks-v3)
   3. Third-party LLM fallback (OpenAI GPT, Anthropic Claude) • Requests flow:
   • User issues deepsite generate or serve → /generate
   • CLI loads .deepsite.yml
   • Query passed to local cache; hits bypass AI calls
   • Misses routed through primary model → fallback chain
   • Response templated & written to disk

2. Headless daemon & API modes • Start in daemon mode:

   Bash
   1deepsite serve --headless --daemon \
   2  --port=5000 \
   3  --model=fireworks-v3 \
   4  --cache-dir=/data/deepsite/cache
   5

   • REST endpoints:

   • POST /generate • Payload:

     Json
     1{
     2  "prompt": "Generate homepage content for a tech blog",
     3  "lang": "en",
     4  "options": { "maxTokens": 512 }
     5}
     6

     • Response:

     Json
     1{
     2  "status": "success",
     3  "content": "# Welcome to My Tech Blog\n..."
     4}
     5

   • GET /status • Returns health and usage metrics:

     Json
     1{
     2  "uptime": 12345,
     3  "model": "fireworks-v3",
     4  "cacheHits": 42,
     5  "cacheMisses": 17
     6}
     7

   • DELETE /cache • Clears embeddings and temporary files • Response: { "status": "cache_cleared" }

   • GraphQL schema (headless mode):

   Graphql
   1type Query {
   2  status: Status
   3}
   4
   5type Mutation {
   6  generate(input: GenerateInput!): GeneratePayload
   7  clearCache: CachePayload
   8}
   9
   10type Status {
   11  uptime: Int
   12  model: String
   13  metrics: Metrics
   14}
   15
   16type Metrics {
   17  cacheHits: Int
   18  cacheMisses: Int
   19}
   20
   21input GenerateInput {
   22  prompt: String!
   23  options: JSON
   24}
   25
   26type GeneratePayload {
   27  content: String
   28  rawResponse: JSON
   29}
   30
   31type CachePayload {
   32  success: Boolean
   33}
   34

3. Default model configuration & fallback chain

   • Configure primary/fallback in .deepsite.yml:

     Yaml
     1model:
     2  primary: fireworks-v3
     3  fallbacks:
     4    - openai-gpt-4
     5    - anthropic-claude-2
     6

   • CLI override:

     Bash
     1deepsite generate \
     2  --model=openai-gpt-4 \
     3  --max-tokens=1024
     4

   • Fallback sequence algorithm:
     1. Attempt primary model call
     2. On network or rate-limit error, iterate through fallbacks[]
     3. On total failure, return HTTP 503 (daemon mode) or error code

4. Cursor UI micro-frontend

   • Install:

     Bash
     1npm install @deepsite/cursor-ui
     2

   • Integrate into existing web app (React example):

     Js
     1import React from 'react';
     2import { CursorUI } from '@deepsite/cursor-ui';
     3
     4function App() {
     5  return (
     6    <div>
     7      <CursorUI
     8        apiUrl="http://localhost:5000"
     9        cursorPort={6789}
     10        lang="en"
     11      />
     12    </div>
     13  );
     14}
     15
     16export default App;
     17

   • WebSocket handshake:

     Js
     1const socket = new WebSocket('ws://localhost:6789');
     2socket.onopen = () => {
     3  socket.send(JSON.stringify({
     4    type: 'init',
     5    lang: 'en',
     6  }));
     7};
     8socket.onmessage = ({ data }) => {
     9  const msg = JSON.parse(data);
     10  if (msg.type === 'cursor_move') {
     11    // update editor cursor
     12  }
     13};
     14

5. Plugin adapter system

   • Discover installed adapters:

     Bash
     1deepsite plugin list
     2

     • Output:

     Text
     1✔ deepsite-plugin-markdown (npm)
     2✔ deepsite-plugin-python (PyPI)
     3✔ deepsite-plugin-wasm (WASM)
     4

   • Add new adapter:

     Bash
     1deepsite plugin add deepsite-plugin-wasm --source=wasm
     2

   • Adapter lifecycle hooks:

     Js
     1module.exports = {
     2  name: 'deepsite-plugin-example',
     3  onInit({ config, logger }) { /* set up */ },
     4  onGenerate({ prompt, model, next }) {
     5    // modify prompt
     6    return next({ prompt: prompt + ' [enhanced]' });
     7  },
     8  onFinish({ result }) { /* post-process result */ },
     9};
     10

6. CLI command reference

   Text
   1Usage: deepsite [command] [options]
   2
   3Commands:
   4  scaffold      Generate project boilerplate
   5  migrate       Upgrade project from v1 → v2
   6  serve         Run headless daemon (REST & GraphQL)
   7  build         Render static content
   8  generate      One-off content generation
   9  audit         Run best-practice audits
   10  doctor        Check & fix environment issues
   11  plugin        Manage plugins (add | remove | list)
   12  config        Get | set | validate configuration
   13
   14Global Options:
   15  --config <file>        Path to .deepsite.yml
   16  --model <name>         Override default model
   17  --lang <code>          Content language (e.g., en, es, fr)
   18  --output-format <fmt>  md | html | json
   19  --verbose              Enable detailed logs
   20

---

Configuration & Customization

1. .deepsite.yml schema

   Yaml
   1# Core settings
   2model:
   3  primary: fireworks-v3
   4  fallbacks:
   5    - openai-gpt-4
   6    - anthropic-claude-2
   7
   8lang: en
   9output-format: md
   10
   11# Plugin declarations
   12plugins:
   13  - deepsite-plugin-markdown
   14  - deepsite-plugin-wasm
   15
   16# Cursor UI settings
   17cursor:
   18  enabled: true
   19  port: 6789
   20
   21# Caching and storage
   22cache-dir: .cache
   23cache-ttl: 86400  # seconds
   24
   25# Audit report options
   26audit:
   27  accessible: true
   28  seo: true
   29  compliance: true
   30  output: html
   31

   • Validate schema before running:

   Bash
   1deepsite config validate --config .deepsite.yml
   2

   • Output (human):

   Text
   1✔ model.primary is valid
   2✔ lang is supported (en)
   3✖ plugins[1] not found: deepsite-plugin-nonexistent
   4

2. Templating layer

   • Default uses Handlebars syntax; supports:
     • {{title}}, {{date}}, {{#each items}}…{{/each}}
     • Custom helpers via template.helpers.js:

       Js
       1module.exports = {
       2  uppercase: (str) => str.toUpperCase(),
       3  formatDate: (d, fmt) => require('date-fns').format(new Date(d), fmt),
       4};
       5

   • Reference in markdown:

     Markdown
     1# {{title}}
     2
     3Published on {{formatDate date "yyyy-MM-dd"}}
     4
     5{{#each posts}}
     6- [{{this.title}}]({{this.url}})
     7{{/each}}
     8

3. Plugin development and customization

   • Create a new plugin scaffold:

     Bash
     1deepsite plugin create my-plugin
     2

   • Directory structure:

   Text
   1my-plugin/
   2├── index.js
   3├── package.json
   4└── README.md
   5

   • Example index.js:

     Js
     1module.exports = {
     2  name: 'my-plugin',
     3  onInit({ config, logger }) {
     4    logger.info('my-plugin initialized with', config);
     5  },
     6  onGenerate({ prompt, next }) {
     7    const enhanced = prompt + '\nAdd a summary section.';
     8    return next({ prompt: enhanced });
     9  },
     10};
     11

   • Publish to npm:

     Bash
     1npm publish --access public
     2

4. Multi-language support

   • Add languages in config:

     Yaml
     1languages:
     2  - code: en
     3    template: templates/en.hbs
     4  - code: fr
     5    template: templates/fr.hbs
     6

   • Generate per-language output:

     Bash
     1deepsite build --lang=fr
     2

   • Structure output:

   Text
   1dist/
   2├── en/
   3│   └── index.md
   4└── fr/
   5    └── index.md
   6

5. Advanced configuration commands

   • Set a config value:

     Bash
     1deepsite config set cache-ttl 43200
     2

   • Retrieve current setting:

     Bash
     1deepsite config get model.primary
     2

   • Reset to defaults:

     Bash
     1deepsite config reset
     2

6. Configuration migration helper

   • Run config migration:

     Bash
     1deepsite config migrate --from=1.x --to=2.x \
     2  --input=old-config.yml \
     3  --output=.deepsite.yml
     4

   • Combined with --dry-run to preview changes:

     Bash
     1deepsite config migrate --dry-run
     2

---

Advanced Use Cases & Real-World Examples

1. CI/CD integration with audit reports

   • Add audit step in GitHub Actions:

     Yaml
     1- name: Run audit
     2  run: deepsite audit --output=html --dir=dist
     3- name: Upload Audit Report
     4  uses: actions/upload-artifact@v3
     5  with:
     6    name: deepsite-audit
     7    path: dist/audit.html
     8

   • Audit output highlights:
     • SEO issues (missing <title>, <meta description>)
     • Accessibility flags (alt attributes, contrast ratios)
     • Compliance warnings (deprecated HTML tags)

2. Performance tuning & caching strategies

   • Enable persistent SQLite cache in production:

     Yaml
     1cache-dir: /var/lib/deepsite/cache
     2cache-ttl: 2592000  # 30 days
     3

   • Use in-memory LRU for short-lived environments:

     Bash
     1deepsite serve --cache-dir=memory
     2

   • Monitor cache stats via API:

     Bash
     1curl http://localhost:5000/status | jq .metrics
     2

3. Deploying headless daemon behind proxy

   • Nginx config snippet:

     Nginx
     1server {
     2  listen 80;
     3  server_name deepsite.example.com;
     4
     5  location / {
     6    proxy_pass http://127.0.0.1:5000;
     7    proxy_http_version 1.1;
     8    proxy_set_header Upgrade $http_upgrade;
     9    proxy_set_header Connection 'upgrade';
     10    proxy_set_header Host $host;
     11  }
     12}
     13

   • TLS via Let’s Encrypt:

     Bash
     1sudo certbot --nginx -d deepsite.example.com
     2

4. Integrating DeepSite into existing static-site pipeline

   • Example with Eleventy (11ty):
     1. Add a pre-build script in package.json:

        Json
        1"scripts": {
        2  "prebuild": "deepsite build --output=content/generated",
        3  "build": "eleventy"
        4}
        5

     2. Reference generated files in 11ty config:

        Js
        1module.exports = function(eleventyConfig) {
        2  eleventyConfig.addPassthroughCopy("content/generated");
        3};
        4

     3. Run:

        Bash
        1npm run prebuild
        2npm run build
        3

5. Case study: migrating a corporate blog

   • Source: InfoQ article “Scaling Content Ops with DeepSite v2” (2024)
   • Steps followed:
     1. Initial audit of existing Markdown → deepsite audit --dir=old-blog
     2. Bulk migration: deepsite migrate --from=1.x --to=2.x --dir=old-blog --output=migrated
     3. Validation via deepsite doctor in CI
     4. Integration with enterprise LLM (Anthropic) using --model=anthropic-claude-2
     5. Final audit and accessibility report generation

6. Production readiness checklist

   • ✅ Environment health: deepsite doctor --fix
   • ✅ Config validation: deepsite config validate
   • ✅ Audit reports: deepsite audit --output=html
   • ✅ Load testing: simulate concurrent /generate calls
   • ✅ Monitoring & Alerts: wrap /status in Prometheus exporter

7. Troubleshooting & best practices

   • If model calls fail under load, increase retry count:

     Yaml
     1model:
     2  retries: 3
     3  backoff: exponential
     4

   • For large sites, shard cache by date:

     Yaml
     1cache-dir: .cache/{{year}}/{{month}}
     2

   • Use --verbose to trace plugin execution:

     Bash
     1deepsite generate --verbose
     2