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).
Contributor profiles
The Web UI includes /users/:id and GET /api/v1/users/:user_id/profile. Deploy the rebuilt static/ together with the updated server. No new environment variables or database migration are required: contributions use existing version uploaders and respect skill visibility.
Publish/settings presentation changes require rebuilding web/ into static/; no server configuration or migration is needed.
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)
| Option | Description |
|---|
-p, --port | Listening port, default 8000 |
-h, --host | Listening address, default 0.0.0.0 (listens on all local network cards/IPv4 addresses, accessible from both internal and external networks; set to 127.0.0.1 for local-only access) |
-d, --data-dir | Data root directory; sets DATA_DIR and DATABASE_PATH=<dir>/skills.db |
--base-path | Deployment base path prefix, default / (e.g., /skills/ for subpath deployment) |
--no-cappy | Disable Cappy the capybara mascot |
-v, --verbose | Enable debug logging |
--help | Show help information |
--version | Show version number |
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:
| Capability | Web UI | CLI |
|---|
| Browse / search skills | Yes | skb search |
| Version history & changelogs | Yes | skb update |
| Tags & favorites | Yes (admin tag library; owner assigns tags) | — |
| Collections (admin-curated packs, max 10 skills) | Browse on home | skb install --collection <id_or_slug> |
| GitHub import (public repos only) | Publish page | skb import-github |
| Desktop client | docs/desktop.md | Same install/update logic as CLI |
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.