Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: refactor README #60

Merged
merged 8 commits into from
Dec 5, 2024
Merged

docs: refactor README #60

Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
85484f8
Standardize Browsersync capitalization
tyler36 Dec 3, 2024
95e9452
fix Wordpress TOC entry
tyler36 Dec 3, 2024
1c78eb9
use "-" instead of "*" for bullets
tyler36 Dec 3, 2024
5bb7620
remove duplicate spaces
tyler36 Dec 3, 2024
fe6e401
update "Getting Started"
tyler36 Dec 3, 2024
434b1d5
refactor usage and problems sections
tyler36 Dec 3, 2024
ee286ab
docs: add "auto-start" section
tyler36 Dec 3, 2024
1873b7d
default to "ddev add-on get"
tyler36 Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 96 additions & 60 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,17 @@

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Auto-start the watcher server](#auto-start-the-watcher-server)
- [What does this add-on do?](#what-does-this-add-on-do)
- [Other ways to use Browsersync with this add-on](#other-ways-to-use-browsersync-with-this-add-on)
- [Basic usage](#basic-usage)
- [Problems](#problems)
- [Laravel-mix configuration](#laravel-mix-configuration)
- [Integrations](#integrations)
- [Laravel Mix Configuration](#laravel-mix-configuration)
- [WordPress Configuration Changes](#wordpress-configuration-changes)
- [Others](#others)
- [Troubleshooting](#troubleshooting)
- [No Gateway / 502 error](#no-gateway--502-error)
- [Unknown command "browsersync" for "ddev"](#unknown-command-browsersync-for-ddev)
- [System limit for number of file watchers reached](#system-limit-for-number-of-file-watchers-reached)
- [Contributing](#contributing)

## Introduction

Expand All @@ -22,46 +28,56 @@ This add-on allows you to run [Browsersync](https://browsersync.io/) through the

## Getting Started

- Install the DDEV Browsersync add-on:
1. Install the DDEV Browsersync add-on:

```shell
# For DDEV v1.23.5 or above run
For DDEV v1.23.5 or above run
tyler36 marked this conversation as resolved.
Show resolved Hide resolved

```sh
ddev add-on get ddev/ddev-browsersync
# For earlier versions of DDEV run
```

For earlier versions of DDEV run

```sh
ddev get ddev/ddev-browsersync
# Then for all versions:
ddev restart
ddev browsersync
```

The new `ddev browsersync` global command runs Browsersync inside the web container and provides a
link to the Browsersync proxy URL, something like `https://<project>.ddev.site:3000`.
1. Use the custom command, `ddev browsersync`, to start the watcher

The Browsersync’d URL is ***HTTPS***, not HTTP. ddev-router redirects traffic to HTTPS, but Browsersync does not know this.
```shell
$ ddev browsersync
Proxying browsersync on https://mysite.ddev.site:3000
[Browsersync] Proxying: http://localhost
[Browsersync] Watching files...
```

EG.
"External: <http://d9.ddev.site:3000>" => Access on **<https://d9.ddev.site:3000>**
1. Launch the Browsersync page, via the `Proxying browsersync` URL shown in your terminal or `ddev launch :3000`

```shell
ddev launch :3000
```

> :bulb: This add-on moves to a per-project approach in v2.5.0+. You can safely delete the global `~/.ddev/commands/web/browsersync` once you’re on v2.5.0 or higher—this will not affect usage.
The site should briefly display "Browsersync: connect" in the top right corner, confirming it is connect to the server.

### Auto-start the watcher server

If you run `ddev browsersync` from a local project and get `Error: unknown command "browsersync" for "ddev"`, run the following to add the command to the project:
You can use DDEV's `post-start` hook to start the watcher server and launch the page when DDEV starts.

For DDEV v1.23.5 or above run
1. Create a `.ddev/config.browsersync-extras.yaml`

```sh
ddev add-on get ddev/ddev-browsersync
```yml
hooks:
post-start:
- exec-host: bash -c "ddev browsersync &"
- exec-host: ddev launch :3000
```

For earlier versions of DDEV run
1. Restart DDEV to apply the changes.

```sh
ddev get ddev/ddev-browsersync
```shell
ddev restart
```

Once Browsersync is running, visit `https://<project>.ddev.site:3000` or run `ddev launch :3000` to launch the proxy URL in a web browser.

## What does this add-on do?

1. Checks to make sure the DDEV version is adequate.
Expand All @@ -71,40 +87,15 @@ Once Browsersync is running, visit `https://<project>.ddev.site:3000` or run `dd
5. Adds a `ddev browsersync` shell command, which lets you easily start Browsersync when you want it.

For WordPress projects, this add-on also:
* Adds a `wp-config-ddev-browser.php` file which modifies the WP_HOME and WP_SITEURL values to work with Browsersync.
* On install, modifies the `wp-config-ddev.php` file to include the `wp-config-ddev-browser.php` file.

## Other ways to use browsersync with this add-on

There are many other options to integrate browsersync into your project, including:

- [Grunt](https://browsersync.io/docs/grunt)
- [Laravel Mix](https://laravel-mix.com/docs/4.0/browsersync)

Please see [Browsersync documentation](https://browsersync.io/docs) for more details.
PRs for install steps for specific frameworks are welcome.

### Basic usage
- Adds a `wp-config-ddev-browser.php` file which modifies the WP_HOME and WP_SITEURL values to work with Browsersync.
- On install, modifies the `wp-config-ddev.php` file to include the `wp-config-ddev-browser.php` file.

The existing example with just `ddev browsersync` should work out of the box.
There is no need for additional configuration, but you may want to edit
the `.ddev/browser-sync.js` file to specify exactly what files and directories
should be watched. If you watch less things it’s easier on your computer.
## Integrations

### Problems

- If you get `Error: ENOSPC: System limit for number of file watchers reached, watch '/var/www/html/web/core/themes/classy/images/icons/video-x-generic.png'` it means you either have to increase the file watcher limit or decrease the number of files you’re watching.
- To decrease the number of files you’re watching, edit the `ignore` section in `browser-sync.js` (or another config file if you have a more complex setup).
- On Colima, run `colima ssh` and `sudo sysctl fs.inotify.max_user_watches` to see how many watches you have. To increase it, use something like `sudo sysctl -w fs.inotify.max_user_watches=2048576`. Unfortunately, this has to be done on every Colima restart.
- On Docker Desktop for Mac, `docker run -it --privileged --pid=host justincormack/nsenter1` and `sysctl -w fs.inotify.max_user_watches=1048576`. Unfortunately, this has to be done again on every Docker restart.
- On Docker Desktop for Windows, add or edit `~/.wslconfig` with these contents:

```config
[wsl2]
kernelCommandLine = "fs.inotify.max_user_watches=1048576"
```

- On Linux, you can change `fs.inotify.max_user_watches` on the host in `/etc/sysctl.d/local.conf` or elsewhere.
`ddev-browsersync` works out of the box for many project types.
However, you may want to edit the `.ddev/browser-sync.js` file to specify exactly what files and directories
should be watched. Limiting watched files may reduce hard disk and CPU loads.

### Laravel Mix Configuration

Expand Down Expand Up @@ -143,9 +134,7 @@ ddev exec npm run watch

- Browsersync will be running on **HTTPS** at `https://browsersync-demo.ddev.site:3000`

**Contributed and maintained by [tyler36](https://github.com/tyler36)**

### WordPress Configuration Changes.
### WordPress Configuration Changes

The changes this add-on makes to the `wp-config-ddev.php` file during installation can be seen below.

Expand Down Expand Up @@ -175,3 +164,50 @@ defined( 'WP_HOME' ) || define( 'WP_HOME', 'https://projectname.ddev.site' );
/** WP_SITEURL location */
defined( 'WP_SITEURL' ) || define( 'WP_SITEURL', WP_HOME . '/' );
```

### Others

There are many other options to integrate Browsersync into your project, including:

- [Grunt](https://browsersync.io/docs/grunt)
- [Laravel Mix](https://laravel-mix.com/docs/4.0/browsersync)

Please see [Browsersync documentation](https://browsersync.io/docs) for more details.

## Troubleshooting

### No Gateway / 502 error

This error usually occurs when the watcher server is not running.
Run `ddev browsersync` to start the server.

### Unknown command "browsersync" for "ddev"

> :bulb: This add-on moves to a per-project command approach in v2.5.0+. You can safely delete the global `~/.ddev/commands/web/browsersync` once you’re on v2.5.0 or higher.

If you run `ddev browsersync` from a local project and get `Error: unknown command "browsersync" for "ddev"`, please reinstall the add-on.

### System limit for number of file watchers reached

This error means the watcher is unable to track all the files it is tasked with watching.
You either have to decrease the number of files you’re watching or increase the file watcher limit.

- Decrease the number of files you're watching by updating `browser-sync.js`:
- Limit the number of files being watch by updating `files: [...]` section
- Increase the number of ignored files by updating the `ignore: []` section
- If you use Colima, run `colima ssh` and `sudo sysctl fs.inotify.max_user_watches` to see how many watches you have. To increase it, use something like `sudo sysctl -w fs.inotify.max_user_watches=2048576`. Unfortunately, this has to be done on every Colima restart.
- If you use Docker Desktop for Mac, `docker run -it --privileged --pid=host justincormack/nsenter1` and `sysctl -w fs.inotify.max_user_watches=1048576`. Unfortunately, this has to be done again on every Docker restart.
- On Docker Desktop for Windows, add or edit `~/.wslconfig` with these contents:

```conf
[wsl2]
kernelCommandLine = "fs.inotify.max_user_watches=1048576"
```

- On Linux, you can change `fs.inotify.max_user_watches` on the host in `/etc/sysctl.d/local.conf` or elsewhere.

## Contributing

PRs for install steps for specific frameworks are welcome.

**Contributed and maintained by [tyler36](https://github.com/tyler36)**
Loading