/skill-base-web-deploy

name: skill-base-web-deploy
description: >-
  Skill Base server deployment guide. Covers starting the Skill Base server (npx skill-base), Docker configuration, port mapping, SQLite database backup, and platform capabilities (collections, tags, GitHub import). For deploying and operating the Skill Base platform itself only.
keywords:
  - deploy skill-base
  - npx skill-base
  - skill-base docker
  - collection

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](../../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.