Update docs
This commit is contained in:
+10
-4
@@ -4,7 +4,7 @@ Admin route prefix: **`magesail`** (see [`Magesail/etc/adminhtml/routes.xml`](..
|
||||
|
||||
## Menu: MageSail → Holesail Tunnel
|
||||
|
||||
Defined in [`Magesail/etc/adminhtml/menu.xml`](../Magesail/etc/adminhtml/menu.xml). The module registers a **top-level** admin sidebar entry **MageSail** (sort order **78**, just before JetRails at **79** when both are installed), same structural pattern as JetRails’ `JetRails_Plugins::jetrails` menu. The sail icon is applied like JetRails’ sidebar icon: `.admin__menu .item-magesail.parent.level-0 > a:before` in [`view/adminhtml/web/css/magesail-admin-menu.css`](../Magesail/view/adminhtml/web/css/magesail-admin-menu.css) (JetRails uses `.item-jetrails` with an icon font in `vendor/jetrails/*/view/adminhtml/web/css/source/_module.less`).
|
||||
Defined in [`Magesail/etc/adminhtml/menu.xml`](../Magesail/etc/adminhtml/menu.xml). The module registers a **top-level** admin sidebar entry **MageSail** with `sortOrder="78"`. The sail icon uses `.admin__menu .item-magesail.parent.level-0 > a:before` in [`view/adminhtml/web/css/magesail-admin-menu.css`](../Magesail/view/adminhtml/web/css/magesail-admin-menu.css), following the same stacked-icon layout as Magento’s `.admin__menu-link()` pattern in the admin theme (`_menu.less`: block `::before`, `margin-bottom` on level-0 links).
|
||||
|
||||
### Manage Tunnel
|
||||
|
||||
@@ -18,17 +18,17 @@ Defined in [`Magesail/etc/adminhtml/menu.xml`](../Magesail/etc/adminhtml/menu.xm
|
||||
- **Start** — starts the Node process for that tunnel only (uses saved port and Holesail secure flag). No re-provisioning.
|
||||
- **Stop** — stops the Node process and removes that tunnel’s PID/key files; **registry row, store view, and NGINX map line stay** so you can start again.
|
||||
- **Remove** — stops the process if needed, removes the NGINX map entry, deletes the store view when safe, and removes the tunnel from the registry.
|
||||
- **Cron (dead process)** — If **Auto-restart on crash** is **No** under **Stores → Configuration → MageSail → Holesail Tunnel**, the **daily** monitor applies the same **Remove**-style teardown to any tunnel whose PID file exists but the process is no longer running (see [cron-and-monitoring.md](cron-and-monitoring.md)).
|
||||
- **Cron (dead process)** — If **Auto-restart on crash** is **No** under **MageSail → Holesail Tunnel → Configuration**, the **daily** monitor applies the same **Remove**-style teardown to any tunnel whose PID file exists but the process is no longer running (see [cron-and-monitoring.md](cron-and-monitoring.md)).
|
||||
- Each row can expand **Log tail** for `var/log/magesail_tunnel_<id>.log`.
|
||||
|
||||
**Add tunnel** (new row)
|
||||
|
||||
- **Website** and **Store group** — required; the new dedicated store view is created under that scope.
|
||||
- **Local port** — preset **443**, **80**, or **8080**, or **Custom…** with any port **1–65535**. Multiple tunnels may use the same port in configuration; whether more than one Node process can bind depends on the OS (see field note in Admin).
|
||||
- **Tunnel hostname (unsecure)** — required; hostname only (e.g. `dev.myshop.local`); stored as `http://host/`. Must match the browser / holesail-browser vhost.
|
||||
- **Tunnel hostname (unsecure)** — required; hostname only (e.g. `dev.myshop.local`); stored as `http://host/`. Must match the browser / Holesail client vhost.
|
||||
- **Tunnel hostname (secure, optional)** — same rules; stored as `https://host/` when set.
|
||||
- **Use secure URLs on storefront and in admin** — drives scoped `web/secure/*` when provisioning.
|
||||
- **Holesail secure tunnel** — private vs public Holesail mode for this tunnel (defaults from **Stores → Configuration → MageSail → Holesail Tunnel** if unset in the form).
|
||||
- **Holesail secure tunnel** — private vs public Holesail mode for this tunnel (defaults from **MageSail → Holesail Tunnel → Configuration** if unset in the form).
|
||||
- **Create and start tunnel** — provisions the store, updates the NGINX map if configured, writes the registry row, then starts Node.
|
||||
|
||||
**AJAX / JSON**
|
||||
@@ -55,6 +55,12 @@ Full-screen tools for the configured **global map** file: read raw content, writ
|
||||
|
||||
Requires **`MageSail_Magesail::config`** ACL resource. Operational details: [nginx-global-map.md](nginx-global-map.md).
|
||||
|
||||
### Configuration (store settings)
|
||||
|
||||
- **Action**: `magesail/settings/index` → [`Controller/Adminhtml/Settings/Index.php`](../Magesail/Controller/Adminhtml/Settings/Index.php) — redirects to **`adminhtml/system_config/edit`** with **`section=magesail`** (same form as legacy Stores config).
|
||||
- **Menu id**: `MageSail_Magesail::config_settings`; when that section is open, [`EditPlugin`](../Magesail/Plugin/Config/Controller/Adminhtml/System/Config/EditPlugin.php) sets the active main menu to this item.
|
||||
- **Stores → Configuration**: the **MageSail / Holesail Tunnel** section is omitted from the configuration sidebar via [`StripMagesailSectionTabFromConfigDataPlugin`](../Magesail/Plugin/Config/Structure/StripMagesailSectionTabFromConfigDataPlugin.php).
|
||||
|
||||
## ACL
|
||||
|
||||
[`Magesail/etc/acl.xml`](../Magesail/etc/acl.xml):
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Configuration
|
||||
|
||||
The module registers a **MageSail** tab in the Configuration left navigation (**Stores → Configuration**), ordered **before** the core **General** tab, with a branded tab icon. The **Holesail Tunnel** section lives under that tab.
|
||||
Store-scoped settings use Magento’s standard **System Configuration** form for section **`magesail`** ([`Magesail/etc/adminhtml/system.xml`](../Magesail/etc/adminhtml/system.xml)). In Admin, open **MageSail → Holesail Tunnel → Configuration** (redirects to that section). The **Holesail Tunnel** section is **not** listed under **Stores → Configuration** in the left tree ([`StripMagesailSectionTabFromConfigDataPlugin`](../Magesail/Plugin/Config/Structure/StripMagesailSectionTabFromConfigDataPlugin.php)); bookmarks to `adminhtml/system_config/edit` with `section=magesail` still work.
|
||||
|
||||
All paths below are under **Stores → Configuration → MageSail → Holesail Tunnel** unless noted. XML sources: [`Magesail/etc/adminhtml/system.xml`](../Magesail/etc/adminhtml/system.xml), defaults in [`Magesail/etc/config.xml`](../Magesail/etc/config.xml).
|
||||
All Admin labels below match **MageSail → Holesail Tunnel → Configuration** (section title **Holesail Tunnel**). Defaults: [`Magesail/etc/config.xml`](../Magesail/etc/config.xml).
|
||||
|
||||
## Settings (tunnel)
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ composer require magesail/magesail:^1.0
|
||||
|
||||
If the package is not on Packagist, add a **path** or **VCS** repository in the project `composer.json`, then require `@dev` or a branch alias.
|
||||
|
||||
After a **vendor** install, set **Stores → Configuration → MageSail → Holesail Tunnel → Scripts directory** to the absolute path of the `scripts` folder, for example:
|
||||
After a **vendor** install, set **MageSail → Holesail Tunnel → Configuration → Scripts directory** to the absolute path of the `scripts` folder, for example:
|
||||
|
||||
`<magento-root>/vendor/magesail/magesail/scripts`
|
||||
|
||||
@@ -57,7 +57,7 @@ npm install
|
||||
## Verification
|
||||
|
||||
- `php bin/magento module:status MageSail_Magesail` → enabled.
|
||||
- Admin: **MageSail → Holesail Tunnel** appears (**Manage Tunnel**, **NGINX Global Map**) in the main sidebar (top-level **MageSail**, before JetRails when both are installed).
|
||||
- Admin: **MageSail → Holesail Tunnel** appears (**Manage Tunnel**, **NGINX Global Map**, **Configuration**) in the main sidebar as a **top-level** **MageSail** entry (no dependency on other extensions).
|
||||
- Database: table `magesail_logs` after `setup:upgrade` (see [`Setup/InstallSchema.php`](../Magesail/Setup/InstallSchema.php)).
|
||||
- Optional: open **Manage Tunnel**, add a test tunnel (website/group, port, hostname), then **Remove** if you only wanted to verify the UI.
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
MageSail can **append** and **remove** lines inside your existing **`map $http_host $MAGE_RUN_CODE`** and **`map $http_host $MAGE_RUN_TYPE`** blocks so each tunneled hostname sets PHP-FPM bootstrap params without hand-editing Ansible. Each tunnel’s **`MAGE_RUN_CODE`** value is that tunnel’s **Magento store view code** (e.g. `mgtun_…`), as shown in **Manage Tunnel**.
|
||||
|
||||
Implementation: [`NginxGlobalMapManager`](../Magesail/Model/NginxGlobalMapManager.php), [`NginxMapParser`](../Magesail/Model/NginxMapParser.php), configured under **Stores → Configuration → MageSail → Holesail Tunnel → NGINX Configuration** (see [configuration.md](configuration.md)).
|
||||
Implementation: [`NginxGlobalMapManager`](../Magesail/Model/NginxGlobalMapManager.php), [`NginxMapParser`](../Magesail/Model/NginxMapParser.php), configured under **MageSail → Holesail Tunnel → Configuration** (group **NGINX Configuration**; see [configuration.md](configuration.md)).
|
||||
|
||||
## Validation strategy
|
||||
|
||||
|
||||
+1
-1
@@ -9,7 +9,7 @@ MageSail exposes a local Magento instance through **Holesail** P2P tunnels. Admi
|
||||
|
||||
## High-level flow
|
||||
|
||||
1. Admin configures **Stores → Configuration → MageSail → Holesail Tunnel** (default secure mode, default port for new forms, scripts path, auto-restart, NGINX paths).
|
||||
1. Admin configures **MageSail → Holesail Tunnel → Configuration** (default secure mode, default port for new forms, scripts path, auto-restart, NGINX paths).
|
||||
2. Under **Manage Tunnel → Add tunnel**, Admin picks website/group, port, hostnames, and options; the module creates a **new store view**, appends **hostname → store code** lines to the configured **global map** (if configured), writes **`var/magesail_tunnels.json`**, and starts Node for that tunnel id.
|
||||
3. Incoming HTTP(S) requests can bind to the tunnel store via **header**, **query**, **`___store`**, **hostname match** against persisted base URLs in the registry, or **NGINX `MAGE_RUN_*`** when the map is active. **Non-existent** store codes from nginx or bookmarks are ignored so Magento can fall back (see [`StoreFromMageSailHeaderPlugin`](../Magesail/Plugin/App/Request/StoreFromMageSailHeaderPlugin.php)).
|
||||
4. Plugins adjust **admin front name resolution**, **store base URLs** for links, and **skip redirect-to-base** for tunnel traffic so local/proxy URLs stay usable.
|
||||
|
||||
@@ -9,6 +9,7 @@ Module namespace: **`MageSail\Magesail`**. Paths are relative to [`Magesail/`](.
|
||||
| `Tunnel\Index` | `Controller/Adminhtml/Tunnel/Index.php` | Tunnel page; create/start/stop/delete tunnels; JSON/AJAX responses. |
|
||||
| `Tunnel\Status` | `Controller/Adminhtml/Tunnel/Status.php` | JSON status for one tunnel (`tunnel_id`) or all tunnels. |
|
||||
| `Tunnel\Logtail` | `Controller/Adminhtml/Tunnel/Logtail.php` | JSON tail of a tunnel log file (`tunnel_id`). |
|
||||
| `Settings\Index` | `Controller/Adminhtml/Settings/Index.php` | Redirect to system config `section=magesail` (MageSail menu **Configuration**). |
|
||||
| `Nginx\Map` | `Controller/Adminhtml/Nginx/Map.php` | NGINX Global Map UI actions: read, write, validate, reload, parse, save_blocks, diagnostics. |
|
||||
|
||||
## Blocks (`Block/Adminhtml/`)
|
||||
@@ -43,7 +44,7 @@ Module namespace: **`MageSail\Magesail`**. Paths are relative to [`Magesail/`](.
|
||||
|
||||
## Plugins (`Plugin/`)
|
||||
|
||||
See [request-routing-and-plugins.md](request-routing-and-plugins.md) for behavior; files live under `Plugin/App/Request/`, `Plugin/Backend/App/Area/`, `Plugin/Store/`, `Plugin/FrontController/`.
|
||||
See [request-routing-and-plugins.md](request-routing-and-plugins.md) for behavior; files live under `Plugin/App/Request/`, `Plugin/Backend/App/Area/`, `Plugin/Store/`, `Plugin/FrontController/`, `Plugin/Config/…` (system config nav: `StripMagesailSectionTabFromConfigDataPlugin`, `EditPlugin`).
|
||||
|
||||
## Setup
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Legacy installs migrated from older MageSail may still use the deprecated code *
|
||||
|
||||
You must supply at least the **unsecure hostname** (e.g. `dev.myshop.local` without `http://`). The module saves **`http://hostname/`** as the unsecure base URL. Optional **secure hostname** (without `https://`) becomes **`https://hostname/`**. You can still paste a full `http://` or `https://` URL; schemes are preserved when already present.
|
||||
|
||||
The configured base URLs must match what users see in the browser when using holesail-browser (or your proxy) for host/scheme expectations.
|
||||
The configured base URLs must match what users see in the browser when using a Holesail client (or your proxy) for host/scheme expectations.
|
||||
|
||||
**Use secure URLs on storefront and in admin** drives scoped configuration:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user