Home / Documentation / Administrator Guide / Deployment / Local Directory

Local Directory

Introduction

The Local Directory deployment method allows you to deploy your static site to a directory on the same server hosting your WordPress installation. The chosen directory is usually configured as the webserver’s document root or “public_html” for the static site.

Use this method when WordPress and the static site are hosted on the same server and the WordPress process can write to the static site’s document root.

This deployment method supports:

  • Deployment to a directory on the same server;
  • Support for HTTP redirects;
  • Support for MIME type rules needed by generated files;
  • Support for custom error page;
  • Retaining specific pre-existing files or directories in the target directory;
  • Symlink or copy handling for the WordPress uploads directory.

Preparation

In order to use this deployment method, both your dynamic WordPress site and your static site need to be hosted on the same server. The static site’s document root (for example httpdocs or public_html) needs to be writable from your WordPress installation.

Considering the following setup:

Domain Document Root
wordpress.example.com /home/user/domains/wordpress.example.com/public_html/
www.example.com /home/user/domains/www.example.com/public_html/

Staatic would publish your static site’s assets to /home/user/domains/www.example.com/public_html/ (the target directory in this case).

Note: HTTP redirects, generated MIME type rules and a custom error page are only supported on Apache or Nginx.

Configuration

In order to configure the Local Directory deployment method, head over to the WordPress Admin and click Staatic > Settings > Deployment. Choose Local Directory as the deployment method and make sure the following fields are entered correctly.

Target Directory

The path to the directory on the filesystem where the static version of your site is deployed. Staatic will create this directory if it does not exist, but the parent location must be writable by WordPress.

Note: by default, the Target Directory is set to a subdirectory of the WordPress uploads directory. This should be adjusted depending on your setup. See Preparation for more information.

The target directory cannot be the WordPress installation directory itself or a parent directory of the WordPress installation. This prevents a deployment from overwriting the dynamic WordPress site.

How Deployment Sync Works

Local Directory deployments are synchronizing deployments. Staatic writes the build to a staging directory first, then mirrors that staging directory to the configured target directory when deployment finishes.

Files and directories in the target directory that are not part of the latest build are removed unless they are listed under Retain Files/Directories. Keep unrelated files, verification files, or host-managed files out of the target directory unless they are explicitly retained.

Configuration Files

Depending on your hosting environment you can choose to generate an .htaccess configuration file or nginx_rules.conf file that enables HTTP redirects, MIME type rules and the custom error page.

Generate Apache Configuration

Enable this option if you’re on an Apache webserver. When enabled, an .htaccess file will be generated and placed inside the configured target directory.

Note: make sure that your webserver configuration has the AllowOverride option enabled. Without AllowOverride the .htaccess file will not be applied. Check the documentation for more information.

Generate Nginx Configuration

Enable this option if you’re on a Nginx webserver which imports this configuration file. When enabled, a nginx_rules.conf file will be generated and placed inside the configured target directory.

Note: in order to import the nginx_rules.conf configuration file, make sure to include it within your virtual host. Check the documentation for more information.

Retain Files/Directories

Optionally add file or directory paths (absolute or relative to the target directory) that need to be left intact (one path per line).

Note: files existing in the target directory that are not part of the build and not in this list will be deleted upon deployment.

Retain paths must already exist when the setting is saved. Paths that cannot be resolved are skipped instead of being used during deployment.

Examples: favicon.ico, robots.txt, a search-engine verification file, or a host-managed directory that must survive each deployment.

Symlink/Copy Uploads

Enabling this option makes sure that every file within the WordPress uploads directory is available on the static site without crawling and processing each upload as a separate build result.

On Linux environments, Staatic uses a symbolic link for the uploads directory. On Windows, it copies the uploads directory instead. When this option is enabled, uploads URLs are excluded from crawling because the files are provided directly by the symlink or copy.

Note: this can greatly improve publication speed for media-heavy sites, but it also means the target webserver must be able to serve the linked or copied uploads path correctly.