{"id":50984760,"url":"https://github.com/jbsnewmedia/vibe4dock","last_synced_at":"2026-06-19T18:02:22.431Z","repository":{"id":359566020,"uuid":"1246469792","full_name":"jbsnewmedia/vibe4dock","owner":"jbsnewmedia","description":"Vibe4Dock is a modular, Docker-based development workspace with a web interface for tool management, browser terminals, CLI configuration and dynamically generated container provisioning. Its biggest advantage is browser-based access to AI CLI tools and project environments, so work on a project remains possible anytime and from virtually anywhere.","archived":false,"fork":false,"pushed_at":"2026-06-09T11:40:58.000Z","size":2717,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T13:21:19.169Z","etag":null,"topics":["ai","ai-agent","ai-agents","ai-tools","cli","coding","developer-tools","docker","vibe","vibe-coding"],"latest_commit_sha":null,"homepage":"https://github.com/jbsnewmedia/vibe4dock","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbsnewmedia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T08:15:53.000Z","updated_at":"2026-06-09T11:41:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jbsnewmedia/vibe4dock","commit_stats":null,"previous_names":["jbsnewmedia/vibe4dock"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/jbsnewmedia/vibe4dock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbsnewmedia%2Fvibe4dock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbsnewmedia%2Fvibe4dock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbsnewmedia%2Fvibe4dock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbsnewmedia%2Fvibe4dock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbsnewmedia","download_url":"https://codeload.github.com/jbsnewmedia/vibe4dock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbsnewmedia%2Fvibe4dock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34542467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","ai-agents","ai-tools","cli","coding","developer-tools","docker","vibe","vibe-coding"],"created_at":"2026-06-19T18:02:18.479Z","updated_at":"2026-06-19T18:02:22.425Z","avatar_url":"https://github.com/jbsnewmedia.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"readme/vibe4dock-logo-icon.svg\" alt=\"Vibe4Dock logo\" width=\"160\"\u003e\n\u003c/p\u003e\n\n# Vibe4Dock\n\nFor the German version, see [README.de.md](readme/README.de.md).\n\nThis documentation describes **Vibe4Dock 1.0.3**.\n\nVibe4Dock is a Docker-based development environment with a web interface for CLI tools, browser shells, and project-specific runtime extensions. The main reason this project exists is simple: it gives you direct web access to AI CLI tools so you can keep working on your project anytime - on your desktop, phone, tablet, while traveling, or basically from anywhere.\n\nThis repository contains both the Vibe4Dock skeleton template and the setup CLI (`./vibe4dock` or `php vibe4dock.php`). The setup CLI generates a new Vibe4Dock project exclusively from the bundled `skeleton/` directory.\n\nTechnically, Vibe4Dock consists of a PHP-based web container for the actual workspace and a separate tools service for the management UI. Optional runtime extensions such as databases are activated later through the tools interface, which generates provisioning, mount, and Compose override configuration dynamically from JSON definitions.\n\n![Vibe4Dock Example](readme/vibe4dock-example.webp)\n\n## Project goal\n\nVibe4Dock solves a common problem in local and team development setups: the base environment should start quickly, while optional tools should only be enabled when needed. At the same time, access to AI and developer tools should not be tied to a single machine. Instead of maintaining one huge static Docker image per project, Vibe4Dock lets you manage tools modularly and then use them comfortably through the browser.\n\nThis project is especially useful in setups where:\n\n- a PHP-based web environment is needed,\n- multiple CLI tools should be optionally available,\n- configuration such as logins, caches, or dotfiles must persist,\n- direct browser access to root and application shells is useful,\n- people want to continue working productively through web access while remote or mobile,\n- Docker mounts should be activated dynamically without manually editing Compose files.\n\n## Setup CLI\n\nThe setup CLI creates a new Vibe4Dock project from the bundled `skeleton/` template. All generated project files come from that placeholder-based kit, so ports, image versions, and container names are rendered into copied templates instead of being hardcoded in the generator. Files in that directory are stored as `*.skeleton` templates and are written to the target project without the `.skeleton` suffix.\n\n### Setting up the Vibe4Dock setup CLI\n\nThe CLI itself only requires PHP CLI version 8 or newer. No additional dependencies or Composer installation are required to run the setup tool.\n\nLatest stable tag:\n\n```bash\ngit clone --branch 1.0.3 --depth 1 https://github.com/jbsnewmedia/vibe4dock.git\ncd vibe4dock\nchmod +x vibe4dock\n```\n\nDevelopment branch:\n\n```bash\ngit clone https://github.com/jbsnewmedia/vibe4dock.git\ncd vibe4dock\nchmod +x vibe4dock\n```\n\nOptionally, you can create a symlink to make the CLI available globally:\n\n```bash\nsudo ln -s $(pwd)/vibe4dock /usr/local/bin/vibe4dock\n```\n\nAfter that, you can run the CLI directly:\n\n```bash\n./vibe4dock --help\n```\n\nIf you do not want to make the file executable, this always works as well:\n\n```bash\nphp vibe4dock.php --help\n```\n\n### Interactive start\n\n```bash\n./vibe4dock\n```\n\nAlternative:\n\n```bash\nphp vibe4dock.php\n```\n\nWithout options, the setup runs interactively and asks for the project name, PHP version, ports, and output directory. If you run it inside an existing Vibe4Dock project, the detected settings are prefilled automatically.\n\n### CLI help\n\n```bash\n./vibe4dock --help\n```\n\n### Non-interactive usage\n\n```bash\n./vibe4dock \\\n  --project-name=my-vibe4dock \\\n  --php-version=8.4 \\\n  --web-port=80 \\\n  --tools-port=8090 \\\n  --root-shell-port=7681 \\\n  --app-shell-port=7682 \\\n  --output-dir=./build/my-vibe4dock\n```\n\n### Supported options\n\n| Option | Meaning |\n| --- | --- |\n| `--project-name` | Name of the generated project |\n| `--php-version` | PHP base version for the web image |\n| `--web-port` | Host port for the web application |\n| `--tools-port` | Host port for the tools UI |\n| `--root-shell-port` | Host port for the root shell |\n| `--app-shell-port` | Host port for the application shell |\n| `--output-dir` | Target directory for the generated project |\n\n### Setup CLI internals\n\nThe setup CLI source lives in `src/` under the `Vibe4Dock\\` namespace and is loaded by a\nminimal PSR-4 autoloader in `vibe4dock.php`. **Running the CLI still only requires PHP 8 or\nnewer - no Composer installation or `vendor/` directory is needed.** Composer is only used\nfor development tooling.\n\n| Class | Responsibility |\n| --- | --- |\n| `Cli` | Argument handling, interactive prompts, and console output |\n| `OptionParser` | Parses raw CLI arguments into an options array |\n| `SetupConfig` | Immutable, validated project configuration |\n| `ProjectGenerator` | Copies and renders the `skeleton/` templates |\n| `TemplatePath` | Maps skeleton paths to rendered output paths |\n| `EnvironmentReader` | Reads defaults from an existing generated environment |\n| `PortNormalizer` | Normalizes and validates host ports |\n\n### Development and quality tooling\n\nDevelopment requires Composer and a modern PHP version (8.3+ for the bundled tools).\n\n```bash\ncomposer install\n```\n\nThe following tools are configured and wired up as Composer scripts:\n\n| Command | Tool | Purpose |\n| --- | --- | --- |\n| `composer ecs` / `composer ecs:fix` | Easy Coding Standard | Coding-style checks and fixes |\n| `composer rector` / `composer rector:fix` | Rector | Automated refactoring (dry-run / apply) |\n| `composer phpstan` | PHPStan (level max) | Static analysis |\n| `composer test` | PHPUnit | Test suite |\n| `composer check` | all of the above | Run ecs, rector (dry-run), phpstan and tests |\n| `composer fix` | ecs + rector | Apply all automatic fixes |\n\n```bash\ncomposer check\n```\n\n## Architecture overview\n\nVibe4Dock starts two Docker services by default:\n\n| Service | Purpose | Port(s) |\n| --- | --- | --- |\n| `web` | Main development environment with Apache/PHP, ttyd, shells, and installed tools | `80`, `7681`, `7682` |\n| `tools` | Management UI for dashboard, categories, settings, and install/uninstall workflows | `8090` |\n\n### `web` service\n\nThe web service is based on `webdevops/php-apache-dev:8.4` and extends that image with:\n\n- `ttyd` for browser-based terminals,\n- `tmux`,\n- `git`,\n- `sudo`,\n- dynamic provisioning via `docker/web/provision.sh`,\n- startup logic via `docker/web/entrypoint-dev.sh`.\n\nOn container startup, the following happens:\n\n1. optional values from `.env.local` are loaded,\n2. Git config is applied for the application user when enabled,\n3. already enabled tools are reinstalled or verified using `docker/web/settings/installed_tools.json`,\n4. persistent mounts are restored from backup directories,\n5. permissions under `/home/application` are fixed,\n6. two ttyd sessions are started:\n   - root shell on port `7681`\n   - application shell on port `7682`\n\nThis creates an environment that is not only usable locally on one machine, but reachable from any browser. That is exactly what makes Vibe4Dock attractive for working on the go: the project runs centrally in the container while access happens through the web UI and browser terminals.\n\n### `tools` service\n\nThe tools service is a standalone PHP container based on `php:8.4-cli-bookworm`. It provides the management interface and has access to:\n\n- the project directory via bind mount,\n- the Docker socket,\n- the configuration files for tools and settings,\n- the target container `\u003cproject-name\u003e-web-1`, where commands are executed.\n\nThe interface is not just informational; it actively manages:\n\n- tool installation and removal,\n- generation of `docker/web/provision.sh`,\n- generation of `docker-compose.override.yml`,\n- activation of the rebuild hint when installed packs add new mounts or services,\n- status display for runtime, memory, disk, and installed tools.\n\n### Bundled packs plus on-demand activation\n\nThe repository ships the base services together with a curated set of bundled tool and addon definitions. Generated projects stay clean in practice because tools, addon services, and their persistent directories are only activated when you install them through the Tools UI. Mount-backed directories and addon data folders are created on demand and removed again when no longer needed.\n\n## Project structure\n\nThe most important files and directories:\n\n| Path | Meaning |\n| --- | --- |\n| `docker-compose.yml` | Main service definition |\n| `docker-compose.override.yml` | Generated automatically when installed packs add persistent mounts or optional services |\n| `public/` | Web root of the `web` container |\n| `docker/web/` | Dockerfile, entry logic, provisioning, and persistent tool data |\n| `docker/tools/` | Management UI, dashboard, routing, and tool/settings definitions |\n| `docker/tools/category/` | Tool definitions, sorted and merged by filename |\n| `docker/tools/addons/` | Addon and optional service definitions, also sorted and merged |\n| `docker/tools/settings/` | Settings definitions, also mergeable |\n| `docker/web/settings/` | Persistent user data such as installed tools, caches, logins, and hint files |\n| `docker/data/` | On-demand addon data directories such as database storage |\n| `readme/` | Screenshot and documentation assets |\n\n## Usage model\n\nThe tools UI on port `8090` is split into several areas:\n\n- **Dashboard**\n  - application shell\n  - root shell\n  - addon-provided browser shells, either by extending `web` or by exposing their own addon service ports\n  - system information such as PHP, Composer, RAM, and disk status\n  - configuration status\n  - list of installed tools / addons\n- **Tools**\n  - one combined tools view with search and a category switcher\n  - installable tools can expose a separate `Config` action after installation\n  - Git Config now lives as a regular tool in its own `Git` category\n  - categories appear only when tool packs provide them via JSON\n- **Addons**\n  - addon categories appear only when addon packs provide them via JSON\n\nInstallations and updates are triggered directly through form actions. While an action is running, the UI places a global loading layer with a spinner over the page until the response page loads.\n\n## Why Vibe4Dock is especially useful\n\nThe core value is not just installing tools, but location independence. Vibe4Dock makes AI CLI tools and project access available over the web. That means the same development environment can be used:\n\n- on an office desktop,\n- on a personal laptop,\n- on a phone,\n- on a tablet,\n- while traveling on a train or at a client site,\n- anywhere a browser is available.\n\nThe real work stays inside the container and therefore inside one consistent environment. Device choice, operating system, and local machine setup become much less important.\n\n## Tool and addon packs\n\nBundled definitions for **Vibe4Dock 1.0.3** are loaded from:\n\n```text\ndocker/tools/category/\ndocker/tools/addons/\n```\n\nCurrent bundled tool packs:\n\n- **AI CLI**: GitHub Copilot CLI, Codex CLI, Claude Code, Cline CLI, Hermes CLI, Junie CLI, OpenCode CLI\n- **Git**: Git Config, Lazygit\n- **System \u0026 Runtime**: Node.js, pnpm, Yarn\n- **PHP Frameworks**: Laravel CLI, Symfony CLI, WordPress CLI\n- **Code Quality**: Code Quality Package\n\nCurrent bundled addon packs:\n\n- **Databases**: MariaDB, MySQL, PostgreSQL, Firebird, Adminer\n- **Browser Shells**: Lazygit Shell\n- **Browser IDEs**: code-server\n- **DevOps Platforms**: OneDev Community Edition\n- **Mail \u0026 Messaging**: Mailpit\n- **AI Assistants**: opencode\n\nYou can still add your own packs or overrides on top of these files.\n\nThe base web image stays minimal and database-agnostic. Each database addon is\nself-contained (\"autark\"): installing it not only adds its Compose service but also\nprovisions the matching PHP driver into the web container at image build time via\n`provision.sh` (for example `pdo_mysql`/`mysqli` for MariaDB and MySQL, `pdo_pgsql`/`pgsql`\nfor PostgreSQL, and `pdo_firebird` for Firebird). The install commands are idempotent, so\nrebuilds are safe and uninstalling simply rebuilds the image from the clean base.\n\n## How tool installation works\n\nTool installation in Vibe4Dock is a multi-step process:\n\n1. the UI triggers an action such as `install`, `update`, `switch`, or `uninstall`,\n2. the tools service executes the configured command inside the `web` container,\n3. the tool is marked as active in `docker/web/settings/installed_tools.json`,\n4. if the tool requires persistent mounts, a rebuild hint is set,\n5. `docker/web/provision.sh` is regenerated,\n6. `docker-compose.override.yml` is regenerated when additional volumes are required.\n\n### Provisioning\n\n`docker/web/provision.sh` is generated automatically and contains:\n\n- installation commands for all enabled tools,\n- a topologically sorted order based on configured dependencies,\n- backup logic for mounted tool directories,\n- cleanup of old rebuild hint files.\n\n### Dynamic volumes\n\nTools with persistent data define `mounts`. These are written automatically into `docker-compose.override.yml` so that data such as the following can survive rebuilds:\n\n- npm cache,\n- CLI login data,\n- tool configuration,\n- local agent data directories.\n\n## Rebuild flow\n\nSome tools require volume mounts. In that case, installing them in the running container alone is not enough. Vibe4Dock marks that state as:\n\n**Manual Rebuild Required**\n\nThe rebuild is done with:\n\n```bash\n./docker/rebuild.sh\n```\n\nor on Windows:\n\n```bat\n./docker/rebuild.bat\n```\n\nThis will:\n\n1. run `docker compose down`,\n2. rebuild the web container,\n3. start the Compose setup again and remove orphaned addon containers from renamed/removed services,\n4. remove the rebuild hint from inside the container.\n\nIn addition, the UI polls rebuild status every 15 seconds. As soon as the hint file disappears, the banner fades out automatically.\n\nWhen you click **Rebuild now** the Tools UI takes you to a live status page that polls `/api/rebuild-progress` every two seconds. The page shows:\n\n- the moment the hint file was touched,\n- whether the host watcher has picked up the request (`pending` → `running` → `completed`/`failed`),\n- the watcher's last seen mtime and the timestamp of the last rebuild,\n- the most recent 30 lines of `docker/watcher.log` with auto-scroll.\n\nWhile the rebuild script runs `docker compose down` the tools container itself is briefly unavailable. The page shows a \"Rebuilding\" state during that gap and resumes polling automatically once the container comes back.\n\n### Rebuild watcher (host daemon)\n\nVibe4Dock ships a small PHP-based **host daemon** as `./docker/watcher.sh`. It runs on the host, watches `docker/web/settings/rebuild_required.hint`, and - by default - runs `./docker/rebuild.sh` as soon as a new mtime is detected. The **Rebuild now** button in the Tools UI banner touches the same hint file with a fresh mtime, so the daemon picks up the request on its next poll and runs the rebuild for you.\n\n#### Starting and managing the daemon\n\n```bash\n./docker/watcher.sh start    # start as a background daemon\n./docker/watcher.sh status   # is it running?\n./docker/watcher.sh logs     # tail ./docker/watcher.log\n./docker/watcher.sh stop     # stop it\n./docker/watcher.sh restart  # restart it\n./docker/watcher.sh run      # run in the foreground (Ctrl+C to stop)\n./docker/watcher.sh once     # single poll, then exit\n./docker/watcher.sh service  # print a ready-to-use systemd service unit\n```\n\nOn Windows the equivalent is `./docker/watcher.bat run|once|status|logs`.\n\nThe daemon uses `setsid`, a PID file, and a stop file for clean shutdowns. Its state survives restarts through a small JSON file at `docker/.watcher.state` so that a touch of the hint file (for example from the **Rebuild now** button) is always detected as a fresh request.\n\n#### Run as a real OS service (recommended)\n\nThe daemon is opt-in. The recommended way to run it is via your platform's service manager so it survives reboots and crashes. The wrapper itself is project-local, which is why the paths in the examples below use absolute paths.\n\n**systemd** (Linux, recommended)\n\n```bash\nsudo ./docker/watcher.sh service | sudo tee /etc/systemd/system/vibe4dock-watcher.service\nsudo systemctl daemon-reload\nsudo systemctl enable --now vibe4dock-watcher.service\nsudo systemctl status vibe4dock-watcher.service\n```\n\n`./docker/watcher.sh service` prints a ready-to-use unit file with the right `WorkingDirectory` and `ExecStart` for the current project. It looks like this:\n\n```ini\n[Unit]\nDescription=Vibe4Dock Rebuild Watcher\nAfter=network.target docker.service\nRequires=docker.service\n\n[Service]\nType=simple\nWorkingDirectory=/absolute/path/to/your/vibe4dock-project\nExecStart=/absolute/path/to/your/vibe4dock-project/docker/watcher.sh run\nRestart=on-failure\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\n```\n\n**launchd** (macOS, as a user LaunchAgent)\n\nSave the following as `~/Library/LaunchAgents/com.vibe4dock.watcher.plist` and adjust the two absolute paths:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n  \u003cdict\u003e\n    \u003ckey\u003eLabel\u003c/key\u003e\u003cstring\u003ecom.vibe4dock.watcher\u003c/string\u003e\n    \u003ckey\u003eWorkingDirectory\u003c/key\u003e\u003cstring\u003e/absolute/path/to/your/vibe4dock-project\u003c/string\u003e\n    \u003ckey\u003eProgramArguments\u003c/key\u003e\n    \u003carray\u003e\n      \u003cstring\u003e/absolute/path/to/your/vibe4dock-project/docker/watcher.sh\u003c/string\u003e\n      \u003cstring\u003erun\u003c/string\u003e\n    \u003c/array\u003e\n    \u003ckey\u003eRunAtLoad\u003c/key\u003e\u003ctrue/\u003e\n    \u003ckey\u003eKeepAlive\u003c/key\u003e\u003ctrue/\u003e\n  \u003c/dict\u003e\n\u003c/plist\u003e\n```\n\n```bash\nlaunchctl load -w ~/Library/LaunchAgents/com.vibe4dock.watcher.plist\nlaunchctl list | grep vibe4dock\n```\n\n**Windows Task Scheduler**\n\nCreate a basic task that runs `docker\\watcher.bat run` at user logon. Because the wrapper is a foreground loop, set \"Stop the task if it runs longer than\" to \"Do not stop\" or a long duration.\n\n#### Tuning the daemon\n\nAll knobs are environment variables; `.env.local` is the right place for them. The shell wrappers pass them through to the PHP process automatically.\n\n| Variable | Default | Meaning |\n| --- | --- | --- |\n| `WATCHER_POLL_INTERVAL` | `3` | Seconds between polls. |\n| `WATCHER_AUTO_REBUILD` | `1` | `1` runs `./docker/rebuild.sh` on detection, `0` only logs. |\n| `WATCHER_REBUILD_DEBOUNCE` | `0` | Wait this many seconds after the last change before rebuilding (useful when multiple tool installs happen in quick succession). |\n| `WATCHER_REBUILD_TIMEOUT` | `0` | Hard timeout in seconds for the rebuild command (`0` = no timeout). |\n| `WATCHER_REBUILD_COMMAND` | `./docker/rebuild.sh` | Command to execute (relative to `WATCHER_REBUILD_CWD`). |\n| `WATCHER_REBUILD_CWD` | project root | Working directory for the rebuild command. |\n\n## Configuration system\n\nA central part of the project is the mergeable JSON configuration system.\n\n### Tool definitions\n\nTool definitions live in:\n\n```text\ndocker/tools/category/\n```\n\nEach file:\n\n- ends in `.json`,\n- is loaded in filename order,\n- can define categories and tools,\n- is merged with all other files.\n\nBundled tool files are already part of the repository in version 1.0.3, and additional team-specific or project-specific packs can be layered on top through the same merge mechanism.\n\n### Addon definitions\n\nAddon definitions live in:\n\n```text\ndocker/tools/addons/\n```\n\nThese files are loaded with the same merge rules as normal tools, but they usually contribute optional Compose services, ports, environment variables, persistent data directories, and dashboard-dockable browser endpoints such as shells or browser IDEs.\n\n### Settings definitions\n\nSettings live in:\n\n```text\ndocker/tools/settings/\n```\n\nThese files are also loaded by filename and merged.\n\nSettings can optionally define `apply_commands`. Those commands are executed through the tools UI after saving a setting and can also be triggered centrally through `POST /action/settings/apply`.\n\n### Merge rules\n\nThe merge logic lives in `docker/tools/config.php`:\n\n- categories are merged by `unique_key`,\n- tools are merged by `id`,\n- settings are merged by `id`,\n- files are processed alphabetically or numerically by filename,\n- later files can selectively extend or override existing definitions.\n\nExample file naming:\n\n```text\n100_base.json\n200_team.json\n300_project.json\n```\n\nThis allows you to layer a base configuration, team-wide additions, and project-specific overrides cleanly.\n\n## Structure of a tool definition\n\nA tool can contain fields such as:\n\n| Field | Meaning |\n| --- | --- |\n| `id` | Unique tool ID |\n| `category` | Target category |\n| `label` | Display name in the UI |\n| `description` | Short description |\n| `check` | Command used for status or version detection |\n| `install` | Install command |\n| `uninstall` | Uninstall command |\n| `mounts` | Persistent volume mounts |\n| `dependencies` | Installation prerequisites |\n| `type` | Optional, e.g. `versioned` |\n| `versions` | Version entries for versioned tools |\n| `default_version` | Preselected version for versioned tools |\n| `config_schema` | Optional config dialog definition for tool-specific settings |\n| `apply_commands` | Optional commands executed after config changes or activation |\n| `package_operations` | Optional package/file operations for project scaffolding tools |\n| `compose_service` | Optional service definition used mainly by addons |\n| `compose_services` | Optional list of additional addon services such as bootstrap or sidecar jobs |\n| `dashboard_shell` | Optional dashboard entry for browser-accessible shells or addon endpoints |\n\n`package_operations.templates` can now scaffold files either from `source`, from inline `content`, or from readable multiline `content_lines`. Templates can also declare `mode` or `executable` to write shell scripts and similar helper files directly from JSON definitions.\n\n### Browser endpoint docking\n\nAddons can dock into the dashboard in two generic ways:\n\n1. by exposing their own host port and describing it via `dashboard_shell`\n2. by extending the `web` service and adding a declarative `dashboard_shell.launcher`\n\nTypical `dashboard_shell` fields:\n\n| Field | Meaning |\n| --- | --- |\n| `label` | Dashboard card title |\n| `port_field` / `port` | Host port from config or as a fixed value |\n| `username_field` / `username` | Optional Basic Auth username |\n| `password_field` / `password` | Optional Basic Auth password |\n| `protocol` | Optional URL scheme such as `http` or `https` |\n| `path` | Optional path appended to the URL |\n| `button_label` | Optional button text |\n| `help_title` / `help_text` / `help_command` | Dashboard help modal content |\n\nThis also supports password-only endpoints such as `code-server`, where no username is required but a configured password still counts as protected access.\n\nFor `web`-hosted browser shells, `dashboard_shell.launcher` supports a declarative runtime definition:\n\n| Launcher field | Meaning |\n| --- | --- |\n| `type` | Currently `ttyd` |\n| `service` | Currently `web` for in-container browser shells |\n| `container_port` | Container port opened by the launcher |\n| `run_as` | `application` or `root` |\n| `working_directory` | Optional working directory before launch |\n| `executable` | Command to launch |\n| `arguments` | Optional argument list |\n| `fallback_profile` | Optional fallback shell profile such as `application-shell` |\n| `environment` | Optional extra environment variables |\n\nInstalled declarative launchers are materialized into `docker/web/settings/browser_shells.json`, which the web entrypoint reads on startup to spawn additional browser shells without hardcoded addon-specific logic.\n\nExamples of bundled browser endpoints:\n\n- **Lazygit Shell**: additional ttyd session inside the `web` container\n- **Adminer**: separate addon service with generated one-click logins for the installed database addons\n- **code-server**: separate addon service with its own port and password-protected browser IDE\n- **OneDev**: separate addon service with a web UI on port `6610`, Git SSH on port `6611`, and an auto-bootstrap job for the current workspace\n- **Mailpit**: separate addon service with a web UI on port `8025` for viewing caught emails and an SMTP server on port `1025` for local mail testing\n- **opencode**: separate addon service that runs the opencode AI coding agent with a browser-based web UI on port `4096` and the project mounted as workspace\n\n## Settings\n\nSettings definitions remain supported, but the bundled Git identity flow now ships as a regular tool instead of a legacy setting card.\n\n- **Git Config** (tool category `Git`)\n  - install/uninstall through the normal tools workflow\n  - configuration via the tool-level `Config` dialog\n  - `GIT_USER_NAME`\n  - `GIT_USER_EMAIL`\n\nThe values are written into `.env.local`. Optional `apply_commands` make the runtime application neutral and definition-driven instead of hardcoding setting-specific behavior in PHP.\n\nGenerated projects also include a commented `.env.local.example` with optional HTTP Basic Auth credentials for the Tools UI, the application shell, and the root shell.\n\nTo enable that protection, copy the file to `.env.local`, uncomment the variables you need, and replace the placeholder passwords before starting the stack:\n\n```dotenv\nTOOLS_USERNAME=\"tools\"\nTOOLS_PASSWORD=\"replace-with-a-strong-password\"\nAPP_SHELL_USERNAME=\"application\"\nAPP_SHELL_PASSWORD=\"replace-with-a-strong-password\"\nROOT_SHELL_USERNAME=\"root\"\nROOT_SHELL_PASSWORD=\"replace-with-a-strong-password\"\n```\n\n## Persistence\n\nPersistent data is intentionally stored outside the image in mounted directories under `docker/web/settings/`.\n\nExamples:\n\n- `docker/web/settings/copilot`\n- `docker/web/settings/claude`\n- `docker/web/settings/cline`\n- `docker/web/settings/codex`\n- `docker/web/settings/code-server/config`\n- `docker/web/settings/code-server/data`\n- `docker/web/settings/hermes`\n- `docker/web/settings/junie`\n- `docker/web/settings/lazygit`\n- `docker/web/settings/npm`\n\nAddon services also persist their runtime data outside the image, for example:\n\n- `docker/data/mariadb`\n- `docker/data/mysql`\n- `docker/data/onedev`\n- `docker/data/postgresql`\n- `docker/data/firebird`\n- `docker/data/mailpit`\n\nSome addons also scaffold helper files into the project when they need bootstrap logic, for example:\n\n- `docker/onedev/bootstrap/bootstrap.sh`\n\nTechnical state files are also stored there:\n\n- `installed_tools.json`\n- `browser_shells.json`\n- `rebuild_required.hint`\n\n## Browser access\n\nVibe4Dock provides two built-in browser shells plus addon-provided dashboard endpoints such as extra shells or browser IDEs:\n\n| Shell | Purpose | Port |\n| --- | --- | --- |\n| Root Shell | Administrative tasks inside the container | `7681` |\n| Application Shell | Normal development work as `application` | `7682` |\n\nThe application shell starts through `tmux` so sessions can persist. Additional browser shells can be registered declaratively by addons, and separate addon services such as `code-server` or `OneDev` can expose their own browser endpoints while still appearing on the same dashboard.\n\nThe bundled OneDev addon now also bootstraps the configured initial administrator and creates a project for the current workspace automatically on first start. If the workspace already contains a Git repository with commits, the bootstrap job pushes branches and tags into the freshly created OneDev project.\n\n## Starting the project\n\n### Requirements\n\n- Docker\n- Docker Compose\n\n### Start\n\n```bash\ncp .env.local.example .env.local\ndocker compose up -d --build\n```\n\nAfter that, the most important endpoints are:\n\n- application: `http://localhost:80`\n- tools UI: `http://localhost:8090` (protected if both `TOOLS_USERNAME` and `TOOLS_PASSWORD` are set in `.env.local`)\n- root shell: `http://localhost:7681` (protected if both `ROOT_SHELL_USERNAME` and `ROOT_SHELL_PASSWORD` are set in `.env.local`)\n- application shell: `http://localhost:7682` (protected if both `APP_SHELL_USERNAME` and `APP_SHELL_PASSWORD` are set in `.env.local`)\n\n## Typical workflow\n\n1. start Vibe4Dock,\n2. open the tools UI,\n3. add or install the tool and addon packs you need,\n4. if a rebuild is required, run `./docker/rebuild.sh`,\n5. continue working inside the application shell.\n\n## Extending the system\n\n### Add a new tool file\n\nNew tools or overrides should go into their own file under `docker/tools/category/`, for example:\n\n```text\ndocker/tools/category/200_custom.json\n```\n\n### Add a new category\n\nNew categories need:\n\n- `unique_key`\n- `id`\n- `label`\n- `order`\n\n### Add a new setting\n\nNew settings are added as additional entries under `docker/tools/settings/*.json`.\n\n## Notes on the current implementation\n\n- The tools UI is server-rendered PHP without a framework.\n- Routing is implemented directly in `docker/tools/index.php`.\n- Provisioning and override generation happen from the current configuration state.\n- The system is intentionally pragmatic and easy to extend.\n- Because the tools container has access to the Docker socket, the management UI has wide-reaching access to the local Docker environment.\n\n## Security and operational considerations\n\nVibe4Dock is clearly intended as a development tool, not as a hardened multi-tenant platform. In particular:\n\n- the tools container has access to `/var/run/docker.sock`,\n- installation commands are executed inside the web container,\n- some tools install software directly as root,\n- generated projects can optionally protect the Tools UI and both browser shells via `.env.local`,\n- persistent mounts may contain logins, tokens, and local configuration.\n\nIf you want to use Vibe4Dock beyond localhost, at minimum enable the HTTP Basic Auth credentials from `.env.local`, replace all placeholder passwords, and put the setup behind additional network-level protection such as a VPN, reverse proxy access control, or a private subnet.\n\nBecause of that, this setup is not intended for direct public internet exposure without additional hardening.\n\n## Known characteristics\n\n- Tools or addons that add mounts or services require a manual rebuild.\n- Depending on the tool, installations may require network access and external package sources.\n- Some CLIs only store login data after their first interactive start.\n- The Compose override is generated from the currently selected tools and optional services.\n\n## Summary\n\nVibe4Dock is a modular, Docker-based development workspace with a web interface for tool management, browser terminals, persistent CLI configuration, and dynamically generated container provisioning. Its biggest advantage is browser-based access to AI CLI tools and project environments, so work on a project remains possible anytime and from practically anywhere.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbsnewmedia%2Fvibe4dock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbsnewmedia%2Fvibe4dock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbsnewmedia%2Fvibe4dock/lists"}