Skip to content

web-self-hosted.md

Latest commit

 

History

History
196 lines (133 loc) · 4.72 KB

web-self-hosted.md

File metadata and controls

196 lines (133 loc) · 4.72 KB
Raw

PromptHub Web Self-Hosted

apps/web is the lightweight self-hosted web edition of PromptHub.

It is intended for personal use, home lab deployments, or small single-instance setups where users want browser access to their local-first PromptHub workspace without relying on the official cloud product.

It is not the hosted commercial PromptHub Cloud stack. Keep the boundary clear:

  • apps/web: self-hosted, simple auth, workspace files + SQLite index, user-managed deployment
  • prompthub-cloud: official hosted SaaS, team/billing/multi-tenant/cloud operations

Product Scope

This app should stay focused on desktop-equivalent core capabilities:

  • prompt management
  • folders
  • skills
  • import/export
  • sync
  • media
  • settings

It should not grow cloud-only features such as:

  • billing
  • team workspaces
  • multi-tenant organization management
  • hosted object storage orchestration
  • cloud admin operations

Desktop Backup Source

PromptHub Desktop can use this self-hosted web workspace as a personal backup and restore target.

In desktop Settings -> Data, configure:

  • self-hosted PromptHub URL
  • username
  • password

Then desktop can:

  • test the connection
  • upload its current local workspace to PromptHub Web
  • download and restore from PromptHub Web
  • automatically pull once on startup
  • periodically push updates in the background

Sync Contract Snapshot

Current sync provider contract (shared with desktop/web settings) supports:

  • manual
  • webdav
  • self-hosted
  • s3

For web sync operations, PUT /sync/data, POST /sync/push, and POST /sync/pull return a unified summary block (prompts, folders, rules, skills) to keep cross-client parsing stable.

First-Run Bootstrap

When a new deployment starts with an empty database:

  1. The first visit goes to /setup, not the login page.
  2. The user creates the initial administrator account there.
  3. Public registration stays disabled after that first account is created.

Configuration

Copy the example environment file first:

cp apps/web/.env.example apps/web/.env

Install dependencies from the repository root:

pnpm install

Important variables:

  • JWT_SECRET: required, at least 32 characters
  • DATA_ROOT: root directory for all PromptHub data (default: ./). The app writes data/, config/, logs/, and backups/ under this path.
  • ALLOW_REGISTRATION=false: keep this disabled; the first admin is created only through /setup

Local Development

pnpm dev:web

Default ports:

  • client: http://localhost:5174
  • server: http://localhost:3000

Build

pnpm build:web
pnpm --filter @prompthub/web start

Useful root-level commands:

  • pnpm lint:web
  • pnpm typecheck:web
  • pnpm test:web -- --run
  • pnpm verify:web
  • pnpm docker:web:build

Docker

apps/web already includes a production Dockerfile and ready-to-use compose files.

When a release tag is built in CI, PromptHub also publishes a container image to GHCR:

  • ghcr.io/legeling/prompthub-web:<version-tag>
  • ghcr.io/legeling/prompthub-web:latest

Quick Start with Docker Compose

cd apps/web
cp .env.example .env

Then edit .env and set at least:

JWT_SECRET=replace-with-a-random-secret-at-least-32-chars
ALLOW_REGISTRATION=false

Start the service:

docker compose up -d --build

Default access URL:

  • http://localhost:3871

The compose file mounts PromptHub-managed data roots so your database, workspace files, and uploaded media stay outside the container.

Deploy from the Published GHCR Image

docker pull ghcr.io/legeling/prompthub-web:latest
docker run -d \
  --name prompthub-web \
  -p 3871:3000 \
  -e JWT_SECRET='replace-with-a-random-secret-at-least-32-chars' \
  -e ALLOW_REGISTRATION=false \
  -v "$(pwd)/apps/web/data:/app/data" \
  ghcr.io/legeling/prompthub-web:latest

You can also deploy directly from the published image with the compose override in apps/web.

Upgrade

If you deploy with Docker Compose:

cd apps/web
docker compose down
docker compose up -d --build

Your data remains intact as long as you keep the same mounted directories.

Backup

The safest backup strategy is to back up the entire DATA_ROOT, not only the SQLite file.

Typical persisted paths include:

  • data/prompthub.db
  • data/prompts/...
  • data/skills/...
  • data/assets/...
  • config/settings/...
  • backups/...
  • logs/...

Deployment Notes

  • Back up DATA_ROOT regularly.
  • Treat this app as a user-managed deployment artifact, not as a shared hosted service.
  • If you expose it to the public internet, use HTTPS and a reverse proxy in front of it.
  • CI validates the web app with lint, typecheck, tests, production build, Docker image build, and compose validation.