Developer guide: this page covers Docker and production deployment details.

• Docker
• Docker Compose

1. Clone the repository

git clone https://github.com/tse-wei-chen/hs-sql-agent.git
cd hs-sql-agent

2. Configure environment

cp .env.example .env

Edit .env with strong, unique secrets:

HMAC_KEY=<your-32+byte-hmac-key>
JWT_KEY=<your-32+byte-jwt-key>

3. Launch

docker compose up -d

4. Verify

docker compose logs -f

• SQLite database is stored at ./data/hsqlagent.db (mounted volume)
• This volume persists across container restarts

docker compose pull
docker compose up -d

The official image is published to GitHub Container Registry:

ghcr.io/tse-wei-chen/hs-sql-agent:latest

The Dockerfile uses a multi-stage build:

1. frontend-builder — builds Nuxt SPA with pnpm generate
2. backend-builder — builds and publishes .NET application, copies frontend dist/ to wwwroot/
3. runtime — minimal ASP.NET runtime image

• Never use default/example keys in production
• Use a secrets manager or secure environment variable injection
• Consider exposing the service behind a reverse proxy (e.g., Nginx, Traefik)

• Default port: 8080
• The MCP endpoint is at /mcp
• The Admin Panel is served as static files at /
• REST API is at /api/*

server {
    listen 443 ssl;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The application exposes health information through:

• HTTP 200 response at the root path (/)
• MCP endpoint at /mcp

• Docker logs: docker compose logs -f
• Audit Logs: Available in the Admin Panel under Audit Logs
• Dashboard: Real-time monitoring in the Admin Panel