Docker Widget

​

What you get

• One container: FastAPI backend serves both the JSON API and the built frontend
• Two embed modes: floating chatbot (bottom-right bubble) or inline <div>
• Single script tag install on the host site - no iframe required
• Configurable widget title, host port, and CORS origins
• Structured statute source rendering: title, section, code, jurisdiction, excerpt, link
• Health endpoint for Docker / Kubernetes probes

​

Prerequisites

• Docker 20.10+ and Docker Compose (download)
• A Vaquill API key (vq_key_...) from app.vaquill.ai/settings/api

• Python 3.10+
• Node.js 18+ and Yarn (npm install -g yarn)
• A Vaquill API key

​

Quickstart

git clone https://github.com/Vaquill-AI/integrations.git
cd integrations/widget

cp .env.example .env

VAQUILL_API_KEY=vq_key_your_key_here

docker-compose up -d

​

Local development (without Docker)

cd backend
pip install -r requirements.txt
VAQUILL_API_KEY=vq_key_... uvicorn main:app --reload --port 8000

cd frontend
yarn install
yarn dev
# proxies /api to http://localhost:8000

​

Configuration

VAQUILL_API_KEY=vq_key_your_key_here
VAQUILL_API_URL=https://api.vaquill.ai/api/v1
WIDGET_MODE=standard
WIDGET_TITLE=Legal Research Assistant
HOST_PORT=8000
ALLOWED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

​

Embedding

​

Option 1 - Floating chatbot (Intercom-style)

<script
  src="https://your-widget-host/embed/script-floating-chatbot.js"
  data-api-url="https://your-widget-host"
  data-primary-color="#1a56db"
></script>

​

Option 2 - Inline embed

<!-- Place this div where you want the chat -->
<div id="vaquill-widget-embed"></div>

<!-- Then include the script -->
<script
  src="https://your-widget-host/embed/script-inline-embed.js"
  data-api-url="https://your-widget-host"
  data-height="640px"
></script>

​

Platform recipes

<!-- 1. Install the "Insert Headers and Footers" plugin -->
<!-- 2. Paste in the footer section, then save -->
<script
  src="https://your-widget-host/embed/script-floating-chatbot.js"
  data-api-url="https://your-widget-host"
></script>

<!-- In Online Store > Themes > Edit Code > theme.liquid, before </body> -->
<script
  src="https://your-widget-host/embed/script-floating-chatbot.js"
  data-api-url="https://your-widget-host"
></script>

<!-- Add a Custom Code element in Settings > Custom Code -->
<script
  src="https://your-widget-host/embed/script-floating-chatbot.js"
  data-api-url="https://your-widget-host"
></script>

import { useEffect } from 'react';

export default function MyApp() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = `${process.env.NEXT_PUBLIC_WIDGET_URL}/embed/script-floating-chatbot.js`;
    script.setAttribute('data-api-url', process.env.NEXT_PUBLIC_WIDGET_URL);
    script.defer = true;
    document.body.appendChild(script);
    return () => document.body.removeChild(script);
  }, []);

  return <YourApp />;
}

​

Deployment

​

Docker Compose (recommended)

docker-compose up -d        # start
docker-compose logs -f      # tail logs
docker-compose down         # stop

​

Behind an Nginx reverse proxy

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

​

SSL with Let’s Encrypt

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
sudo certbot renew --dry-run

​

API endpoints

{
  "message": "What does FRCP Rule 12(b)(6) require?",
  "chatHistory": [
    { "role": "user", "content": "What is a motion to dismiss?" },
    { "role": "assistant", "content": "A motion to dismiss is..." }
  ],
  "mode": "standard"
}

​

Troubleshooting

• Run docker-compose ps to verify the container is up.
• Check HOST_PORT in .env matches the port you are visiting.
• Tail logs with docker-compose logs -f.

• The data-api-url in the embed script must match the widget backend URL exactly (including scheme).
• For testing, set ALLOWED_ORIGINS=* and restart the container.
• In production, set ALLOWED_ORIGINS to a comma-separated list of host-site origins.

• Try a more specific legal query (cite a statute or doctrine by name).
• Verify the API key at app.vaquill.ai/settings/api.

• Ensure Docker Desktop’s Rosetta / ARM support is enabled.
• Check available disk space with df -h.

• Test connectivity from the container: docker-compose exec backend curl https://api.vaquill.ai/api/v1/health.
• Verify VAQUILL_API_KEY and VAQUILL_API_URL are correct.

​

Related