Docker Widget

Self-hosted FastAPI + Vite chat widget bundled in a single Docker container. Embed with a floating button or inline script tag on any site.

A self-contained chat widget that bundles a FastAPI backend and a Vite-built frontend into a single Docker container. Drop it onto any server, point a script tag at it, and you get either a floating chatbot (Intercom-style) or an inline embed - no Vercel account, no Node toolchain in production.

Source: github.com/Vaquill-AI/integrations/widget.

If you only need a US-only marketing-site widget and prefer Vercel over Docker, the leaner Embedded Chat Widget is a better fit. Pick this one when you want self-hosting, a floating button, or a configurable jurisdiction.

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 RAG mode, widget title, host port, and CORS origins
• Structured legal source rendering: case name, citation, court, excerpt, PDF link
• Health endpoint for Docker / Kubernetes probes

Prerequisites

For Docker deployment:

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

For local development:

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

Quickstart

1. Clone the repo

   git clone https://github.com/Vaquill-AI/integrations.git
   cd integrations/widget
   
2. Set your API key

   cp .env.example .env
   

   Open .env and set:

   VAQUILL_API_KEY=vq_key_your_key_here
   
3. Start with Docker Compose

   docker-compose up -d
   
4. Open the widget

   Visit http://localhost:8000 and ask a test question.

Local development (without Docker)

Run backend and frontend in separate terminals.

Backend (FastAPI)

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

Frontend dev server runs at http://localhost:5173 with hot reload.

Configuration

All configuration is via the .env file:

Variable	Required	Default	Description
VAQUILL_API_KEY	Yes	-	Your Vaquill API key (vq_key_...)
VAQUILL_API_URL	No	https://api.vaquill.ai/api/v1	Vaquill API base URL
WIDGET_MODE	No	standard	Default RAG mode: standard or deep
WIDGET_TITLE	No	Vaquill Legal AI	Title shown in the chat header
HOST_PORT	No	8000	Host port the container is exposed on
ALLOWED_ORIGINS	No	*	CORS origins (comma-separated, or *)

Example production .env:

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

In production, always replace ALLOWED_ORIGINS=* with an explicit list of domains that should be allowed to embed the widget.

Embedding

Option 1 - Floating chatbot (Intercom-style)

Add one script tag before </body> on the host site:

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

A floating button appears in the bottom-right corner. Clicking it opens a slide-in chat panel.

Attribute	Default	Description
data-api-url	http://localhost:8000	Widget backend URL
data-primary-color	#1a56db	Brand accent colour
data-button-size	60px	Floating button diameter
data-chat-width	400px	Panel width on desktop
data-chat-height	600px	Panel height

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

WordPress

<!-- 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>

The examples/ folder in the repo has full working test pages for both embed modes.

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

Modern browsers block mixed content. If your host site is HTTPS, the widget host must be HTTPS too - or the script tag will silently fail to load.

API endpoints

The backend exposes:

Endpoint	Method	Description
/api/chat	POST	Send a message, get an answer + sources
/api/widget/info	GET	Returns widget display configuration (title, suggested questions)
/health	GET	Returns {"status": "ok"} for Docker health checks

Example /api/chat request:

{
  "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"
}

Full schema lives in the Ask API reference.

Troubleshooting

Widget not loading

• 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.

“Failed to fetch” or CORS errors

• 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.

No sources in responses

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

Docker build fails on ARM64 Macs

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

Health check failing

• 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

Embedded Chat Widget

Leaner Next.js variant pinned to the US.

Widget Pro

Multi-thread sidebar, voice mode, gamification.

Ask API

The endpoint this widget proxies.

GitHub

Source code and issue tracker.