Content
# Tool List
## Based on the official pre-built image, including Chinese localization and MCP service.
The container's self-start strategy is controlled by `.env`'s `RESTART_POLICY`:
- Set to `no` for local testing (do not self-start)
- Set to `unless-stopped` for server deployment (self-start at boot)
## Directory Structure
```
.
├── .env # Environment variables (3 mandatory items, see below)
├── docker-compose.yml # Orchestration file
├── po2jed.py # Translation regeneration tool (use after modifying .po)
└── docker/
├── docker-entrypoint-initdb.d/
│ └── init-superset-db.sh # Postgres initialization (create examples database)
├── pythonpath_dev/
│ └── superset_config.py # Superset configuration (including Chinese LANGUAGES)
└── translations/zh/LC_MESSAGES/
├── messages.po # Chinese translation source file (editable)
└── messages.json # Frontend-loaded translation (generated by po2jed.py)
```
## Server Deployment
### Prerequisites
The server must have Docker and Docker Compose installed:
```bash
docker --version # Requires 20+
docker compose version # Requires v2+
```
### Deployment Steps
**1. Upload the entire directory to the server**
Upload `.env`, `docker-compose.yml`, `po2jed.py`, and the `docker/` directory to the same server directory.
**2. Edit `.env`, modify 3 mandatory items**
```bash
vim .env
```
Mandatory modifications (marked with `[必改]` in the file):
| Variable | Description | Local testing | Server |
|------|------|----------|--------|
| `REGISTRY_MIRROR` | Image accelerator. Leave blank for direct Docker Hub access; fill in accelerator for domestic servers | `docker.m.daocloud.io/` | `docker.m.daocloud.io/` |
| `SUPERSET_SECRET_KEY` | Production key, must be replaced with a random value |随意 | Run `openssl rand -base64 42` to generate |
| `ADMIN_PASSWORD` | Administrator password | `admin` | Change to a strong password |
| `RESTART_POLICY` | Container self-start strategy | `no` (do not self-start) | `unless-stopped` (self-start at boot) |
Optional (change if port is occupied):
```env
SUPERSET_PORT=8088 # Superset web port
MCP_PORT=5008 # MCP service port
```
**3. Start**
```bash
docker compose up -d
```
The first startup may take longer (database initialization and example data loading, approximately 3-5 minutes).
Check the initialization progress:
```bash
docker logs -f superset_init # Initialization successful when "Complete" is displayed
```
**4. Access**
```
http://server IP:8088
Username: admin
Password: `.env`'s `ADMIN_PASSWORD` (default `admin`)
```
Switch to Chinese: After logging in, visit `http://server IP:8088/lang/zh` or select Chinese from the language selector in the top right corner.
## Function Description
### Chinese Localization
- Frontend loads translation via `/superset/language_pack/zh/` endpoint (4050 items)
- Translation source file: `docker/translations/zh/LC_MESSAGES/messages.po`
- If a translation is inaccurate, edit `.po` and regenerate:
```bash
# Execute po2jed.py in the container to regenerate messages.json
docker exec -i superset_app python - < po2jed.py
# Restart app container (frontend will re-fetch)
docker compose restart superset
```
### MCP Service (for AI invocation)
- Endpoint: `http://server IP:5008/mcp` (streamable-http protocol)
- Allow AI clients (Claude/Cursor, etc.) to operate Superset via MCP: query datasets, generate charts, execute SQL, build dashboards, etc.
- **Production-level security**: Custom API Key authentication, 401 unauthorized for invalid or incorrect keys
#### API Key (configured once, permanently valid)
MCP authentication uses a fixed API Key (instead of expiring JWT tokens). A preset key is provided in `.env`:
```env
MCP_API_KEY=ui_6g8ltD4JPW8ZWZgBdhUTNmL8h5zYFYAd-zBT8oltjiv6S3ahNa_0d
```
Generate a new key (recommended for production environments):
```bash
python -c "import secrets; print(secrets.token_urlsafe(42))"
```
#### Client Connection (with API Key)
Client configuration (Claude Desktop / Cursor, etc.), add API Key to headers:
```json
{
"mcpServers": {
"superset": {
"url": "http://server IP:5008/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer <your MCP_API_KEY>"
}
}
}
}
```
The API Key never expires and remains valid after configuration. To change the key, update `.env`'s `MCP_API_KEY` and restart the `mcp` container:
```bash
docker compose restart superset-mcp
```
## Common Commands
```bash
docker compose up -d # Start (no self-start, manual execution required)
docker compose down # Stop (preserve data)
docker compose down -v # Stop and clear all data
docker compose logs -f superset # View Superset logs
docker compose ps # View container status
```
## Service List
| Container | Port | Function |
|------|------|------|
| superset_app | 8088 | Superset web service |
| superset_mcp | 5008 | MCP service (AI invocation) |
| superset_worker | - | Celery asynchronous tasks |
| superset_worker_beat | - | Celery scheduled tasks |
| superset_db | - | PostgreSQL 17 metadata database |
| superset_cache | - | Redis cache |
The self-start strategy for all containers is determined by `.env`'s `RESTART_POLICY`:
- Local testing `RESTART_POLICY=no`: Do not self-start after computer restart, manual execution required
- Server `RESTART_POLICY=unless-stopped`: **Self-start at boot**
## Troubleshooting
**Startup failure, check logs:**
```bash
docker compose logs superset_init # Initialization failure
docker compose logs superset # App startup failure
```
**Image pull timeout:**
- Confirm `.env`'s `REGISTRY_MIRROR` setting is correct
- Domestic servers use `docker.m.daocloud.io/` or `docker.1ms.run/`
- Test connectivity: `curl -I https://docker.m.daocloud.io/v2/`
**Worker startup failure (missing psycopg2):**
- Normal phenomenon, compose has automatic installation configured, wait 30-60 seconds
- Check: `docker logs superset_worker`
**Port occupied:**
```bash
# Modify `.env`'s `SUPERSET_PORT` or `MCP_PORT`, then:
docker compose up -d
```
**Reset all data:**
```bash
docker compose down -v
docker compose up -d
```
