Skill Base Web Server Deployment

This skill guides you through setting up and operating the Skill Base platform server. Requires Node.js >= 18.

When to Use This Skill

• When users request private deployment, hosting, or running the Skill Base server (npx skill-base or Docker).
• When users ask about Skill Base server host/port configuration (-h, -p), data directory (-d), or how to back up the database.

When NOT to Use This Skill

• When users want to use the skb command to search, install, or publish specific skills (refer to skill-base-cli instead).
• When users ask about Docker, ports, or database configuration for non-Skill Base projects (avoid misuse).

Quick Start (npm package)

# Recommended: fix the data directory for easy backup and migration
npx skill-base -d ./skill-data -p 8000

Default port is 8000; if -d is not specified, data will be stored in npm cache-related paths. In production, always use `-d` to point to a specific directory.

Startup Options (npx skill-base)

Intranet or local hardening example: npx skill-base --host 127.0.0.1 -p 8000 -d ./data

Subpath deployment example: npx skill-base --base-path /skills/ -p 8000

Debug mode example: npx skill-base -v -d ./data

First Access

When no administrator exists, opening the site in a browser will launch the initialization wizard: create a system administrator account and password. Afterward, team members need to be added by the administrator, and users log in via Web and CLI.

Platform Capabilities (Post-Deploy)

After the server is running, the Web UI and CLI share the same backend:

Collections are flat recommendation packs maintained by admins — they link to skills via collection_skills, not a folder hierarchy. Clients install the whole pack in one zip download.

Development/Production Run from Source Directory

pnpm install
pnpm start
# Or for development: `pnpm dev`

Docker (Recommended for Production)

Build in the repository root directory containing the Dockerfile:

docker build -t skill-base .

Image conventions: DATA_DIR=/data, DATABASE_PATH=/data/skills.db, PORT=8000. For host persistence, mount to `/data` inside the container:

docker run -d -p 8000:8000 -v "$(pwd)/data:/data" --name skill-base-server skill-base

If you need to change the port, map both host and container ports and set PORT, e.g., -p 3000:3000 -e PORT=3000.

Data Directory Structure (Backup)

After specifying -d or mounting /data, typical contents:

data/
├── skills.db
├── skills.db-wal
└── skills/
    └── <skill-id>/
        └── vYYYYMMDD.HHmmss.zip

Backup: Simply copy the entire data directory during low write activity or off-peak hours.

Troubleshooting Tips

• Port: Ensure firewall/security groups allow PORT; cloud hosts need to allow corresponding inbound traffic.
• CLI can't connect: Client uses skb init --server <root URL> (without /api); verify the site is accessible from that machine.
• Permissions: The -d path must be readable/writable by the process; for Docker volumes, check host directory permissions.

Relationship with skill-base-cli

After deploying the Web server, users on the client side use `skb` pointing to the same site root URL; see the skill-base-cli skill within the project.