Skip to main content

Webserver

start serves the site with PHP's built-in webserver, at a URL such as http://localhost:8000. This page covers where the site is served, how the port is picked and how several projects share a machine.

start prints the URL when the server is ready, and stop stops it again:

make start   # Start the webserver
make stop    # Stop it

The hostname is localhost unless you set WEBSERVER_HOST. To serve on every interface, set it to 0.0.0.0. The server serves build/web through Drupal's own router. It writes its output to .logs/php.log in the project root, and each start empties that file first.

How the port is picked​

start takes the port from the first of these that sets it:

  1. WEBSERVER_PORT in your shell - used as it is. Prefix a single command with it, such as WEBSERVER_PORT=9000, for a one-off run.
  2. WEBSERVER_PORT in the project's .env file - used as it is.
  3. Neither - start picks the first free port from 8000 to 8099 and saves it to .env as WEBSERVER_PORT.

When another process holds a port from your shell or .env, start fails (see Projects that share a machine).

After the port is in .env, every command that reaches the site reuses it: assemble, build, stop, reset, provision, info, debug, drush, login and the test commands. make and Ahoy load .env on their own. The project's .gitignore lists the file.

To check where the port came from, run info:

make info

info is read-only, so it never picks or saves a port. Its Webserver port line ends with the port's source, such as 8002 (.env).

Under make and Ahoy, a port from .env reaches info as an environment variable, like a port from your shell. So info labels the port by comparing it with .env:

  • (env) - your shell sets the port, and .env holds a different one or none.
  • (.env) - the port is the one in .env, even when your shell sets the same port.
  • (default) - neither sets the port, so info shows 8000, the first port that start tries.

To switch from a port in your shell to the one in .env:

  1. Run stop while your shell still sets the port. It stops the server on that port.
  2. Run unset WEBSERVER_PORT.
  3. If your shell profile exports WEBSERVER_PORT, remove that line, so new shells don't set it again.
  4. Run start. It serves the site on the port in .env, and info shows (.env).

To move the site to another port:

  1. Run stop. It finds the server through the port in .env, so stop the server before you change that port.
  2. Set WEBSERVER_PORT in .env to the new port, such as WEBSERVER_PORT=8010.
  3. Run start. It serves the site on the new port.

To have start pick a port again, delete the WEBSERVER_PORT line from .env. start then takes the first free port from 8000, which can be the port that stop freed.

A port from your shell isn't saved

A WEBSERVER_PORT in your shell wins over the one in .env. make and Ahoy keep the shell value when they load .env. start doesn't save it to .env, so commands without the prefix use the port in .env. While that server runs, prefix every command the same way.

Projects that share a machine​

Another project can record the same port as yours. Each command that stops a webserver stops only the project's own: the server of build/web, recognized by its command line. These commands are stop, assemble and reset, plus start before it restarts the server. Where they can't read command lines, such as on a system without ps, they stop every process that listens on the port.

When another process holds the port, stop, assemble and reset leave it running. start fails and prints the process ID and command line of each process on the port. Stop that process, or set WEBSERVER_PORT in .env to a free port.

Startup timeout​

After it launches the server, start waits up to WEBSERVER_WAIT_TIMEOUT seconds for the server to accept connections. The timeout defaults to 5 and takes a whole number of 1 or more. On any other value, start stops with an error. To give a slow machine more time, raise the timeout in .env:

.env
WEBSERVER_WAIT_TIMEOUT=15

When the server doesn't accept connections in time, start fails and prints the server's log. After the server accepts connections, start requests the front page to check that it can serve the site. It waits up to 5 seconds for the answer, whatever WEBSERVER_WAIT_TIMEOUT holds. It fails unless the status is 200 or 302.

Last, start opens the public tunnel when CLOUDFLARE_TUNNEL turns it on, and runs your scripts/start-*.sh lifecycle scripts.