Env: HTTPS Support

packages/env/.gitignore

@@ -1,2 +1,2 @@
 # Build
-/lib/docker-compose.yml
+/lib/docker-compose.yml

packages/env/README.md

@@ -183,7 +183,7 @@ Out of the box `wp-env` includes the [WordPress' PHPUnit test files](https://dev
 
 While we do provide a default `wp-tests-config.php` file within the environment, there may be cases where you want to use your own. WordPress provides a `WP_TESTS_CONFIG_FILE_PATH` constant that you can use to change the `wp-config.php` file used for testing. Set this to a desired path in your `bootstrap.php` file and the file you've chosen will be used instead of the one included in the environment.
 
-## Using `composer`, `phpunit`, and `wp-cli` tools.
+## Using `composer`, `phpunit`, and `wp-cli` tools
 
 For ease of use, Composer, PHPUnit, and wp-cli are available for in the environment. To run these executables, use `wp-env run <env> <tool> <command>`. For example, `wp-env run cli composer install`, or `wp-env run tests-cli phpunit`. You can also access various shells like `wp-env run cli bash` or `wp-env run cli wp shell`.
 
@@ -262,6 +262,41 @@ Here is a summary:
 4. Launch the debugger and put a breakpoint on any line of PHP code.
 5. Refresh the URL wp-env is running at and the breakpoint should trigger.
 
+## HTTPS/TLS/SSL Support
+
+In order to easily add a certificate for HTTPS, configuration options have been added to pass a TLS certificate and key, as well as the ability to define their separate ports, which default to `8883` for development and `8884` for test. This way, you can use whatever tool you like to create a TLS certificate and use it in your environments.
+
+By using `.wp-env.override.json`, you can define a personal TLS certificate without disrupting a projects `.wp-env.json` configuration.
+
+This can be defined as root settings, as shown here, which will get moved to the development and tests environments when parsed.
+
+```json
+{
+	"ssl": {
+		"cert": "\etc\ssl\certs\localhost.crt",
+		"key": "\etc\ssl\certs\localhost.key",
+		"port": 8883,
+		"testsPort": 8884,
+	}
+}
+```
+
+Or it can be defined per environment:
+
+```json
+{
+	"env": {
+		"development": {
+			"ssl": {
+				"cert": "\etc\ssl\certs\localhost.crt",
+				"key": "\etc\ssl\certs\localhost.key",
+				"port": 8883,
+			}
+		}
+	}
+}
+```
+
 ## Command reference
 
 `wp-env` creates generated files in the `wp-env` home directory. By default, this is `~/.wp-env`. The exception is Linux, where files are placed at `~/wp-env` [for compatibility with Snap Packages](https://github.com/WordPress/gutenberg/issues/20180#issuecomment-587046325). The `wp-env` home directory contains a subdirectory for each project named `/$md5_of_project_path`. To change the `wp-env` home directory, set the `WP_ENV_HOME` environment variable. For example, running `WP_ENV_HOME="something" wp-env start` will download the project files to the directory `./something/$md5_of_project_path` (relative to the current directory).
@@ -487,10 +522,11 @@ You can customize the WordPress installation, plugins and themes that the develo
 | `"themes"`     | `string[]`     | `[]`                                   | A list of themes to install in the environment.                                                                                  |
 | `"port"`       | `integer`      | `8888` (`8889` for the tests instance) | The primary port number to use for the installation. You'll access the instance through the port: 'http://localhost:8888'.       |
 | `"testsPort"`  | `integer`      | `8889`                                 | The port number for the test site. You'll access the instance through the port: 'http://localhost:8889'.                         |
+| `"ssl"`        | `Object`       | `{ "cert": null, "key": null, "port": 8883, "testsPort": 8884 }` | Defines options for SSL/TLS/HTTPS support. Providing a path for `cert` and `key` will enable HTTPS.    |
 | `"config"`     | `Object`       | See below.                             | Mapping of wp-config.php constants to their desired values.                                                                      |
 | `"mappings"`   | `Object`       | `"{}"`                                 | Mapping of WordPress directories to local directories to be mounted in the WordPress instance.                                   |
 
-_Note: the port number environment variables (`WP_ENV_PORT` and `WP_ENV_TESTS_PORT`) take precedent over the .wp-env.json values._
+_Note: the port number environment variables (`WP_ENV_PORT`, `WP_ENV_TESTS_PORT`, `WP_ENV_SSL_PORT`, `WP_ENV_SSL_TESTS_PORT`) take precedent over the .wp-env.json values._
 
 Several types of strings can be passed into the `core`, `plugins`, `themes`, and `mappings` fields.
 

packages/env/lib/build-docker-compose-config.js

@@ -54,6 +54,11 @@ function getMounts(
 			? `user-home:/home/${ hostUsername }`
 			: `tests-user-home:/home/${ hostUsername }`;
 
+	const sslMount = [];
+	if ( config.ssl !== undefined && config.ssl.cert ) {
+		sslMount.push( workDirectoryPath + `/ssl:/home/${ hostUsername }/ssl` );
+	}
+
 	const corePHPUnitMount = `${ path.join(
 		workDirectoryPath,
 		wordpressDefault === 'wordpress'
@@ -72,6 +77,7 @@ function getMounts(
 			coreMount, // Must be first because of some operations later that expect it to be!
 			corePHPUnitMount,
 			userHomeMount,
+			...sslMount,
 			...directoryMounts,
 			...pluginMounts,
 			...themeMounts,
@@ -165,8 +171,32 @@ module.exports = function buildDockerComposeConfig( config ) {
 	}
 
 	// Set the default ports based on the config values.
-	const developmentPorts = `\${WP_ENV_PORT:-${ config.env.development.port }}:80`;
-	const testsPorts = `\${WP_ENV_TESTS_PORT:-${ config.env.tests.port }}:80`;
+	const developmentPorts = [
+		`\${WP_ENV_PORT:-${ config.env.development.port }}:80`,
+	];
+	const testsPorts = [
+		`\${WP_ENV_TESTS_PORT:-${ config.env.tests.port }}:80`,
+	];
+
+	// Set the default SSL ports based on the config values.
+	if (
+		config.env.development.ssl !== undefined &&
+		config.env.development.ssl.cert &&
+		config.env.development.ssl.port
+	) {
+		developmentPorts.push(
+			`\${WP_ENV_PORT:-${ config.env.development.ssl.port }}:443`
+		);
+	}
+	if (
+		config.env.tests.ssl !== undefined &&
+		config.env.tests.ssl.cert &&
+		config.env.tests.ssl.port
+	) {
+		testsPorts.push(
+			`\${WP_ENV_TESTS_PORT:-${ config.env.tests.ssl.port }}:443`
+		);
+	}
 
 	return {
 		version: '3.7',
@@ -200,7 +230,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 					dockerfile: 'WordPress.Dockerfile',
 					args: imageBuildArgs,
 				},
-				ports: [ developmentPorts ],
+				ports: developmentPorts,
 				environment: {
 					APACHE_RUN_USER: '#' + hostUser.uid,
 					APACHE_RUN_GROUP: '#' + hostUser.gid,
@@ -218,7 +248,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 					dockerfile: 'Tests-WordPress.Dockerfile',
 					args: imageBuildArgs,
 				},
-				ports: [ testsPorts ],
+				ports: testsPorts,
 				environment: {
 					APACHE_RUN_USER: '#' + hostUser.uid,
 					APACHE_RUN_GROUP: '#' + hostUser.gid,

packages/env/lib/config/get-config-from-environment-vars.js

@@ -34,6 +34,10 @@ module.exports = function getConfigFromEnvironmentVars( cacheDirectoryPath ) {
 	const environmentConfig = {
 		port: getPortFromEnvironmentVariable( 'WP_ENV_PORT' ),
 		testsPort: getPortFromEnvironmentVariable( 'WP_ENV_TESTS_PORT' ),
+		ssl: {
+			port: getPortFromEnvironmentVariable( 'WP_ENV_SSL_PORT' ),
+			testsPort: getPortFromEnvironmentVariable( 'WP_ENV_SSL_TESTS_PORT' ),
+		},
 		lifecycleScripts: getLifecycleScriptOverrides(),
 	};
 

packages/env/lib/config/merge-configs.js

@@ -53,6 +53,10 @@ function mergeConfig( config, toMerge ) {
 				);
 				break;
 			}
+			case 'ssl': {
+				config.ssl = Object.assign( config.ssl, toMerge.ssl );
+				break;
+			}
 
 			// Environment-specific config options are recursively merged.
 			case 'env': {

packages/env/lib/config/parse-config.js

@@ -14,6 +14,7 @@ const {
 } = require( './parse-source-string' );
 const {
 	ValidationError,
+	checkString,
 	checkPort,
 	checkStringArray,
 	checkObjectWithValues,
@@ -35,6 +36,7 @@ const mergeConfigs = require( './merge-configs' );
  * @typedef WPRootConfigOptions
  * @property {number}                               port                          The port to use in the development environment.
  * @property {number}                               testsPort                     The port to use in the tests environment.
+ * @property {Object.<string, string|number|null>}  ssl                           The ssl certificate, key, and port numbers.
  * @property {Object.<string, string|null>}         lifecycleScripts              The scripts to run at certain points in the command lifecycle.
  * @property {Object.<string, string|null>}         lifecycleScripts.afterStart   The script to run after the "start" command has completed.
  * @property {Object.<string, string|null>}         lifecycleScripts.afterClean   The script to run after the "clean" command has completed.
@@ -50,11 +52,21 @@ const mergeConfigs = require( './merge-configs' );
  * @property {WPSource[]}                pluginSources Plugins to load in the environment.
  * @property {WPSource[]}                themeSources  Themes to load in the environment.
  * @property {number}                    port          The port to use.
+ * @property {WPSSLConfig}               ssl           The ssl certificate, key, and port number.
  * @property {Object}                    config        Mapping of wp-config.php constants to their desired values.
  * @property {Object.<string, WPSource>} mappings      Mapping of WordPress directories to local directories which should be mounted.
  * @property {string|null}               phpVersion    Version of PHP to use in the environments, of the format 0.0.
  */
 
+/**
+ * The SSL configuration options.
+ *
+ * @typedef WPSSLConfig
+ * @property {string} cert The path to the SSL certificate.
+ * @property {string} key  The path to the SSL key.
+ * @property {number} port The port to use for SSL.
+ */
+
 /**
  * The root configuration options.
  *
@@ -85,6 +97,12 @@ const DEFAULT_ENVIRONMENT_CONFIG = {
 	themes: [],
 	port: 8888,
 	testsPort: 8889,
+	ssl: {
+		cert: null,
+		key: null,
+		port: 8883,
+		testsPort: 8884,
+	},
 	mappings: {},
 	config: {
 		FS_METHOD: 'direct',
@@ -281,6 +299,21 @@ function getEnvironmentVarOverrides( cacheDirectoryPath ) {
 		overrideConfig.env.tests.port = overrides.testsPort;
 	}
 
+	if ( overrides.ssl ) {
+		overrideConfig.ssl = {};
+		overrideConfig.env.development.ssl = {};
+		overrideConfig.env.tests.ssl = {};
+
+		if ( overrides.ssl.port ) {
+			overrideConfig.ssl.port = overrides.ssl.port;
+			overrideConfig.env.development.ssl.port = overrides.ssl.port;
+		}
+		if ( overrides.ssl.testsPort ) {
+			overrideConfig.ssl.testsPort = overrides.ssl.testsPort;
+			overrideConfig.env.tests.ssl.port = overrides.ssl.testsPort;
+		}
+	}
+
 	if ( overrides.coreSource ) {
 		overrideConfig.coreSource = overrides.coreSource;
 		overrideConfig.env.development.coreSource = overrides.coreSource;
@@ -436,6 +469,35 @@ async function parseEnvironmentConfig(
 		parsedConfig.port = config.port;
 	}
 
+	if ( config.ssl !== undefined ) {
+		parsedConfig.ssl = config.ssl;
+		if ( config.ssl.port !== undefined ) {
+			checkPort(
+				configFile,
+				`${ environmentPrefix }ssl.port`,
+				config.ssl.port
+			);
+			parsedConfig.ssl.port = config.ssl.port;
+		}
+		if ( config.ssl.key ) {
+			checkString(
+				configFile,
+				`${ environmentPrefix }ssl.key`,
+				config.ssl.key
+			);
+			parsedConfig.ssl.key = config.ssl.key;
+		}
+		parsedConfig.ssl.key = config.ssl.key;
+		if ( config.ssl.cert ) {
+			checkString(
+				configFile,
+				`${ environmentPrefix }ssl.cert`,
+				config.ssl.cert
+			);
+			parsedConfig.ssl.cert = config.ssl.cert;
+		}
+	}
+
 	if ( config.phpVersion !== undefined ) {
 		// Support null as a valid input.
 		if ( config.phpVersion !== null ) {