Previewing a Static Site

Overview

Once you've generated your static site, it's time for a preview. You want to make sure everything looks correct, that all the expected paths are there, and that you haven't exported any paths you didn't mean to.

Now, you can't just open the export folder in your file browser and open any of the HTML files. I mean, you can, but the site likely won't look right and links won't work correctly.

To properly preview the site, you need to serve it locally like a web server would.

How to serve your site depends on whether you have Drupal site installed directly on your host machine (desktop or laptop), or whether you're using a containerised / dockerised environment like DDEV or Lando.

As always there are several approaches that give similar results. None is necessarily better than the other, it's all a matter of what you find most convenient for your way of doing things.

Note: Be careful when you makes changes in your Drupal site and re-export your site: changes to your static site will be ignored until you restart your preview server.

Scenario 1 - Preview on HOST machine using tome:preview

If you're NOT using a containerised environment like DDEV, and your Drupal site is installed directly on your host machine (possibly via solution like XAMP), you can use the tome:preview drush command to preview the static site:

drush tome:preview

Output:

[OK] Static site server running at http://127.0.0.1:8889/
You can now browse to http://127.0.0.1:8889 and you should see your static site.

You can now browse to your static site at http://127.0.0.1:8889.  

Note: this approach will not work if you run this command inside DDEV, for reasons explained below.

Scenario 2 - Preview on HOST machine using PHP's built-in server

If you're NOT using a DDEV, and your Drupal site is installed directly on your host machine, you can use PHP's built-in server:

php -S 127.0.0.1:8889 -t /path/to/your/drupal/project/static

You can now browse to http://127.0.0.1:8889 or http://localhost:8889, and you should see your static site.

Scenario 3: Preview inside DDEV using tome:preview

This is currently broken. 

At the time of writing, tome:preview hard-codes the preview url as 127.0.0.1. This is fine if you run tome:preview directly on your host machine, but causes trouble when you run it inside DDEV.

There's an issue for this in the Tome issue queue, and a fix is waiting to be committed. Until then, if you want to run tome:preview inside DDEV, apply the provided patch.

If you go this route, be sure to follow the "Expose additional ports" step explained in the next scenario. This step is not optional.

Scenario 4: Preview inside DDEV using PHP's built-in server

Before you can PHP's built-in webserver inside DDEV and make it accessible from outside the container (e.g. from your browser), you need to:

  1. Expose additional ports in .ddev/config.yaml.
  2. Restart DDEV.
  3. Start PHP's built-in webserver inside DDEV using the correct port information.

Expose additional ports in DDEV's config.yaml

You're going to run PHP's built-in web server inside DDEV on a certain port. You need to expose that port to the outside world so your browser can reach it. This is explained in the DDEV documentation: Exposing extra ports.

Add the following to your .ddev/yaml.config, choosing any free port number. You're probably safe to just copy/paste this example:

File: .ddev/config.yaml

web_extra_exposed_ports:
  - name: tome_preview
    container_port: 8889
    http_port: 8888
    https_port: 8889
  • name: choose any name to identify the extra service you are configuring
  • container_port: the port you want the built-in server to use inside DDEV
  • https_port: the port to use to access your static site over HTTP
  • https_port: the port to use to access your static site over HTTPS

Restart DDEV

ddev restart

Run built-in server

php -S 0.0.0.0:3901 -t /var/www/html/static
  • Be sure to use 0.0.0.0 as the IP address. This is required to ensure the new service will be accessible outside DDEV. (Learn more: 0.0.0.0 catch-all address)
  • Be sure to use the same port number as the one you configured for container_port number in .ddev/config.yaml. In our example that was 8889.
  • Be sure to point to the correct directory inside DDEV that contains your static site. By default this will be /var/www/html/html (assuming DDEV's default directory structure). If you renamed the export directory to static, you'll want to point to /var/www/html/static.

Access the Static Site

If all this went well, you should be able to browse to your static site using https://<project_name>.ddev.site:<https_port>.

In our case: https://mysite.ddev.site:8889

Optional: Run preview server via custom Composer script

You may want to add a convenient Composer script to start the built-in server without having to remember all these details.

To do so, add the following to the your project's top-level composer.json:

File: /var/www/html/composer.json

   "scripts": {
       "preview" : "php -S 0.0.0.0:8889 -t /var/www/html/static",
   }

You can now use the command composer preview inside DDEV to start your preview server:

composer preview