SELFHOST-HELPER

Simplify local project hosting, process management, and tunneling

v0.39.0 (mirrors package.json — update both when releasing)

Built with the tools and technologies:

Table of Contents

• Overview
• Recent updates
• Getting Started
  • Prerequisites
  • Installation
  • Usage
  • Scripts
  • Testing
• Features
• Project Structure
  • Key directories and entry points
• Roadmap
• Contributing
• License
• Acknowledgment

---

Overview

SelfHost-Helper is an advanced developer tool designed to simplify local project hosting, process management, and system monitoring. Built with a focus on stability, performance, and user experience, it integrates native Windows process control, real-time resource monitoring, and a modern UI to streamline development workflows.

Why SelfHost-Helper?

This project aims to provide developers with a robust, all-in-one solution for managing local projects efficiently. The core features include:

• 🛠️ Optional Docker builds: A Dockerfile is available for reproducible CI/container builds; everyday development uses npm only.
• ⚙️ Native Process Control: Implements Windows-specific job objects for reliable process grouping and resource management.
• 🔍 Real-Time Monitoring: Resource tracking, process insights, live logs, a configurable Overview grid, and a Resources view for deeper stats.
• 🎨 Modern UI: Frameless desktop shell with custom title bar, toast notifications, and styling via Tailwind CSS v4 (@tailwindcss/postcss, @theme in src/index.css, plus tailwind.config.js for legacy/theme alignment).
• 📁 Project Lifecycle Management: Start/stop/restart projects, editor and file tools, settings split into General, Data, Backup, Runtimes, Updates, and About.
• 🔄 Cross-Platform Utilities: Process tree management and packaging targets for Windows (NSIS) and Linux (AppImage, deb, rpm).
• 🌐 Cloudflare Tunnels: Quick or authenticated tunnels via cloudflared, optional auto-start, dedicated tunnel tab and logs.
• 🔄 In-app updates: electron-updater checks GitHub Releases; Settings → Updates for checks and release notes (see docs/auto-update-publishing.md for maintainers).

---

Recent updates

Recent development has expanded SelfHost-Helper into a full-featured local dev workspace:

• Overview & Resources: Per-project Overview tab with a draggable grid (@eleung/react-grid-layout) and metric tiles; Resources tab for sparklines, uptime, and process detail.
• Editor & LSP: Monaco with an LSP bridge (typescript-language-server, ws) for in-app editing per project.
• Search & Git (Editor): Ripgrep-based SearchPanel and full Git via GitPanel live inside EditorView as resizable panels—not separate top-level router tabs (those are Overview, Console, Editor, Tunnel, Resources).
• File system: Create, delete, rename files and folders; read/write and directory listing; folder watcher; ignore patterns for trees and search.
• Multi-workspace: Multiple projects with categories (Category model), drag-and-drop reorder, and bulk reorder; each project is a workspace root.
• Backup & restore: Legacy SQLite migration with automatic backup; Settings → Backup (and data sections) to restore from a file or open the data folder; see docs/RESTORE_FROM_BACKUP.md.
• Auto-updates: GitHub Releases–driven updates via electron-updater; Settings → Updates; maintainers follow docs/auto-update-publishing.md.
• Error handling & logging: Central electron/services/logger.js, IPC error logging, and debug logging for key operations.

Roadmap and planning notes are in TODO.md.

---

Features

	Component	Details
⚙️	Architecture	Modular Electron desktop app with React renderer Vite for dev and production frontend builds Main/preload/renderer separation with context isolation Hash-based react-router-dom routes for dashboard, project views, and settings
🔩	Code Quality	ESLint and Prettier Path aliases via jsconfig.json npm run typecheck — tsc --noEmit with tsconfig.json (JS codebase; types for tooling/checks)
📄	Documentation	Dockerfile for containerized builds This README; ChangeLog; historical RELEASE_NOTES_v0.7.0.md Current release notes: GitHub Releases (used by the updater) docs/RESTORE_FROM_BACKUP.md; docs/auto-update-publishing.md Roadmap: TODO.md
🎛️	Overview & layout	Overview tab: draggable grid and tiles (CPU, RAM, tunnel mini-views, etc.) Resources tab: detailed resource history and process views ViewTabs routes: overview, console, editor, tunnel, resources
🔔	Shell & UX	Frameless window with TitleBar window controls react-toastify for status toasts
🔌	Integrations	Electron, React, Vite, electron-builder, electron-updater Tailwind v4 pipeline (@tailwindcss/postcss), tailwind.config.js Jotai, Framer Motion, Radix UI, lucide-react Monaco + LSP (ws, typescript-language-server), xterm addons cloudflared, SQLite3, Sequelize, st.db settings simple-git, @vscode/ripgrep, chokidar @hello-pangea/dnd, @eleung/react-grid-layout react-markdown (e.g. update release notes)
🔍	Search	Ripgrep-backed SearchPanel inside the editor workspace Case-sensitive, whole-word, glob options; structured results
📂	Git	Full Git via simple-git in GitPanel (editor workspace): status, diff, stage, commit, push, pull, branches, clone, init, remotes
💾	Backup & restore	Legacy SQLite migration with automatic backup on upgrade Settings sections for data folder, backup/restore (adm-zip / config backup flows where applicable) docs/RESTORE_FROM_BACKUP.md
🌐	Tunneling	Cloudflare quick and authenticated tunnels via cloudflared Tunnel tab + log viewer; optional auto-start with project
⬆️	Auto-updates	updateService + electron-updater against GitHub Releases Settings → Updates; publish:prod for maintainers (requires GH_TOKEN — see docs)
🧩	Modularity	Component-based React UI under src/components Electron services under electron/services Hooks (src/hooks) and shared lib
🧪	Testing	No automated test suite yet; ESLint + optional npm run typecheck
⚡️	Performance	pidusage and statsService for monitoring Vite, Tailwind, React Fast Refresh
🛡️	Security	Context isolation, hardened preload surface secretStore (safeStorage) for tunnel tokens
📦	Runtime	runtimeService / Settings → Runtimes for toolchain hints and environment Windows job object native addon under electron/job

---

Project Structure

The user-visible app version is defined in package.json; keep the README header version in sync when releasing.

└── SelfHost-Helper/
    ├── ChangeLog
    ├── Dockerfile
    ├── LICENSE
    ├── README.md
    ├── RELEASE_NOTES_v0.7.0.md   # historical; current notes on GitHub Releases
    ├── TODO.md
    ├── tsconfig.json
    ├── database/
    │   └── models/                 # Project.js, Category.js (Sequelize + SQLite)
    ├── docs/
    │   ├── RESTORE_FROM_BACKUP.md
    │   └── auto-update-publishing.md
    ├── electron/
    │   ├── ipc/
    │   ├── job/                    # native Windows job object addon (C++)
    │   ├── services/               # DB, projects, tunnels, git, search, LSP, stats, updates, …
    │   ├── tray/
    │   ├── main.js
    │   └── preload.js
    ├── public/
    │   └── file-icons/
    ├── resources/
    ├── src/
    │   ├── components/             # UI, overview grid, panels
    │   ├── editors/
    │   ├── hooks/
    │   ├── lib/
    │   ├── pages/                  # Dashboard, Settings (+ settings/* sections)
    │   ├── store/
    │   ├── config/
    │   ├── App.jsx
    │   ├── main.jsx
    │   ├── index.css               # Tailwind v4: @import "tailwindcss", @theme
    │   └── monacoWorkers.js
    ├── eslint.config.js
    ├── index.html
    ├── jsconfig.json
    ├── package.json
    ├── postcss.config.js
    ├── tailwind.config.js
    └── vite.config.js

Key directories and entry points

• electron/main.js — BrowserWindow, custom protocol, lifecycle; registers IPC and services.
• electron/preload.js — Exposes window.api to the renderer (context isolation).
• electron/ipc/handlers.js — IPC for projects, files, git, search, tunnels, settings, updates, and more.
• electron/services/ — Includes projectsManager, database, tunnelManager, gitService, searchService, lspBridge, statsService, runtimeService, updateService, configBackupService, secretStore, settingsService, filesWatcher, logger, processTree, ignorePatterns, and related helpers.
• src/App.jsx — Hash routes: dashboard, project/:projectId/{overview|console|editor|tunnel|resources}, /settings/*.
• src/components/ProjectLayout.jsx — Project shell and data loading; ViewTabs.jsx switches the five primary views and shows the stats pill.
• src/components/EditorView.jsx — Monaco, file tree, resizable SearchPanel and GitPanel (search/git are editor panels, not separate top-level tabs).
• src/components/overview/ — Dashboard grid (@eleung/react-grid-layout) and metric tiles.
• src/pages/settings/ — General, data, backup, runtimes, updates (release notes via react-markdown), about.
• Full repository tree on GitHub — exhaustive listing.

---

Getting Started

Prerequisites

For local development:

• Runtime: Node.js (LTS recommended)
• Language: JavaScript (renderer + main); TypeScript toolchain for npm run typecheck only
• Package manager: npm

Docker is optional — use it only if you want the Dockerfile-based build pipeline. Most contributors run npm install and npm run dev directly on the host.

Installation

Build SelfHost-Helper from the source and install dependencies:

1. Clone the repository:

   ❯ git clone https://github.com/DevRoots-Studio/SelfHost-Helper

2. Navigate to the project directory:

   ❯ cd SelfHost-Helper

3. Install the dependencies:

Using docker:

❯ docker build -t DevRoots-Studio/SelfHost-Helper .

Using npm:

❯ npm install

Usage

Run the project in development:

Using docker:

Build the image, then run a container; the built app is in /app/release inside the image (see Dockerfile VOLUME). Example:

docker build -t DevRoots-Studio/SelfHost-Helper .
docker run -it -v release-out:/app/release DevRoots-Studio/SelfHost-Helper

Using npm:

npm run dev

This starts the Vite dev server and Electron together. For production, run npm run build then run the installer or unpacked app from the release/ directory.

Scripts

Script	Description
npm run dev	Start development (Vite + Electron via concurrently)
npm run build	Production build: Vite → dist/, then electron-builder → release/
npm run build:dev	Dev artifact (separate appId, output under release-dev/)
npm run build:prod	Same as production build with NODE_ENV=production set for electron-builder
npm run build:web	Vite build only (frontend to dist/, no Electron package)
npm run publish:prod	Maintainers: build and publish to GitHub Releases (electron-builder --publish always). Requires GH_TOKEN (and optional .env via dotenv-cli). See docs/auto-update-publishing.md.
npm run lint	Run ESLint
npm run typecheck	tsc --noEmit (no compile output; checks against tsconfig.json)
npm run format	Format with Prettier
npm run format:check	Check Prettier formatting

Testing

There is no automated test suite yet. Use ESLint, Prettier, and optionally npm run typecheck before releases.

---

Roadmap

The project roadmap and task list live in TODO.md — planned work, ideas, and completed items. For shipped versions, see GitHub Releases.

---

Contributing

• 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
• 🐛 Report Issues: Submit bugs found or log feature requests for the SelfHost-Helper project.
• 💡 Submit Pull Requests: Review open PRs and submit your own against the main branch.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your github account.
2. Clone Locally: Clone the forked repository to your local machine using a git client.

   git clone https://github.com/DevRoots-Studio/SelfHost-Helper

3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b new-feature-x

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented new feature x.'

6. Push to github: Push the changes to your forked repository.

   git push origin new-feature-x

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

Contributor Graph

---

License

SelfHost-Helper is licensed under the ISC License. See the LICENSE file in the repository root for the full text.

---

Acknowledgments

• Credit contributors, inspiration, references, etc.

⬆ Return

---