diff --git a/.github/workflows/vitest.yml b/.github/workflows/vitest.yml new file mode 100644 index 0000000000..fd7c0f1c38 --- /dev/null +++ b/.github/workflows/vitest.yml @@ -0,0 +1,23 @@ +name: JavaScript Unit Tests +on: + pull_request: + paths: + - 'src/**' + - '.github/workflows/vitest.yml' + types: + - opened + - synchronize + - reopened + - ready_for_review + workflow_dispatch: + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 'latest' + - run: npm ci + - run: npx vitest src/components diff --git a/README.md b/README.md index a725fb8b53..67655c3289 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,35 @@ Alternatively, if you'd rather create a classic-style token: GITHUB_API=$TOKENHASH ``` +## Using GitHub Codespaces + +A [GitHub Codespace](https://github.com/features/codespaces) can be used to test the site as well. To set up a Codespace, navigate to the branch you want to use as the base (e.g. `main`) and click the Code dropdown. + +![Codespaces screenshot](/source/images/assets/codespaces-setup.png) + +This will take you to a VSCode-like interface with a Terminal window. From here, export your GitHub API token you created in the previous step using the following command (replacing `$TOKENHASH` with your API token): + +```bash{promptUser: user} +export GITHUB_API=$TOKENHASH +``` + +Now you can run `npm ci` and `npm start` in the Terminal panel at the bottom of the page. The docs site will build inside the Codespaces container and install Node dependencies just like it would on your local machine. When the Node server is running, a dialog box will appear at the bottom right corner asking if you want to open the Codespace in a browser and if you want to make the Codespace public. + +![Codespaces open in browser](/source/images/assets/codespaces-application-available.png) + +Clicking on the link will take you to a live site that's running on the current branch of the repository. If you opted to make the Codespace public, you can share the link to others and they will be able to view the site after accepting a warning that they are visiting someone else's Codespace. If the Codespace was not made public, only your GitHub user will be able to see it. + +### Working with branches on Codespaces +You can open a Codespace (or load an existing Codespace) on a particular branch by first navigating to that branch in the GitHub repository. Alternately, if you already have the VSCode editor open, you can select a specific branch by clicking the branch name at the bottom left, then selecting the branch you would like to switch to in the panel that appears at the top of the screen. The Codespace will make the necessary adjustments and rebuild the docs site on that branch. + +![Codespaces branch](/source/images/assets/codespaces-branch.png) + +![Codespaces branch selection](/source/images/assets/codespaces-branch-list.png) + +### Notes on running in Codespaces + +Codespaces is free for individuals for [60 hours of runtime for 2 cores](https://github.com/features/codespaces#pricing), after which your _user_ is billed for additional time. It's unclear whether Pantheon's Enterprise account would own billing, but as of this writing it appears to be billed on a per user basis. For this reason, it's important to _not leave your Codespaces running_ when you're done with them. + ## Install With The Gatsby Cli From the `documentation` directory: @@ -112,8 +141,19 @@ You can view the local environment at `localhost:8000/`. Updates to docs are aut ## Testing -We include several tools to test that new content doesn't break the documentation. Most of these tests are performed automatically by our continuous integration service, but pull requests created from external contributors aren't included in CI tests. If you want to manually test your branch, you can execute the following tests within the Docker container. +To reduced the likelihood of regressions and bugs this site uses a few different testing tools: + +### Visual Regression Tests -### Merge Conflicts +Within the [`tests`](/tests/) directory there are a number of visual regression tests that can be run to compare the current state of the site to a PR preview or the live site. +These tests are meant to be run locally instead of CI as they have a high rate of false positives. + +### Unit Tests + +Unit tests for custom logic are written in in Vitest and can be executed with + +```bash +npx vitest src/components +``` -To check for merge conflict messages accidentally committed into the docs, run `merge_conflicts.sh` from `scripts`. +These tests are executed in CI via a [GitHub Action](.github/workflows/vitest.yml). diff --git a/gatsby-config.js b/gatsby-config.js index 748bb5bf10..90b074e3e6 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -267,11 +267,33 @@ module.exports = { serialize: ({ query: { site, allMdx } }) => { return allMdx.edges.map(edge => { const url = new URL(edge.node.fields.slug, site.siteMetadata.siteUrl).toString(); + // Simple hash function to turn a string into a numeric value + // https://chatgpt.com/share/69aeb001-e00f-41b9-98a4-816aa6a0330d + function hashCode(str) { + let hash = 0; + for (let i = 0; i < str.length; i++) { + const char = str.charCodeAt(i); + hash = (hash << 5) - hash + char; + hash |= 0; // Convert to 32bit integer + } + return Math.abs(hash); + } + + // Generate time based on title hash + function getSeededTime(title) { + const hash = hashCode(title); + + const hours = (hash % 24).toString().padStart(2, '0'); + const minutes = (hash % 60).toString().padStart(2, '0'); + const seconds = ((hash >> 8) % 60).toString().padStart(2, '0'); // Shift for more variance + + return `${hours}:${minutes}:${seconds}`; + } return { title: edge.node.frontmatter.title, description: edge.node.excerpt, - date: edge.node.frontmatter.published_date, + date: `${edge.node.frontmatter.published_date}T${getSeededTime(edge.node.frontmatter.title)}Z`, url: url, guid: edge.node.id, }; diff --git a/gatsby-node.js b/gatsby-node.js index a564157f5d..a3c1c3f49d 100644 --- a/gatsby-node.js +++ b/gatsby-node.js @@ -413,6 +413,24 @@ exports.createPages = ({ graphql, actions }) => { component: path.resolve("./src/templates/releaseNotesListing/index.js"), }) + // Create release notes pages for pagination. + const releaseNotesPostsPerPage = 8 + const releaseNotesNumPages = Math.ceil(result.data.allReleaseNotes.edges.length / releaseNotesPostsPerPage) + + Array.from({ length: releaseNotesNumPages }).forEach((_, i) => { + const path2 = `/release-notes/${i+1}/`; + createPage({ + path: path2, + component: path.resolve("./src/templates/releaseNotesListing/index.js"), + context: { + limit: releaseNotesPostsPerPage, + skip: i * releaseNotesPostsPerPage, + numPages: releaseNotesNumPages, + i, + }, + }) + }) + // terminusCommands.forEach(command => { // const slugRegExp = /:/g // const slug = command.name.replace(slugRegExp, "-") diff --git a/package-lock.json b/package-lock.json index d46b58e243..aeb716b3cf 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4508,19 +4508,29 @@ "@octokit/openapi-types": "^12.11.0" } }, + "node_modules/@pantheon-systems/pds-design-tokens": { + "version": "1.0.0-dev.134", + "resolved": "https://registry.npmjs.org/@pantheon-systems/pds-design-tokens/-/pds-design-tokens-1.0.0-dev.134.tgz", + "integrity": "sha512-3lnbRwnRTj2yZ/wpnpWAtcEDuXV9Be3mewM89xWIRoXNQ7srUyvFbj0NNNr/VegioT+Ftg1MMQWWfPJoGYbeuw==", + "license": "GPL-3.0-or-later" + }, "node_modules/@pantheon-systems/pds-toolkit-react": { - "version": "1.0.0-dev.130", - "resolved": "https://registry.npmjs.org/@pantheon-systems/pds-toolkit-react/-/pds-toolkit-react-1.0.0-dev.130.tgz", - "integrity": "sha512-9exrXbJEESEIqPUftIt4j0clT+9vPqcl7+rWNGcwJEH26AESNRr8+WCJ9h/S4cRxUrTX1PGbiLTN0p06LVOI3A==", + "version": "1.0.0-dev.138", + "resolved": "https://registry.npmjs.org/@pantheon-systems/pds-toolkit-react/-/pds-toolkit-react-1.0.0-dev.138.tgz", + "integrity": "sha512-dGRT5tapGBggyvdk0fV6xbpI5V5PsIXlP5NLC1yGPyoImKA7FK8H6InhLNkGD/YmR/nIDl7uBsFkEOBTK20UrA==", "dependencies": { "@floating-ui/react": "^0.24.3", - "@reactuses/core": "^5.0.14", + "@floating-ui/react-dom": "~1.3.0", + "@pantheon-systems/pds-design-tokens": "^1.0.0-dev.134", + "@reactuses/core": "^5.0.15", "focus-trap-react": "^10.2.1", "hash-sum": "^2.0.0", - "react-merge-refs": "^2.1.1", "react-router-dom": "^6.13.0", "react-toastify": "^9.0.3" }, + "engines": { + "node": ">=18.0.0 <=20.x" + }, "peerDependencies": { "react": "^16.0.0 || ^17.0.0 || ^18.0.0" } @@ -4539,6 +4549,18 @@ "react-dom": ">=16.8.0" } }, + "node_modules/@pantheon-systems/pds-toolkit-react/node_modules/@floating-ui/react-dom": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-1.3.0.tgz", + "integrity": "sha512-htwHm67Ji5E/pROEAr7f8IKFShuiCKHwUC/UY4vC3I5jiSvGFAYnSYiZO5MlGmads+QqvUkR9ANHEguGrDv72g==", + "dependencies": { + "@floating-ui/dom": "^1.2.1" + }, + "peerDependencies": { + "react": ">=16.8.0", + "react-dom": ">=16.8.0" + } + }, "node_modules/@pantheon-systems/pds-toolkit-react/node_modules/@floating-ui/react/node_modules/@floating-ui/react-dom": { "version": "2.0.8", "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.0.8.tgz", @@ -22952,15 +22974,6 @@ "url": "https://opencollective.com/unified" } }, - "node_modules/react-merge-refs": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/react-merge-refs/-/react-merge-refs-2.1.1.tgz", - "integrity": "sha512-jLQXJ/URln51zskhgppGJ2ub7b2WFKGq3cl3NYKtlHoTG+dN2q7EzWrn3hN3EgPsTMvpR9tpq5ijdp7YwFZkag==", - "funding": { - "type": "github", - "url": "https://github.com/sponsors/gregberge" - } - }, "node_modules/react-refresh": { "version": "0.14.0", "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.14.0.tgz", @@ -30766,16 +30779,22 @@ "@octokit/openapi-types": "^12.11.0" } }, + "@pantheon-systems/pds-design-tokens": { + "version": "1.0.0-dev.134", + "resolved": "https://registry.npmjs.org/@pantheon-systems/pds-design-tokens/-/pds-design-tokens-1.0.0-dev.134.tgz", + "integrity": "sha512-3lnbRwnRTj2yZ/wpnpWAtcEDuXV9Be3mewM89xWIRoXNQ7srUyvFbj0NNNr/VegioT+Ftg1MMQWWfPJoGYbeuw==" + }, "@pantheon-systems/pds-toolkit-react": { - "version": "1.0.0-dev.130", - "resolved": "https://registry.npmjs.org/@pantheon-systems/pds-toolkit-react/-/pds-toolkit-react-1.0.0-dev.130.tgz", - "integrity": "sha512-9exrXbJEESEIqPUftIt4j0clT+9vPqcl7+rWNGcwJEH26AESNRr8+WCJ9h/S4cRxUrTX1PGbiLTN0p06LVOI3A==", + "version": "1.0.0-dev.138", + "resolved": "https://registry.npmjs.org/@pantheon-systems/pds-toolkit-react/-/pds-toolkit-react-1.0.0-dev.138.tgz", + "integrity": "sha512-dGRT5tapGBggyvdk0fV6xbpI5V5PsIXlP5NLC1yGPyoImKA7FK8H6InhLNkGD/YmR/nIDl7uBsFkEOBTK20UrA==", "requires": { "@floating-ui/react": "^0.24.3", - "@reactuses/core": "^5.0.14", + "@floating-ui/react-dom": "~1.3.0", + "@pantheon-systems/pds-design-tokens": "^1.0.0-dev.134", + "@reactuses/core": "^5.0.15", "focus-trap-react": "^10.2.1", "hash-sum": "^2.0.0", - "react-merge-refs": "^2.1.1", "react-router-dom": "^6.13.0", "react-toastify": "^9.0.3" }, @@ -30800,6 +30819,14 @@ } } }, + "@floating-ui/react-dom": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-1.3.0.tgz", + "integrity": "sha512-htwHm67Ji5E/pROEAr7f8IKFShuiCKHwUC/UY4vC3I5jiSvGFAYnSYiZO5MlGmads+QqvUkR9ANHEguGrDv72g==", + "requires": { + "@floating-ui/dom": "^1.2.1" + } + }, "focus-trap-react": { "version": "10.2.3", "resolved": "https://registry.npmjs.org/focus-trap-react/-/focus-trap-react-10.2.3.tgz", @@ -44297,11 +44324,6 @@ } } }, - "react-merge-refs": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/react-merge-refs/-/react-merge-refs-2.1.1.tgz", - "integrity": "sha512-jLQXJ/URln51zskhgppGJ2ub7b2WFKGq3cl3NYKtlHoTG+dN2q7EzWrn3hN3EgPsTMvpR9tpq5ijdp7YwFZkag==" - }, "react-refresh": { "version": "0.14.0", "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.14.0.tgz", diff --git a/source/content/addons/object-cache/howto/wordpress.md b/source/content/addons/object-cache/howto/wordpress.md index 3f5db37bf0..82a68b46d9 100644 --- a/source/content/addons/object-cache/howto/wordpress.md +++ b/source/content/addons/object-cache/howto/wordpress.md @@ -3,7 +3,7 @@ title: Enable Object Cache Pro for WordPress description: How to install and configure Object Cache Pro for WordPress. permalink: docs/object-cache/wordpress tags: [cache, plugins, modules, database] -reviewed: "2023-08-17" +reviewed: "2024-08-08" contenttype: [doc] innav: [true] categories: [cache] @@ -11,7 +11,7 @@ cms: [wordpress] audience: [development] product: [--] integration: [--] -contributors: [jazzsequence] +contributors: [jazzsequence, jkudish] showtoc: true --- @@ -71,11 +71,11 @@ terminus redis:enable - If the workflow text in the dashboard turns red, it did not succeed. Please [create a ticket with support](/guides/support/contact-support/#ticket-support) to debug this further. + If the workflow text in the dashboard turns red, it did not succeed. Please [create a ticket with support](/guides/support/contact-support/#general-support-ticket) to debug this further. -1. Once complete, activate the Object Cache Pro plugin from the WordPress Admin or via WP-CLI through Terminus. +1. Once complete, activate the Object Cache Pro plugin from the WordPress Admin or via WP-CLI through Terminus on your development or multidev environment. NOTE: This workflow cannot be run on test or live environments. **WordPress Admin:** @@ -152,25 +152,13 @@ Refer to the [official Object Cache Pro documentation](https://objectcache.pro/d git add auth.json && git commit -m "Add Object Cache Pro auth token." ``` -1. Add the Object Cache Pro repository to your `composer.json` file's `repositories` section. Your final `repositories` section should look something like this: +1. Add the Object Cache Pro repository to your `composer.json` file's `repositories` section. ```json repositories: [ { "type": "composer", "url": "https://objectcache.pro/repo/" - }, - { - "type": "composer", - "url": "https://wpackagist.org", - "only": [ - "wpackagist-plugin/*", - "wpackagist-theme/*" - ] - }, - { - "type": "path", - "url": "upstream-configuration" } ], ``` @@ -315,6 +303,7 @@ Refer to the [official Object Cache Pro documentation](https://objectcache.pro/d 1. Merge code 1. Activate OCP 1. Flush Redis cache +- The `object-cache.php` drop-in file must be created in your development or multidev environment and committed or pushed to live to work. - When installed as a `mu-plugin` on a WordPress Multisite, Object Cache Pro handles each subsite separately. The dashboard widget applies to the current site and none of the other sites on the network. - Flushing the network cache from the network admin will flush all caches across the network. - Subsites do not get their own configuration or graphs. diff --git a/source/content/cache-control.md b/source/content/cache-control.md index 17b7fc301c..3e006008b6 100644 --- a/source/content/cache-control.md +++ b/source/content/cache-control.md @@ -118,14 +118,14 @@ $regex_json_path_patterns = array( foreach ($regex_json_path_patterns as $regex_json_path_pattern) { if (preg_match($regex_json_path_pattern, $_SERVER['REQUEST_URI'])) { // re-use the rest_post_dispatch filter in the Pantheon page cache plugin - add_filter( 'rest_post_dispatch', 'filter_rest_post_dispatch_send_cache_control', 12, 2 ); + add_filter( 'rest_post_dispatch', 'filter_rest_post_dispatch_send_cache_control', 12 ); break; } } // Re-define the send_header value with any custom Cache-Control header -function filter_rest_post_dispatch_send_cache_control( $response, $server ) { - $server->send_header( 'Cache-Control', 'no-cache, must-revalidate, max-age=0' ); +function filter_rest_post_dispatch_send_cache_control( $response ) { + $response->header( 'Cache-Control', 'no-cache, must-revalidate, max-age=0' ); return $response; } ``` @@ -138,7 +138,7 @@ As an alternative to using HTTP headers to control downstream caching, you can s -Pantheon does not support manually editing and updating the VCL on Global CDN. We use a standard VCL for all sites on the platform. Requests are accepted, but we do not guarantee change requests will be implemented. To submit a request for [Global CDN](/guides/global-cdn), open a [Support Ticket](/guides/support/contact-support/#ticket-support). +Pantheon does not support manually editing and updating the VCL on Global CDN. We use a standard VCL for all sites on the platform. Requests are accepted, but we do not guarantee change requests will be implemented. To submit a request for [Global CDN](/guides/global-cdn), open a [Support Ticket](/guides/support/contact-support/#general-support-ticket). Note some customizations to VCL are available via [Advanced Global CDN](/guides/professional-services/advanced-global-cdn). For more information, [Contact Sales](https://pantheon.io/contact-us). diff --git a/source/content/certification/exam.md b/source/content/certification/exam.md index 67d9b6c50e..65a753f8a8 100644 --- a/source/content/certification/exam.md +++ b/source/content/certification/exam.md @@ -293,21 +293,13 @@ The following directions and instructions were captured by a user on a MacOS dev ## Exam FAQs Here are some frequently asked questions about Pantheon's WebOps Certification Program. - - +### Where Can I Find Materials to Study for the Pantheon WebOps Certification Exam? In addition to [this guide within our documentation](/certification/study-guide) you can download a [PDF version that contains hands-on activities and review questions.](https://certification.pantheon.io/sites/default/files/2023-11/webopscert_final_v1_1.pdf). - - - - -You can find the directions for launching the exam here: [Exam Instructions](/certification/exam-instructions) - - - - - +### What are the directions for launching my exam? +You can find the directions for launching the exam here: [Exam Instructions](/certification/exam#exam-instructions) +### How do I use the ProctorFree virtual proctoring service for my exam? Pantheon’s Certification Program utilizes [ProctorFree](https://www.proctorfree.com/), a software-only identity verification and exam recording solution. The following document describes the requirements for successfully enabling ProctorFree when taking a Pantheon Certification exam. Before you get started, please note the following: @@ -340,13 +332,11 @@ If you are using a Linux machine, you will need to indicate this on the form whe Remote exam sessions must be completed on a laptop or desktop computer that meets the minimum technical requirements. - - - +### Do I need a camera? In order to take the exam with our automated proctoring service, you will need a working web camera to record your test taking session. Please reach out to us if you have any questions about this. - - + +### What are the technical requirements for taking a Pantheon Certification? In order to maintain compatibility with our online proctoring service, we require that exam takers use machines that adhere to the following minimum technical specifications: @@ -362,20 +352,20 @@ In order to maintain compatibility with our online proctoring service, we requir **Web Camera & Microphone:** An external or internal web camera and microphone are required. Camera and microphone drivers must have been updated or released within the last 5 years. 3D Webcams are not supported at this time. - - + +### How do I register for an exam? You can register for the [Pantheon WebOps Certification Exam with the form on this page](https://pantheon.io/certification). The form will ask for your name, email address, organization (if applicable), and some technical information about the computer you will be using to take the exam. This is to help us ensure that your computer is technically compatible with our exam engine and proctoring service. You will then choose a date to take the exam. - - + +### How do I get certificate and a badge? When you have finished taking the exam, you will see a message on the screen indicating whether you have passed or not. Once you have passed the exam, we will go through the process of validating the results. This validation can take up to 48 hours, at which point you will receive an email with a link to your badge and certification. We will also display your name, certification date, and a link to your badge and digital certificate on our [Certification Registry site](https://certification.pantheon.io/). - + ## More Resources diff --git a/source/content/certification/study-guide-cms/02-platform.md b/source/content/certification/study-guide-cms/02-platform.md index a5db42b524..0c5d2986db 100644 --- a/source/content/certification/study-guide-cms/02-platform.md +++ b/source/content/certification/study-guide-cms/02-platform.md @@ -142,7 +142,7 @@ Moving up to higher levels of value also requires effective collaboration betwee [Chapter 7](/certification/study-guide/chapter-7-people) shows how to connect with your team on Pantheon, and most critically, how to connect your DNS so that the public can find your site. It covers: * **Site Security Tab:** Allows users to** **lock down environments to only be accessible using a username/password, allowing for selective sharing of progress. -* **Expert Support: **Pantheon offers a range of Account options that include the features required for mission critical sites, such as 24x7x365 emergency on-call, debugging assistance, and concierge pre-launch load testing for Diamond Elite sites. +* **Expert Support: **Pantheon offers a range of Account options that include the features required for mission critical sites, such as 24x7x365 emergency support, debugging assistance, and concierge pre-launch load testing for Diamond Elite sites. * **Role-base access control:** Users can be automatically provisioned with adherence to** **the principle of least privilege. Within the workflow of a single site, any number of details can trip up a team on a regular basis or with the occasional disaster. [Chapter 6](/certification/study-guide/chapter-6-deployment) highlights the guardrails Pantheon puts around the workflow of a site as code moves through the deployment pipeline from Multidev environments to Dev to Test to Live. diff --git a/source/content/certification/study-guide-cms/09-automate.md b/source/content/certification/study-guide-cms/09-automate.md index e918fa702a..c6e2f71afd 100644 --- a/source/content/certification/study-guide-cms/09-automate.md +++ b/source/content/certification/study-guide-cms/09-automate.md @@ -79,7 +79,7 @@ Pantheon offers several paths to help you launch a Drupal site that leverages In * If you are using a deprecated Pantheon Drupal Upstream and would like to convert your site from one of the deprecated upstreams to the supported `drupal-composer-managed` upstream, you can use the [Terminus Conversion Tools Plugin](https://github.com/pantheon-systems/terminus-conversion-tools-plugin). ### WordPress with Integrated Composer -Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create an Integrated Composer WordPress site with Bedrock. This upstream is currently in EA. +Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create an Integrated Composer WordPress site with Bedrock. #### Adding and Removing Dependencies with Integrated Composer diff --git a/source/content/code-of-conduct.md b/source/content/code-of-conduct.md index e49db6e930..45f6d75fd7 100644 --- a/source/content/code-of-conduct.md +++ b/source/content/code-of-conduct.md @@ -2,7 +2,7 @@ title: Pantheon Community Code of Conduct description: Pantheon is dedicated to a positive and harassment-free community experience for everyone. contributors: [joshkoenig, rachelwhitton] -reviewed: "2016-09-27" +reviewed: "2024-08-22" tags: [collaborate] contenttype: [doc] innav: [true] @@ -50,7 +50,7 @@ You may contact any of our community Administrators to report a Code of Conduct |------|-------| | McKenna Regets (She/Her) | | | Steve Persch (He/Him) | | -| Steve Bresnick (He/Him) | | +| Chris Reynolds (He/Him) | | | Rachel Whitton (She/Her) | | ## Scope diff --git a/source/content/continuous-integration.md b/source/content/continuous-integration.md index e88d3aa00d..d094793c85 100644 --- a/source/content/continuous-integration.md +++ b/source/content/continuous-integration.md @@ -57,3 +57,6 @@ At this time, Pantheon does not provide or support: - [Build Tools](/guides/build-tools) - [Local Development](/guides/local-development) - [Pantheon Multidev](/guides/multidev) + +### Debug CI pipeline failures +If your continuous integration pipeline is suddenly failing across a large portfolio of sites due to permission denied errors for Git/SSH authentication, we recommend [debugging local DNS cache](/local-dns-cache) to solve. diff --git a/source/content/custom-certificates.md b/source/content/custom-certificates.md index 48f77295d8..9cf0c293c7 100644 --- a/source/content/custom-certificates.md +++ b/source/content/custom-certificates.md @@ -12,9 +12,9 @@ product: [cdn] integration: [--] --- -This article provides an overview of the steps to set up and work with manually managed, custom certificates through Pantheon's Global CDN and Advanced Global CDN, available through Pantheon's Custom Certificates concierge service. +This article provides an overview of the steps to set up and work with manually managed, custom certificates through Pantheon's Custom Certificates concierge service. -Custom Certificates service is available to contract customers, including Elite, Enterprise, Higher Education, and Resellers. To get started, contact your account manager or our [Sales Team](https://pantheon.io/contact-us?docs). +Custom Certificates service is available to contract customers only, but it does not require the Advanced Global CDN product or an Elite plan. There is a fee to utilize to utilize the service. To get started, contact your account manager or our [Sales Team](https://pantheon.io/contact-us?docs). ## Add a Custom Certificate diff --git a/source/content/dns-providers/cloudflare.md b/source/content/dns-providers/cloudflare.md index aae8486efc..c09440bb5a 100644 --- a/source/content/dns-providers/cloudflare.md +++ b/source/content/dns-providers/cloudflare.md @@ -110,6 +110,20 @@ You can configure Cloudflare's CDN as an additional layer on Pantheon's Global C ![Example DNS only](../../images/cloudflare-full.png) +#### Restrict Content Based on Geographic Location + +If you're using Cloudflare's IP Geolocation feature, you will need to read the `CF-IPCountry` header and set `Vary: CF-IPCountry` on all responses. + +#### Access to the /.well-known Path Is Needed + +If you're using Cloudflare's services to control or block traffic, an exception must be made for the `/.well-known` path in Cloudflare's config. If the `/.well-known` path is not accessible, Lets Encrypt may not be able to issue a certificate. + +#### Cache Invalidation Best Practices + +Cloudflare allows you to turn on caching. However, no cache invalidation hook is fired when you make content changes if you have Cloudflare caching turned on. This means that Cloudflare will be unaware of your changes and persist with stale cache. + +We recommend that you turn off Cloudflare caching until the `pantheon_advanced_page_cache` module/plugin is extended to send API calls to Cloudflare. + ## CAA Records (Optional) A **CAA Record** specifies which certificate authority (**CA**) can issue HTTPS certificates for a domain. @@ -140,16 +154,6 @@ A **CAA Record** specifies which certificate authority (**CA**) can issue HTTPS 1. Repeat this process for the `www` subdomain. -## Restrict Content Based on Geographic Location - -If you're using Cloudflare's IP Geolocation feature, you will need to read the `CF-IPCountry` header and set `Vary: CF-IPCountry` on all responses. - -## Cache Invalidation Best Practices - -Cloudflare allows you to turn on caching. However, no cache invalidation hook is fired when you make content changes if you have Cloudflare caching turned on. This means that Cloudflare will be unaware of your changes and persist with stale cache. - -We recommend that you turn off Cloudflare caching until the `pantheon_advanced_page_cache` module/plugin is extended to send API calls to Cloudflare. - ## Next Steps - [Launch Essentials: Domains & HTTPS](/guides/launch/domains) diff --git a/source/content/drupal-updates.md b/source/content/drupal-updates.md index 569f42e33d..c9a24cc700 100644 --- a/source/content/drupal-updates.md +++ b/source/content/drupal-updates.md @@ -53,7 +53,9 @@ The critical commands are: terminus drush my-drupal-8-site.dev -- migrate-upgrade --legacy-db-key=drupal_7 --configure-only --legacy-root=https://drupal7.example.com ``` -This command configures (but does not run) the migrations from Drupal 7 to Drupal 8. In this example, the Drupal 8 site is named `my-drupal-8-site` and the command is running on the `dev` environment. The `--legacy-db-key` parameter indicates how to get the login credentials to the source Drupal 7 database. In our example, we use the [Terminus secrets](https://github.com/pantheon-systems/terminus-secrets-plugin) plugin to supply the connection info. [See our blog post for more information on how this flag is used](https://pantheon.io/blog/running-drupal-8-data-migrations-pantheon-through-drush). The `--legacy-root` flag lets Drupal 8 know from where it can grab images and other uploaded media assets. +This command configures (but does not run) the migrations from Drupal 7 to Drupal 8. In this example, the Drupal 8 site is named `my-drupal-8-site` and the command is running on the `dev` environment. The `--legacy-db-key` parameter indicates how to get the login credentials to the source Drupal 7 database. + +In our example, we use the [Terminus secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin) plugin to supply the connection info. [See our blog post for more information on how this flag is used](https://pantheon.io/blog/running-drupal-8-data-migrations-pantheon-through-drush). The `--legacy-root` flag lets Drupal 8 know from where it can grab images and other uploaded media assets. The following command generates a report on how many items have been imported by each migration: diff --git a/source/content/guides/account-mgmt/billing/01-introduction.md b/source/content/guides/account-mgmt/billing/01-introduction.md index 413dbe58aa..086b55d1df 100644 --- a/source/content/guides/account-mgmt/billing/01-introduction.md +++ b/source/content/guides/account-mgmt/billing/01-introduction.md @@ -35,7 +35,7 @@ If you need to assume site and billing ownership, the current Site Owner must [t ## Tax Exempt Status Billing -To make it easy for our team to confirm your tax-exempt status and have it reflected on your bill quickly, [contact Support](/guides/support/contact-support/) and provide the following information in the [chat](/guides/support/contact-support/#real-time-chat-support) or [support ticket](/guides/support/contact-support/#ticket-support): +To make it easy for our team to confirm your tax-exempt status and have it reflected on your bill quickly, [contact Support](/guides/support/contact-support/) and provide the following information in the [chat](/guides/support/contact-support/#live-chat) or [support ticket](/guides/support/contact-support/#general-support-ticket): - An attached copy of the organization's [tax exemption determination letter](https://www.irs.gov/charities-non-profits/exempt-organizations-affirmation-letters) - Email address of Site Owner diff --git a/source/content/guides/account-mgmt/plans/07-site-plans.md b/source/content/guides/account-mgmt/plans/07-site-plans.md index fed4d1487a..2984a79df4 100644 --- a/source/content/guides/account-mgmt/plans/07-site-plans.md +++ b/source/content/guides/account-mgmt/plans/07-site-plans.md @@ -7,7 +7,7 @@ contributors: [wordsmither] showtoc: true permalink: docs/guides/account-mgmt/plans/site-plans editpath: docs/guides/account-mgmt/plans/07-site-plans.md -reviewed: "2022-09-19" +reviewed: "2024-08-07" contenttype: [guide] innav: [false] categories: [plans] @@ -93,23 +93,30 @@ Pantheon offers savings for sites purchased with annual billing. Refer to [Panth -1. [Go to the Site Dashboard](/guides/account-mgmt/workspace-sites-teams/sites#site-dashboard). +Please note that only Site owners can update plans. There are several places within the Pantheon Dashboard you can upgrade your site plan: -1. For Sandbox sites, click **Upgrade** next to the site's name. Otherwise, click the current plan tag next to the site's name. +1. [Go to the Site Dashboard](/guides/account-mgmt/workspace-sites-teams/sites#site-dashboard), and click **Upgrade** next to the site's name. +2. Within your personal workspace, navigate to Settings>Subscriptions. Click the 'Actions' dropdown and choose, **Change Site Plan** +3. If you are in a workspace, you can navigate to **Settings** > **Billing**. Scroll to see **Supported Sites** table. Within that table, if you are the site owner, you'll be able to click the **Site Plan** column to upgrade or downgrade your site. + + +From the site upgrade and downgrade page, complete the following steps: + +1. Click the **Select** button under the [plan you choose](https://pantheon.io/plans/pricing/). Select the billing frequency: [**Pay Annually**](/guides/account-mgmt/plans/pricing) or **Pay Monthly** at the top of the page. -1. Click **Select** for the plan you wish to purchase. + - If you've chosen a **Performance Plan**, choose the size and click **Choose Performance**. -1. Enter your billing information. Site ownership is designated to the user account entering billing information. + - If you've chosen a **Basic Plan**, click **Continue**. -1. Make sure the **Plan** details are correct. + - If you've chosen **Custom**, please fill out the contact field to be contacted by a customer support agent. -1. Verify the card shown in **Billing** details. +2. Click **+ Add New Card** and enter the credit card information, then click **Add Card** to save the card information. If you already have a card saved, it should be available in this section. -1. Click the **Submit** button. +3. Click **Continue** and review your information carefully, then click **Place Your Order** to confirm your purchase. -The Site Owner will receive an email confirmation of this change, a new invoice will be issued, and a prorated amount for the current billing cycle will be credited or charged to the associated card automatically. + - [Contact Support](/guides/support/contact-support) if you need any help. -Invoices and transaction history related to this change can be found in ** Account** > **Billing**. +As the site owner, you’ll receive an email confirming the change to the site. You’ll receive an updated invoice after the site billing is processed. ## Enable Add-ons diff --git a/source/content/guides/account-mgmt/traffic/03-overages.md b/source/content/guides/account-mgmt/traffic/03-overages.md index 5ee7eb52bb..3f6d6e1792 100644 --- a/source/content/guides/account-mgmt/traffic/03-overages.md +++ b/source/content/guides/account-mgmt/traffic/03-overages.md @@ -7,7 +7,7 @@ contributors: [wordsmither] showtoc: true permalink: docs/guides/account-mgmt/traffic/overages editpath: docs/guides/account-mgmt/traffic/03-overages.md -reviewed: "2024-03-28" +reviewed: "2024-08-15" contenttype: [guide] innav: [false] categories: [plans] @@ -17,6 +17,13 @@ product: [--] integration: [--] --- + + + +In response to your feedback, Pantheon has temporarily paused the automated overage program. See [related release note](/release-notes/2024/08/overage-charges-updates). + + + ## Traffic Limits Pantheon optimizes the resources and performance of your site based on your choice of [pricing plan](https://pantheon.io/plans/pricing?docs). Your pricing plan determines the [backend resources](/guides/account-mgmt/plans/faq#plan-resources) Pantheon deploys to support site performance and to serve the corresponding traffic levels for each plan. @@ -48,6 +55,13 @@ To access nonprofit preferred pricing, the organization will either need to 1) p All new Pantheon sites with a Performance or Elite annual plan will have a three-month grace period starting with your service start date (the day a site is first moved from a Sandbox to a commercial plan) where no overages will be incurred. New sites include any website that has not had a Pantheon subscription during the past 12 months. This allows you the time to get calibrated on the platform and focus on what is most important: the successful launch of your web site(s) on Pantheon! ### Overage Processing + + + +In response to your feedback, Pantheon has temporarily paused the automated overage program. See [related release note](/release-notes/2024/08/overage-charges-updates). + + + Overages will be processed on a monthly basis. All customers subject to overages will be notified immediately. For customers paying monthly by credit card- you can expect to receive an invoice for any site in overage right away. For customers on an annual contract, overages will be invoiced quarterly (processing in March, June, September and December). This is intended to ease the administrative burden that comes with the potential for monthly invoices. For those contract customers on quarterly invoicing- you will still receive monthly notifications on any overages found for the month so as to keep you informed ahead of final processing and invoicing avoiding any surprises. diff --git a/source/content/guides/agcdn/04-submit-request.md b/source/content/guides/agcdn/04-submit-request.md index 36bb08849f..0b218a7839 100644 --- a/source/content/guides/agcdn/04-submit-request.md +++ b/source/content/guides/agcdn/04-submit-request.md @@ -28,7 +28,7 @@ Follow the steps below to submit a ticket for a configuration change or support 1. Review [Support Ticket Best Practices](/guides/support/support-ticket/#best-practices). -1. Complete the steps in [Ticket Support](/guides/support/contact-support/#ticket-support). +1. Complete the steps in [Ticket Support](/guides/support/contact-support/#general-support-ticket). ![Screenshot of the Support Tab](../../../images/dashboard/support-tab.png) diff --git a/source/content/guides/decoupled/overview/07-support.md b/source/content/guides/decoupled/overview/07-support.md index 2b748b4eb3..005991fb67 100644 --- a/source/content/guides/decoupled/overview/07-support.md +++ b/source/content/guides/decoupled/overview/07-support.md @@ -7,7 +7,7 @@ contributors: [joan-ing] layout: guide showtoc: true permalink: docs/guides/decoupled/overview/support -reviewed: "2023-03-23" +reviewed: "2024-09-10" contenttype: [guide] innav: [false] categories: [create] @@ -27,8 +27,7 @@ Technical Support covers issues related to the following: - Troubleshoot customer cases related to the platform - Enable customers by providing related documentation, where to access logs, and when appropriate share similar case studies that provide a solution for the customer in line with the product life cycle. - Advocate for customers by validating and reporting bugs, feature requests, and improving platform documentation in line with the product life cycle -- During customer outages that cannot be resolved by the customers or CSE, escalate to on-call engineers - +- For business-critical incidents or outages that cannot be resolved by the customers or Pantheon support, escalate the issue to our support engineers by opening a general support ticket or an emergency ticket. Emergency tickets are only available to **Diamond** and **Platinum** customers. Technical Support for Pantheon Front-End Sites does not include the following: diff --git a/source/content/guides/disaster-recovery/01-introduction.md b/source/content/guides/disaster-recovery/01-introduction.md index ddc41f00b9..36fda0e7b3 100644 --- a/source/content/guides/disaster-recovery/01-introduction.md +++ b/source/content/guides/disaster-recovery/01-introduction.md @@ -4,7 +4,7 @@ subtitle: Introduction description: Address emergency downtime situations on the Pantheon platform tags: [webops] contributors: [joshlieb, joan-ing] -reviewed: "2024-07-30" +reviewed: "2024-09-10" type: guide permalink: docs/guides/disaster-recovery editpath: disaster-recovery/01-introduction.md @@ -17,6 +17,6 @@ product: [--] integration: [--] --- -This guide is focused on the immediate actions a Pantheon customer should take in the event of a catastrophic site failure. In all cases, the first step should be to file an emergency downtime on-call ticket, regular ticket, or open a support chat depending on support tier. Filing an emergency Pantheon On-Call ticket will immediately escalate the incident and ensure the fastest and most effective service. +This guide is focused on the immediate actions a Pantheon customer should take in the event of a catastrophic site failure. In all cases, the first step should be to file an emergency ticket, a general support ticket, or start a live chat depending on your [account tier](/guides/support/#support-features-and-response-times). Filing an emergency ticket will immediately escalate the incident to our support engineers, and ensure the fastest and most effective service. -This guide does not cover all potential post-disaster recovery processes. Such processes will depend on the nature of the incident and the impact that it has on your site. You must engage with Pantheon support during the incident, and the support team will help determine what remediation steps are required. +This guide does not cover all potential post-disaster recovery processes, as these will depend on the nature of the incident and its impact on your site. It's essential to engage with Pantheon Support during the incident; our team will help determine the necessary remediation steps. diff --git a/source/content/guides/disaster-recovery/03-site-goes-down.md b/source/content/guides/disaster-recovery/03-site-goes-down.md index 6a4e034f82..b563445504 100644 --- a/source/content/guides/disaster-recovery/03-site-goes-down.md +++ b/source/content/guides/disaster-recovery/03-site-goes-down.md @@ -4,7 +4,7 @@ subtitle: What to Do If Your Site Goes Down description: Working with Pantheon support during emergencies tags: [webops] contributors: [joshlieb, joan-ing] -reviewed: "2024-07-30" +reviewed: "2024-09-10" type: guide permalink: docs/guides/disaster-recovery/site-goes-down editpath: disaster-recovery/03-site-goes-down.md @@ -19,15 +19,23 @@ integration: [--] ## Open a Support Ticket -In cases of downtime or significant functional failure in the Live environment, the first step is to open a support ticket. Even if you escalate the incident to your dedicated Customer Success Manager (included for all Enterprise contract customers), our support engineers will be the ones diagnosing the cause of downtime and working to get your site back up, and a ticket is the fastest way to get them up to speed and engaged. +In cases of downtime or significant functional failure in the live environment, the first step is to open a support ticket. Even if you escalate the incident to your dedicated Customer Success Manager (available to all Enterprise contract customers), our support engineers will be the ones diagnosing the cause of the downtime and working to restore your site. Opening a ticket is the fastest way to get them up to speed and engaged. -Diamond and Platinum Account customers can report and escalate site downtime by clicking **Trigger Pantheon On-Call** from the Support tab. In cases where the dashboard is inaccessible, a ticket can be filed using a telephone ticketing service, accessible at **1(866)415-7624**. Note that this is strictly for filing a ticket, and you will not reach a support engineer by using this method. -All other account types should click **Open Ticket** to open a support interaction to report site downtime. +From the Support tab in the workspace of the affected site: -![Show platinum support features in the site dashboard](../../../images/dashboard/new-dashboard/platinum-support-site-dashboard.png) +* **Diamond** and **Platinum** customers can open an **emergency ticket** to report and escalate business-critical site downtime. + * In cases where the dashboard is inaccessible, a support ticket can be filed using a telephone ticketing service, accessible at 1(866)415-7624. Note that this is strictly for filing a ticket, and you will not reach our support engineers by using this method. +* **Gold** customers can open a **general support ticket** to report site downtime. +* **Silver** customers can start a **live chat** to report site downtime. -Please include as much information as possible. A support engineer will work with you to diagnose the cause, and any information that you can provide will shorten the investigation time. +![Show diamond support features in the workspace dashboard](../../../images/dashboard/new-dashboard/diamond-support-workspace-dashboard.png) + +Please provide as much detail as possible. Our support engineers will work with you to diagnose the cause of the issue, and any information you provide will help shorten the investigation time. + +To learn more about the support features for different account tiers, see also the following: +* [Scope of Support](/guides/support/#support-features-and-response-times) +* [Contact Support](/guides/support/contact-support/) ## Check for Ongoing Platform Incidents @@ -39,23 +47,23 @@ Because incidents are declared when a platform issue meets a minimal downtime or ## Incident Escalation -Although filing an emergency on-call ticket will escalate your downtime incident within the support team and ensure you receive the fastest response, you may also want to alert your broader Pantheon account team. Depending on the situation, your escalation path may differ. +Filing an emergency ticket will escalate your downtime incident within the Support team and ensure you receive the fastest response. However, you may also want to alert your broader Pantheon account team. Depending on the situation, your escalation path may vary. ### Support Channels -* **Ticketing**: If your site is suffering downtime on the Live environment, your first step should be to open a support ticket. Chat normally has a quicker response time, but emergency on-call tickets are absolutely escalated and response times to these tickets should be comparable. +* **Ticket**: In cases of downtime or significant functional failure in the live environment, the first step is to open a support ticket. While live chat generally offers a quicker response time, emergency tickets (for **Diamond** and **Platinum** customers) are escalated and should have comparable response times. * **Slack**: Diamond tier accounts can have access to a dedicated Slack channel in which customers can interact directly with their CSM, AM, and primary support resources. This is primarily intended as a means for quick communication and collaboration, and should not be used in lieu of the ticketing system, as there are no SLOs associated with Slack channels. -* **Phone/teleconference**: A phone call or teleconference can be requested for emergency support. This can be done either when filing the emergency ticket, or in the ticket thread once open. +* **Phone/Teleconference**: You can request a phone call or teleconference for emergency support. This can be done either when filing the emergency ticket or within the ticket thread once it is open. - Tickets and chat have tier-specific response time objectives, while email, phone, and Slack channels do not. Refer to the [Support Features and Response Times](/guides/support/#support-features-and-response-times) table for details. + Tickets and live chat have account tier-specific response times, whereas email, phone, and Slack channels do not. Learn more about [support features for different account tiers](/guides/support/#support-features-and-response-times). -* **Diamond and Platinum Account customers** can call Pantheon's premium technical support line directly for any technical issues, escalations, site, billing, or overages queries. The phone number can be found in your Workspace, in the Support tab. Note that this is strictly for filing a ticket, and you will not reach a support engineer by using this method. +* **Premium Support Hotline**: Diamond and Platinum customers can call the 24/7 Premium Support Hotline for any technical issues, escalations, site, billing, or overages queries. You can find the phone number in the Support tab of your workspace. ### Escalation Paths @@ -89,4 +97,4 @@ Key tools that you can use for ongoing diagnosis of issues include: * AGCDN logs can be piped directly into customer-managed log management applications. Setup by Professional Services is required. -The Customer Success Engineering team will work with you through the existing emergency ticket. If additional issues are uncovered you may want to open a new ticket to allow for a cleaner set of interactions, especially if additional Pantheon resources are brought in for review and assistance. +Support engineers will work with you through the existing emergency ticket. If additional issues are uncovered you may want to open a new ticket to allow for a cleaner set of interactions, especially if additional Pantheon resources are brought in for review and assistance. diff --git a/source/content/guides/disaster-recovery/04-incident-remediation.md b/source/content/guides/disaster-recovery/04-incident-remediation.md index 8ebb5cb730..ca8e967ee7 100644 --- a/source/content/guides/disaster-recovery/04-incident-remediation.md +++ b/source/content/guides/disaster-recovery/04-incident-remediation.md @@ -23,11 +23,11 @@ Bringing a site back from downtime and remediating the cause of downtime to ensu The WAF and Advanced GCDN layers are primarily managed by Pantheon’s Professional Services team, with some updates and support tasks performed by the Customer Success Engineering team, which also performs intake on the initial request. This ensures that responses can meet the contracted SLO, and Pantheon aims to escalate/reassign to Professional Services on an as needed basis. -In the event of an attack, exploit, or other issue related to the global edge, file a ticket via the normal support channels, with an on-call emergency ticket filed in cases where downtime or serious service degradation occurs, and notify the Pantheon account team via Slack. +In the event of an attack, exploit, or other issue related to the global edge, file a ticket via the normal support channels, with an emergency ticket filed in cases where downtime or serious service degradation occurs, and notify the Pantheon account team via Slack. ## Edge Failover -Recovery of a site may take minutes, but time to recovery can be uncertain. Additional features have been implemented at the Global CDN level to provide a more immediate solution. These features minimize downtime while the specific issues are remediated. +Recovery of a site may take minutes, but time to recovery can be uncertain. Additional features can be implemented at the CDN layer to provide a more immediate solution. These features minimize downtime while the specific issues are remediated. ### Experience Protection @@ -35,7 +35,7 @@ The Global CDN natively provides a layer of protection via the full-page cache. ### Synthetic Responses -A set of static pages can be hosted directly and when certain failure conditions are detected, traffic can be redirected to a placeholder. The placeholder will provide a minimally acceptable user experience rather than error messages and a completely unreachable site. +A set of static pages can be hosted directly and when certain failure conditions are detected, traffic can be redirected to a placeholder. The placeholder will provide a minimally acceptable user experience rather than error messages and a completely unreachable site. These custom rules require an [Advanced Global CDN](/guides/agcdn) subscription. ## Infrastructure Failover In cases where the Google Cloud Platform infrastructure becomes compromised, Pantheon support can trigger a Multizone failover to redirect traffic at the load-balancing layer to a backup cluster of application servers on an alternate zone. For more information, refer to the [Multizone Failover](/multizone-failover) documentation. diff --git a/source/content/guides/domains/05-custom-domains.md b/source/content/guides/domains/05-custom-domains.md index ae407f44ff..9c6c5e32c9 100644 --- a/source/content/guides/domains/05-custom-domains.md +++ b/source/content/guides/domains/05-custom-domains.md @@ -57,7 +57,7 @@ Note that each custom domain is counted regardless of the environment to which i - Professional workspaces that have wildcard domain(s) pointed at Pantheon may have a valid use case for opt-ing out of domain verification (e.g., WordPress Multisite with many subdomains). For details, [see this FAQ below](#can-i-opt-out-of-domain-verification). + Sites associated with Diamond or Platinum workspaces have the option to skip this step. For details, [see this FAQ below](#can-i-opt-out-of-domain-verification). @@ -84,14 +84,14 @@ Note that each custom domain is counted regardless of the environment to which i - Note that if the Platform detects a CNAME record, the **Status** will show `Remove this detected record` on the line with the CNAME. Remove the CNAME from the DNS management service to avoid potential issues or interruptions. ## FAQ -### I have existing custom domains which were previously connected and launched prior to the enforcement of Domain Verification, will those be impacted? +### I have existing custom domains which were previously connected and launched prior to the enforcement of domain verification, will those be impacted? No. Any custom domains previously added or launched will not require explicit domain verification. However, if any of those domains are deleted by the customer and then re-added, the process of re-addition (whether to the same environment or any other environment) will trigger domain verification. ### Is pre-provisioning HTTPS now a requirement to connect a custom domain? Yes. Skipping HTTPS provisioning is no longer an option. -### Is Wild Card DNS routing supported by Domain Verification? +### Is Wild Card DNS routing supported by domain verification? Pantheon does not allow wild card domains to be directly added as a custom domain. Customers may point wildcard domains (eg: *.example.com) in their own DNS to Pantheon, but are still required to have specific domains (eg: mysite.example.com) added and connected to specific environments on Pantheon. ### How can I know which domains are still pending ownership verification ? @@ -99,10 +99,11 @@ For any domain that has been added that is pending verification, clicking on the You can get a high-level status view for all custom domains connected to a given environment via Terminus using the [`https:info` command](/terminus/commands/https-info). Domains that are pending verification will have the "Verification Pending" status returned as part of the Terminus `https:info` command. -### Can I opt-out of Domain Verification? -Yes, a professional workspace can opt-out from domain verifications across all sites in their organization but only by request. Please [contact support](/guides/support/contact-support/) to request exemption from domain verification, and once granted - you will see an option to skip domain verification when connecting domains to sites in your workspace. +### Can I opt out of domain verification? +Sites associated with Diamond and Platinum workspaces are automatically exempt from domain verification enforcement. All other account tiers can request an exemption for a professional workspace by [contacting support](/guides/support/contact-support/). + +Exemption enables the option to skip domain verification when connecting custom domains in the site dashboard, and is only available at the workspace level. For example, you cannot request exemption for just one site in your workspace, or an individual custom domain such as `example.com`. -Exemption is only available at the workspace level. For example, you cannot request exemption for just one site in your workspace, or an individual custom domain such as `example.com`. ## More Resources diff --git a/source/content/guides/environment-configuration/02-read-environment-config.md b/source/content/guides/environment-configuration/02-read-environment-config.md index 1a481dfed0..690505fd7e 100644 --- a/source/content/guides/environment-configuration/02-read-environment-config.md +++ b/source/content/guides/environment-configuration/02-read-environment-config.md @@ -166,124 +166,17 @@ array(63) { ## Setting Environment Variables -It is not possible to set environment variables on Pantheon. However, there are three common solutions you can use instead. +You can use the [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin) to write the secrets to Pantheon's secure storage system. The secrets are encrypted at rest and follow all standard practices for the storing of sensitive values. -### Terminus Secrets Plugin +Learn more about this new feature by exploring our new Pantheon Secrets Guide: + * [Introduction](/guides/secrets) + * [Secrets Overview](/guides/secrets/overview) + * [PHP Usage](/guides/secrets/php) + * [Drupal Key Usage](/guides/secrets/drupal) + * [Integrated Composer Usage](/guides/secrets/composer) + * [Local Development Usage](/guides/secrets/local) + * [Troubleshooting](/guides/secrets/troubleshooting) -You can use the [Terminus Secrets Plugin](https://github.com/pantheon-systems/terminus-secrets-plugin) to write the secrets to a JSON file in the private file system. Your PHP will look similar to the code example below. This example will help you get started, however, you must modify the third line for the key you want to configure. You can also modify the `secrets.json` file name, although we recommend you provide the file with a name you will recognize for secrets management. - - - - - -1. Modify and use the code example below to write secrets. - -```bash -$secrets_json_text = file_get_contents('/files/private/secrets.json'); -$secrets_data = json_decode($secrets_json_text, TRUE); -define('EXAMPLE_API_KEY', $secrets_data['example_api_key']); -``` - - - - - -1. Modify and use the code example below to write secrets. - -```bash -$secrets_json_text = file_get_contents('/files/private/secrets.json'); -$secrets_data = json_decode($secrets_json_text, TRUE); -$config['example_integration.settings']['apikey'] = $secrets_data['example_api_key']; -``` - - - - - -### Manual File Creation - -You can manually create and add files to the `/files/private` directory for scenarios that are not supported by the Terminus Secrets plugin. For example, when secrets in the Dev and Live environments are different. - -1. Create your files manually in the `/files/private` directory for each case required, for example: - - - `/files/private/dev.secrets.json` - - `/files/private/test.secrets.json` - - `/files/private/live.secrets.json` - -1. Update your PHP file using the code examples below as a reference. - - - Note that the code below uses SendGrid as an example. You will need to modify the code for the specific key you are configuring. - - - - - -1. Add the code to your `wp-config.php` file and modify it as necessary for the specific key you are configuring: - -```php -if ( ! empty( $_ENV['PANTHEON_ENVIRONMENT'] ) ) { - switch( $_ENV['PANTHEON_ENVIRONMENT'] ) { - case 'live': - // keys for production env - $secrets_filename = 'live.secrets.json'; - break; - case 'test': - // keys for staging env - $secrets_filename = 'test.secrets.json'; - break; - default: - // keys for dev and multidev envs - $secrets_filename = 'dev.secrets.json'; - break; - } - if (isset($secrets_filename)) { - $secrets_json_text = file_get_contents('/files/private/' . $secrets_filename); - $secrets_data = json_decode($secrets_json_text, TRUE); - - define('SENDGRID_API_KEY', $secrets_data['sendgrid_api_key']); - define('SOME_OTHER_OPTION', $secrets_data['other_key_example']); -} -``` - - - - - -1. Add the code below to your `settings.php` file and modify it as necessary for the specific key you are configuring: - -```php - if ( ! empty( $_ENV['PANTHEON_ENVIRONMENT'] ) ) { - switch( $_ENV['PANTHEON_ENVIRONMENT'] ) { - case 'live': - // keys for production env - $secrets_filename = 'live.secrets.json'; - break; - case 'test': - // keys for staging env - $secrets_filename = 'test.secrets.json'; - break; - default: - // keys for dev and multidev envs - $secrets_filename = 'dev.secrets.json'; - break; - } - if (isset($secrets_filename)) { - $secrets_json_text = file_get_contents('/files/private/' . $secrets_filename); - $secrets_data = json_decode($secrets_json_text, TRUE); - - $config['sendgrid_integration.settings']['apikey'] = $secrets_data['sendgrid_api_key']; - $config['some_other_config_override']['value'] = $secrets_data['other_key_example']; - } - ``` -``` - - - - - -### Lockr - -You can use [Lockr](/guides/lockr) for maximum site security. Lockr provides a simple-to-use developer interface with a scalable cloud key management system. Review the [Install Lockr via the Lockr Terminus Plugin](/guides/lockr#install-lockr-via-the-lockr-terminus-plugin) guide section for installation steps. ## More Resources diff --git a/source/content/guides/errors-and-server-responses/02-4xx-errors.md b/source/content/guides/errors-and-server-responses/02-4xx-errors.md index d7fdd8d5bb..895ef43a18 100644 --- a/source/content/guides/errors-and-server-responses/02-4xx-errors.md +++ b/source/content/guides/errors-and-server-responses/02-4xx-errors.md @@ -47,6 +47,10 @@ This error or a similar error message displays when a web browser cannot find th More specifically, this error occurs when the client (via web browser) successfully connects to the host (website’s application server), but is unable to find the actual resource requested (for example, a specific URL or file name). We recommend confirming that the URL or file name is correct and still exists on the site. +### Error 414 URI Too Long + +This message is shown if the size of the requested URI exceeds the 8KB limit. + ## More Resources - [Unlock a Site's Environment](/security#unlock-a-sites-environment) diff --git a/source/content/guides/errors-and-server-responses/03-5xx-errors.md b/source/content/guides/errors-and-server-responses/03-5xx-errors.md index bffdd3bc5e..c9a9db054a 100644 --- a/source/content/guides/errors-and-server-responses/03-5xx-errors.md +++ b/source/content/guides/errors-and-server-responses/03-5xx-errors.md @@ -21,9 +21,9 @@ This section provides information on how to interpret 5xx errors. > Upstream sent too big header while reading response header from upstream. -This error occurs when the payload or size of the request sent is greater than the `fastcgi_buffer_size`. Check to see if you are making heavy requests with a number of assets or data being passed if this happens again. +This error occurs when the payload or size of the request sent is greater than the `fastcgi_buffer_size`. Check to see if you are making heavy requests with a number of assets or data being passed if this happens again. -Remove additional images to reduce the size of the payload sent to the buffer for nginx to process. This will allow you to post the request. +Remove additional images to reduce the size of the payload sent to the buffer for nginx to process. This will allow you to post the request. ### 502 Timeout/Segfault Error @@ -33,7 +33,7 @@ Complete the steps below to resolve this: 1. Disable Basic Auth and send the request again to see if it works. -1. Re-enable Basic Auth. +1. Re-enable Basic Auth. However, if it is possible to ensure your headers are always passed for JS files, that is the best solution. @@ -79,14 +79,14 @@ This can be a misleading message if you're using AJAX when HTTP Basic Auth is e ### Pantheon 504 Target Not Responding -> The web page you were looking for could not be delivered. +> The web page you were looking for could not be delivered. A common cause for this error is an [idle container](/application-containers#idle-containers) that has spun down due to inactivity. Wake the environment by loading the home page in your browser or using the [`terminus env:wake` command](/terminus/commands/env-wake). > No php workers are available to handle the request. -This occurs when PHP processing resources for your site are exhausted. Each application container has a fixed limit of requests it can concurrently process. When this limit is reached, nginx will queue up to 100 requests in the hope that PHP workers will free up to serve these requests. - +This occurs when PHP processing resources for your site are exhausted. Each application container has a fixed limit of requests it can concurrently process. When this limit is reached, nginx will queue up to 100 requests in the hope that PHP workers will free up to serve these requests. + When the nginx queue fills up, the application container cannot accept any more requests. We could increase the nginx queue above 100, but it would only mask the problem. At some point, it's better to turn away requests and serve those already in line. Refer to [Overloaded Workers](/guides/errors-and-server-responses/overloaded-workers) for more information. This error can be caused by sustained spikes in traffic (often caused by search engine crawlers) and by having PHP processes that run too slowly or have long waiting times for external resources which occupy the application container for long periods. Consider [upgrading your site plan](/guides/legacy-dashboard/site-plan) if you have too much traffic for your site's resources. @@ -105,11 +105,13 @@ Typically the request timeout is much shorter than the hard timeout for PHP. Whi This is **not** a web application (WordPress or Drupal) maintenance mode error. This is a manually toggled emergency message reserved for unusual circumstances when a site is known to be unavailable. -### Error 561 No site Detected +### Error 561: No Site Detected + +> No site detected. Make sure your code is pulled into this environment. -> No site detected. Make sure your code is pulled into this environment. +This error typically occurs when a site has been created, but no CMS has been installed. Additionally, this error can appear instead of a `403 Directory listing denied` error if no index file is present. -This error typically occurs when a site has been created, but no CMS has been installed. You will also see this error instead of a `403 Directory listing denied` error, if you have no index file. +You will see this error if there is no `index.php` file in the expected location. Ensure that the `index.php` file is in the root of your repository or correctly placed in the `web` directory if you're using a `web_docroot=true` setup, which is the default for Integrated Composer sites. See [Serving Sites from the Web Subdirectory](/nested-docroot) for more details. ## More Resources diff --git a/source/content/guides/getstarted/06-addsite.md b/source/content/guides/getstarted/06-addsite.md index 51862ce84b..ac0d595706 100644 --- a/source/content/guides/getstarted/06-addsite.md +++ b/source/content/guides/getstarted/06-addsite.md @@ -33,7 +33,7 @@ To create a CMS site: If you select Drupal, you will have the option to select the Drupal version you want to use. - ![Select Drupal version](../../../images/create-new-site-cms-drupal.png) + ![Select Drupal version](../../../images/create-new-site-cms-drupal-11crop.png) 1. Enter the name and select a region for this site. If this site is to be part of a Professional Workspace, select a Workspace from **Choose a Workspace for the Site**. Click **Continue**. It can take several minutes to create a new site on Pantheon. diff --git a/source/content/guides/git/08-troubleshooting.md b/source/content/guides/git/08-troubleshooting.md index c6a727fbd9..9e75ef6f56 100644 --- a/source/content/guides/git/08-troubleshooting.md +++ b/source/content/guides/git/08-troubleshooting.md @@ -62,7 +62,7 @@ However, some Git GUI clients, including SourceTree, also support the use of 1. Paste the URL into the **Source URL** field. - 1. Remove `git clone` from the beginning of the URL. + 1. Remove `git clone` from the beginning of the URL. 1. Remove the trailing space and `my-site` name from the end of the URL provided in the **Connection Info** section of your Pantheon Dashboard. @@ -91,6 +91,9 @@ fatal: Could not read from remote repository. To clear this up, you may need to work with your network administrators to unblock this port. If this isn't an option, you may need to try a [Port 2222 Blocked Workaround](/guides/sftp/port-2222). +### Debug CI pipeline failures +If your continuous integration pipeline is suddenly failing across a large portfolio of sites due to permission denied errors for Git/SSH authentication, we recommend [debugging local DNS cache](/local-dns-cache) to solve. + ## More Resources We recommend the following resources for further learning: diff --git a/source/content/guides/integrated-composer/01-introduction.md b/source/content/guides/integrated-composer/01-introduction.md index 8ebd54c791..7712495336 100644 --- a/source/content/guides/integrated-composer/01-introduction.md +++ b/source/content/guides/integrated-composer/01-introduction.md @@ -44,7 +44,7 @@ You can use the [Terminus Conversion Tools Plugin](https://github.com/pantheon-s -Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create an Integrated Composer WordPress site with **Bedrock**. This upstream is currently in EA. +Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create an Integrated Composer WordPress site with **Bedrock**. diff --git a/source/content/guides/launch/03-plans.md b/source/content/guides/launch/03-plans.md index 3eab9718b4..7d3e69973d 100644 --- a/source/content/guides/launch/03-plans.md +++ b/source/content/guides/launch/03-plans.md @@ -12,6 +12,7 @@ cms: [wordpress, drupal] audience: [agency, business] product: [--] integration: [--] +reviewed: "2024-08-07" --- This section provides information on how to upgrade from a free account to a paid plan by adding billing information or inviting a business owner to pay. @@ -20,21 +21,24 @@ Contract customers must contact their account manager when they're ready to upgr ## Use Your Own Card -Add your payment method to upgrade and pay for the site now: +There are several places within the Pantheon Dashboard you can upgrade your site plan: -1. [Go to the Site Dashboard](/guides/account-mgmt/workspace-sites-teams/sites#site-dashboard), and click **Upgrade** next to the site's name. +1. [Go to the Site Dashboard](/guides/account-mgmt/workspace-sites-teams/sites#site-dashboard), and click **Upgrade** next to the site's name. +2. Within your personal workspace, navigate to Settings>Subscriptions. Click the 'Actions' dropdown and choose, **Change Site Plan** +3. If you are in a workspace, you can navigate to Settings>Billing. Scroll to see **Supported Sites** table. Within that table, if you are the site owner, you'll be able to click the **Site Plan** column to upgrade or downgrade your site. -1. Click the **Select** button under the [plan you choose](https://pantheon.io/plans/pricing/). +From the site upgrade and downgrade page, complete the following steps: -1. Continue to the **Choose Billing** step, and then select the billing frequency: [**Pay Annually**](/guides/account-mgmt/plans/pricing) or **Pay Monthly**. - - - If you've chosen a **Performance Plan**, choose the size and click **Continue**. +1. Click the **Select** button under the [plan you choose](https://pantheon.io/plans/pricing/). Select the billing frequency: [**Pay Annually**](/guides/account-mgmt/plans/pricing) or **Pay Monthly** at the top of the page. + - If you've chosen a **Performance Plan**, choose the size and click **Choose Performance**. - If you've chosen a **Basic Plan**, click **Continue**. -1. Click **+ Add New Card** and enter the credit card information, then click **Add Card** to save the card information. + - If you've chosen **Custom**, please fill out the contact field to be contacted by a customer support agent. + +2. Click **+ Add New Card** and enter the credit card information, then click **Add Card** to save the card information. If you already have a card saved, it should be available in this section. -1. Click **Continue** and review your information carefully, then click **Place Your Order** to confirm your purchase. +3. Click **Continue** and review your information carefully, then click **Place Your Order** to confirm your purchase. - [Contact Support](/guides/support/contact-support) if you need any help. diff --git a/source/content/guides/launch/04-domains.md b/source/content/guides/launch/04-domains.md index f9314125e7..ae75646b2d 100644 --- a/source/content/guides/launch/04-domains.md +++ b/source/content/guides/launch/04-domains.md @@ -38,7 +38,7 @@ The steps below will guide you through the process of migrating a site onto Pant - If you have a wildcard domain pointed at Pantheon and you have a valid use case to skip this verification for your sub-domains (although it is recommended to prevent domain takeovers), you may request an exemption to skip the verification by contacting Pantheon Support via chat or [ticket](/guides/support/support-ticket/). + Sites associated with Diamond or Platinum workspaces have the option to skip this step. For details, [see this related FAQ](/guides/domains/custom-domains#can-i-opt-out-of-domain-verification). diff --git a/source/content/guides/php/02-php-versions.md b/source/content/guides/php/02-php-versions.md index 17c15ddffc..c59f6746f4 100644 --- a/source/content/guides/php/02-php-versions.md +++ b/source/content/guides/php/02-php-versions.md @@ -74,7 +74,7 @@ You can use SFTP or Git mode to create or change the `pantheon.yml` file. Follow ```yaml:title=pantheon.yml api_version: 1 - php_version: 8.1 + php_version: 8.2 ``` - You do not need to specify the PHP version's exact point release (for example, `8.1.10`), as these are managed by the platform and deployed automatically. @@ -190,4 +190,4 @@ Upgrade your current version of Drush if you see errors on the Pantheon Dashboar - [The pantheon.yml Configuration File](/pantheon-yml) -- [php.net - Backward Incompatible Changes](https://secure.php.net/manual/en/migration70.incompatible.php) \ No newline at end of file +- [php.net - Backward Incompatible Changes](https://secure.php.net/manual/en/migration70.incompatible.php) diff --git a/source/content/guides/secrets/01-introduction.md b/source/content/guides/secrets/01-introduction.md new file mode 100644 index 0000000000..4f8a784e42 --- /dev/null +++ b/source/content/guides/secrets/01-introduction.md @@ -0,0 +1,67 @@ +--- +title: Pantheon Secrets Guide +subtitle: Introduction +description: Securely store secrets in the Pantheon Platform. +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets +reviewed: "2024-08-22" +showtoc: true +--- +Pantheon Secrets is key to maintaining industry best practices for secure builds and application implementation. This feature provides a convenient mechanism for you to manage your secrets and API keys directly on the Pantheon platform. + +This guide covers features and use cases of the Pantheon Secrets feature; it could also be referred as Secrets Manager because that is the Terminus plugin name. + +## Features +Key features include: +* **Secure**: Secrets are encrypted at rest and securely hosted on Pantheon. +* **Easy to use**: Create and update secrets via Terminus. +* **Governable**: Secrets can be set at organization level and shared with all the sites owned by that organization. +* **Overridable**: Secrets can be overridden at environment level when needed. + +This feature also supports: +* The use of private repositories in Integrated Composer builds. +* The ability to set a `COMPOSER_AUTH` environment variable and/or a Composer `auth.json` authentication file. +* The ability to define the degree of secrecy for each managed item. + +## Access & Availability +This feature is available for anyone to use today at no additional cost. Currently released for Limited Availability, the [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin) will eventually be merged into Terminus core once released for General Availability in the future. + +### Installation +How to get started and use this feature: +1. [Install & authenticate Terminus](/terminus/install) if you have not done so already. +1. Install the [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin): + + ```bash{promptUser: user} + terminus self:plugin:install terminus-secrets-manager-plugin + ``` + +1. You can now use the newly installed Terminus commands, such as `secret:site:set`, to manage secrets securely on Pantheon. + +To see all available commands added by this plugin, refer to the [plugin's README file](https://github.com/pantheon-systems/terminus-secrets-manager-plugin?tab=readme-ov-file#site-secrets-commands). + +### Older plugin now deprecated +The new [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin) replaces the older [Terminus Secrets Plugin](https://github.com/pantheon-systems/terminus-secrets-plugin). The key differences are: + +- The new Terminus Secrets Manager Plugin stores secrets in an encrypted backend service. +- The older secrets plugin simply writes unencrypted values to a json file in `/files/private`. + +Once the Pantheon Secrets service becomes generally available and merged into Terminus core, the older `terminus-secrets-plugin` will be discontinued. If you use the older plugin to manage secrets today, we strongly encourage you to upgrade your security and experience by adopting this new feature. + +## Support +The [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin), [PHP Secrets SDK](https://github.com/pantheon-systems/customer-secrets-php-sdk), and [Pantheon Secrets](https://github.com/pantheon-systems/pantheon_secrets) Drupal module are open source. You can view the projects, file issues and feature requests, and contribute in their respective repositories on GitHub. + +* [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin) +* [Secrets SDK](https://github.com/pantheon-systems/customer-secrets-php-sdk) +* Pantheon Secrets Drupal module + * [github repo](https://github.com/pantheon-systems/pantheon_secrets) for issues & PRs + * [drupal.org](https://www.drupal.org/project/pantheon_secrets) for releases + +[Contact Support](https://dashboard.pantheon.io/#support/support/all) if you have questions or need help with Terminus. diff --git a/source/content/guides/secrets/02-secrets-overview.md b/source/content/guides/secrets/02-secrets-overview.md new file mode 100644 index 0000000000..5123b052eb --- /dev/null +++ b/source/content/guides/secrets/02-secrets-overview.md @@ -0,0 +1,113 @@ +--- +title: Pantheon Secrets Guide +subtitle: Secrets Overview +description: Gaining familiarity with some concepts about Pantheon Secrets will help you make the most of this feature. +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/overview +reviewed: "2024-08-22" +showtoc: true +--- + +

A secret is a key-value pair that should not be exposed to the general public, typically something like a password, API key, or other sensitive information that should not be added to version control.

+ +Each secret's value can be no larger than 16k (16384 Bytes) + +## Secret Type + +This represents how the secret is used. A secret can only have one type. + +Current types are: + + * `runtime`: This secret type can be retreived directly from your application code using the `pantheon_get_secret()` function. This is the recommended type if you want your application to be able to use the secret while it's operating. + + * `env`: This type is used to set environment variables. Environment variables are currently only supported for Integrated Composer builds; setting environment variables on the application server is unsupported. + + * `composer`: This secret type is specifically used for authentication when pulling Composer packages from private repositories. This is the recommended method for installing private composer packages. + + + + You can only set one type per secret and this cannot be changed later (unless you delete and recreate the secret). + + + + +## Secret Scope + +

A secret's scope is the answer to the question "Where is the secret's value available?". Once set, a secret's scope cannot be changed. The secret must be deleted and recreated to change its scope.

+ + * `ic`: This secret will be readable during Integrated Composer builds. You should use this scope to get access to your private repositories. + + * `web`: this secret will be readable by the application runtime. + + * `user`: this secret will be readable by the user. This scope should be set if you want to see the value of your secret displayed when listing site secrets with Terminus. The value for secrets without the the user scope is redacted in the Terminus secrets list. + +## Owning Entity +

Secrets are either owned by a site or an organization. Within that owning entity, the secret may have zero or more environment overrides.

+ +### Organization-owned secrets +Organization-owned secrets are available to every site and environment that are associated with the owning organization. A common use-cases is for a CI system and infrastructure that's shared among all sites in an organization. Note that secrets from "Supporting" Organizations are explicitly ***not shared*** with the sites they support. Sites receive secret key/value pairs from their Primary Organization only. + +### Site-owned secrets +Site-owned secrets are available to the site and all of its environments. A common use-case is Github tokens that a site's composer build can use to access private repos referenced in the composer file. + +### Environment override +Environment overrides provide overrides to a secret value for a specific environment. A common use case for this are API keys that are different in production and non-production environments. + + + +Due to platform design, the "environment" for Integrated Composer will always be either `dev` or a multidev. It will never be `test` or `live`. Therefore we do not recommend using environment overrides for Composer access. The primary use-case for environment overrides is for the CMS key-values and environment variables that need to be different between your live and non-live environments. + + + + +## Value Resolution + +1. Organization values have the lowest priority. They form the base value that is used when there is no more specific value provided for the site or environment. + +3. Site values will replace the organization values when present. To return the secret to it's organization value, simply delete the site value. + +4. Environmental overrides have the highest priority. If the override exists, it will become the value provided to the calling function. + +### The life of a secret + +When a given runtime (e.g. Integrated Composer or an environment PHP runtime) fetches secrets for a given site (and environment), the process will be as follows: + +- Fetch secrets for site (of the given type and scopes). + +- Apply environment overrides (if any) based on the requesting site environment. + +- If the site is owned by an organization: + + - Fetch the organization secrets. + + - Apply environment overrides (if any) based on the requesting site environment. + + - Merge the organization secrets with the site secrets (the following example will describe this process in more detail). + +### Example Value Resolution +Given you have an integrated composer site named `my-org-site` which belongs to an organization `my-org`, and you also have another integrated composer site named `my-personal-site` which belongs to your personal Pantheon account. + +When Integrated Composer attempts to get secrets for `my-personal-site` it will work like this: +- Get the secrets of scope `ic` for `my-personal-site`. +- Apply environment overrides for the current environment. +- Look at `my-personal-site` owner. In this case, it is NOT an organization so there are no organization secrets to merge. +- Process the resulting secrets to make them available to Composer. + +On the other hand, when Integrated Composer attempts to get secrets for `my-org-site`, it will work like this: +- Fetch the secrets in the scope of `ic` for `my-org-site`. +- Apply environment overrides for the current environment. +- Look at the site owner. The organization `my-org` is identified. +- Fetch the secrets for the organization `my-org` with scope `ic`. +- Apply the environment overrides to those secrets for the current environment. +- Merge the resulting organization secrets with the site secrets with the following caveats: + - Site secrets take precedence over organization secrets. This means that the value for site-owned secret named `foo` will be used instead of the value for an org-owned secret with the same name `foo`. + - Only the secrets for the OWNER organization are being merged. If the site has a Supporting Organization, it will be ignored. +- Process the resulting secrets to make them available to Composer. diff --git a/source/content/guides/secrets/04-php.md b/source/content/guides/secrets/04-php.md new file mode 100644 index 0000000000..4cd44ea260 --- /dev/null +++ b/source/content/guides/secrets/04-php.md @@ -0,0 +1,76 @@ +--- +title: Pantheon Secrets Guide +subtitle: PHP Usage +description: How to read Pantheon Secrets from code. +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/php +reviewed: "2024-08-22" +showtoc: true +--- + +## Reading secrets from PHP +Secrets can be read, updated, created, and deleted via the [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin). WordPress and Drupal however, can only read secrets at runtime - there is no way to modify secrets via the application or in code. + +Secrets must have the scope `web` to be visible from your application. Secrets are cached in the server for 15 minutes, so you must wait for a while after modifying secret values before they will be available for use. This cache is also encrypted at rest. + +Note: this also applies to quicksilver scripts. + +### Use the pantheon_get_secret PHP function + +The function `pantheon_get_secret()` may be used to fetch the value of a single secret. + +```php +if ( function_exists('pantheon_get_secret') ) { + $secret_value = pantheon_get_secret("SECRET_NAME"); +} +``` + +## WordPress detailed example +In this guide we will go over an end-to-end example on how to setup secrets for a given site and how to read those secrets in `wp-config.php`. For this example, we will use the [WP Mail SMTP](https://wordpress.org/plugins/wp-mail-smtp/) plugin to setup SendGrid. + +### Prerequisites + +- Make sure you have access to a WordPress site on Pantheon. + +- Make sure you have [Terminus installed](https://docs.pantheon.io/terminus/install#install-terminus) on your local machine. + +- Install the [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#installation). + +### Steps + +1. Install and activate the [WP Mail SMTP](https://wordpress.org/plugins/wp-mail-smtp/) plugin. +1. Make sure your SendGrid account is correctly configured and allows sending email. + +1. Create a SendGrid API key by following the [SendGrid instructions](https://docs.sendgrid.com/ui/account-and-settings/api-keys#creating-an-api-key). + +1. Store the API key as a site secret: + + ```bash{promptUser: user} + terminus secret:site:set sendgrid_api --scope=web --type=runtime + ``` + + As a best practice, the non-production environments should be the default and then override that value with a [secret environment override](/guides/secrets/overview#environment-override) to change the API key for the live environment (for example, if you want to use different SendGrid accounts for live and dev environments). +1. Add the following to `wp-config.php`, replacing placeholder values (e.g., `example@example.com` and `Example From Name`): + + ```php + define( 'WPMS_ON', true ); // True turns on the WPMS constants for usage below, false turns it off. + define( 'WPMS_MAIL_FROM', 'example@example.com' ); + define( 'WPMS_MAIL_FROM_NAME', 'Example From Name'); + define( 'WPMS_MAILER', 'sendgrid' ); + if ( function_exists('pantheon_get_secret') ) { + define( 'WPMS_SENDGRID_API_KEY', pantheon_get_secret( 'sendgrid_api' ) ); + } + ``` + +1. Go to the SendGrid email test page (`/wp-admin/admin.php?page=wp-mail-smtp-tools&tab=test`) and test your SendGrid integration by sending a test email. + +## More Resources +For advanced use cases, you may consider leveraging the [Secrets SDK](https://github.com/pantheon-systems/customer-secrets-php-sdk) library as an alternative to the `pantheon_get_secret` function. diff --git a/source/content/guides/secrets/05-drupal.md b/source/content/guides/secrets/05-drupal.md new file mode 100644 index 0000000000..070cd01c48 --- /dev/null +++ b/source/content/guides/secrets/05-drupal.md @@ -0,0 +1,97 @@ +--- +title: Pantheon Secrets Guide +subtitle: Drupal Key Usage +description: How to configure Sendgrid using Pantheon Secrets with Drupal's Key module. +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/drupal +reviewed: "2024-08-22" +showtoc: true +--- + +If you want to use Pantheon Secrets in your Drupal application through the [Key module](https://www.drupal.org/project/key), you should use the [Pantheon Secrets](https://www.drupal.org/project/pantheon_secrets) module. + +## Pantheon Secrets detailed example + +In this guide we will go over an end-to-end example on how to setup secrets for a given site and how to use those secrets on a module that integrates with the Key module. For this example, we will use the [SendGrid API](https://www.drupal.org/project/sendgrid_api) and [SendGrid Mailer](https://www.drupal.org/project/sendgrid_mailer) modules. + +### Prerequisites + +- Make sure you have access to a Drupal 9.4 or greater site running PHP 8.0 or above hosted on Pantheon. + +- Make sure you have [Terminus installed](https://docs.pantheon.io/terminus/install#install-terminus) on your local machine. + +- Install the [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#installation). + +### Steps + +1. Install the required modules in your Drupal site and push the changes to Pantheon: + ```bash{promptUser: user} + composer require drupal/pantheon_secrets drupal/sendgrid_api drupal/sendgrid_mailer + git add composer.json composer.lock + git commit -m "Add Pantheon Secrets and SendGrid modules." + git push + ``` + +1. Enable the modules: + ```bash{promptUser: user} + terminus drush . -- en -y pantheon_secrets sendgrid_api sendgrid_mailer + ``` + +1. Make sure your SendGrid account is correctly configured and allows sending email. + +1. Create a SendGrid API key by following the [SendGrid instructions](https://docs.sendgrid.com/ui/account-and-settings/api-keys#creating-an-api-key). + +1. Store the API key as a site secret: + ```bash{promptUser: user} + terminus secret:site:set sendgrid_api --scope=web --type=runtime + ``` + + As a best practice, the non-production environments should be the default and then override that value with a [secret environment override](/guides/secrets/overview#environment-override) to change the API key for the live environment (for example, if you want to use different SendGrid accounts for live and dev environments). + +1. Add the Key entity in one of the different available ways: + + * **Option 1: Manually** + + Go to `/admin/config/system/keys` and click **Add key**. Select Pantheon Secret as the key provider and your secret name from the dropdown (make sure you select "SendGrid" as the Key type and "Pantheon" as the Key provider) + + ![Screenshot of creating a new Key entity with type "Sendgrid" and provider "Pantheon"](../../../images/guides/secrets/add-key.png) + + * **Option 2: Sync Keys via Drupal Admin** + + Go to `/admin/config/system/keys/pantheon` and click on the "Sync Keys" button to get all of the available secrets into Key entities. + + ![Screenshot of Sync Pantheon Secrets page in Drupal UI](../../../images/guides/secrets/sync-keys.png) + + Then, go to `/admin/config/system/keys` to edit the `sendgrid_api` Key and change the type to "SendGrid". + + * **Option 3: Sync Keys via Terminus** + + Use the provided Drush command to sync all of your secrets into Key entities: + + ```bash{promptUser: user} + terminus drush . -- pantheon-secrets:sync + ``` + + Then, go to `/admin/config/system/keys` to edit the `sendgrid_api` Key and change the type to "SendGrid". + +1. Go to the SendGrid API Configuration page (`/admin/config/services/sendgrid`) and select your Key item. + + ![Screenshot of Sendgrid API Configuration page in Drupal UI](../../../images/guides/secrets/sendgrid-config.png) + +1. Make sure your site "Email Address" (`/admin/config/system/site-information`) matches a verified Sender Identity in SendGrid. + +1. Go to the Default Mail System Configuration page (`/admin/config/system/mailsystem`) and set `Formatter` and `Sender` to `SendGrid Mailer`. + +1. Go to the SendGrid email test page (`/admin/config/services/sendgrid/test`) and test your SendGrid integration by sending a test email. + + ![Screenshot of Sendgrid email test page in Drupal UI](../../../images/guides/secrets/sendgrid-email-test.png) + +1. The email should get to your inbox. Enjoy! diff --git a/source/content/guides/secrets/06-composer.md b/source/content/guides/secrets/06-composer.md new file mode 100644 index 0000000000..2697b7ebf1 --- /dev/null +++ b/source/content/guides/secrets/06-composer.md @@ -0,0 +1,154 @@ +--- +title: Pantheon Secrets Guide +subtitle: Integrated Composer Usage +description: How to use Pantheon Secrets with Pantheon's Integrated Composer. +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/composer +reviewed: "2024-08-22" +showtoc: true +--- + +## Using secrets with Integrated Composer + +### Mechanism 1: OAuth composer authentication (recommended) +If your Composer-based dependency is private, and the repository supports OAuth authentication, storing your token as a secret in the Pantheon Secrets API is a simpler way to allow access to those private repositories. + + + + + +1. [Generate a GitHub token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). The GitHub token must have all "repo" permissions selected. + + **Note:** Check the repo box that selects all child boxes. **Do not** check all child boxes individually as this does not set the correct permissions. + + ![image](https://user-images.githubusercontent.com/87093053/191616923-67732035-08aa-41c3-9a69-4d954ca02560.png) + +1. Set the secret value to the token via terminus: + + ```bash{promptUser: user} + terminus secret:site:set github-oauth.github.com --type=composer --scope=ic + ``` + +1. Add your private repository to the `repositories` section of `composer.json`: + + ```json + { + "type": "vcs", + "url": "https://github.com/your-organization/your-repository-name" + } + ``` + + Your repository should contain a `composer.json` that declares a package name in its `name` field. It should specify a `type` like `wordpress-plugin` or `drupal-module` for example. For these instructions, we will assume your package name is `your-organization/your-package-name`. + +1. Require the package defined by your private repository's `composer.json` by either adding a new record to the `require` section of the site's `composer.json` or with a `composer require` command: + + ```bash{promptUser: user} + composer require your-organization/your-package-name + ``` + +1. Commit your changes and push to Pantheon. + + + + + +1. [Generate a GitLab token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html). Ensure that `read_repository` scope is selected for the token. + +1. Set the secret value to the token via Terminus: + + ```bash{promptUser: user} + terminus secret:site:set gitlab-oauth.gitlab.com --type=composer --scope=ic + ``` + +1. Add your private repository to the `repositories` section of `composer.json`: + + ```json + { + "type": "vcs", + "url": "https://gitlab.com/your-group/your-repository-name" + } + ``` + + Your repository should contain a `composer.json` that declares a package name in its `name` field. It should specify a `type` like `wordpress-plugin` or `drupal-module` for example. For these instructions, we will assume your package name is `your-organization/your-package-name`. + +1. Require the package defined by your private repository's `composer.json` by either adding a new record to the `require` section of the site's `composer.json` or with a `composer require` command: + + ```bash{promptUser: user} + composer require your-group/your-package-name + ``` + +1. Commit your changes and push to Pantheon. + + + + + +1. [Generate a Bitbucket OAuth consumer](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/). Ensure that Read repositories permission is selected for the consumer. Set the consumer as private and put a (dummy) callback URL. + +1. Set the secret value to the consumer info via Terminus: + ```bash{promptUser: user} + terminus secret:site:set bitbucket-oauth.bitbucket.org " " --type=composer --scope=ic + ``` + +1. Add your private repository to the `repositories` section of `composer.json`: + + ```json + { + "type": "vcs", + "url": "https://bitbucket.org/your-organization/your-repository-name" + } + ``` + + Your repository should contain a `composer.json` that declares a package name in its `name` field. It should specify a `type` like `wordpress-plugin` or `drupal-module` for example. For these instructions, we will assume your package name is `your-organization/your-package-name`. + +1. Require the package defined by your private repository's `composer.json` by either adding a new record to the `require` section of the site's `composer.json` or with a `composer require` command: + + ```bash{promptUser: user} + composer require your-organization/your-package-name + ``` + +1. Commit your changes and push to Pantheon. + + + + + +### Mechanism 2: HTTP Basic Authentication + +In the case where you have a Composer dependency that only supports HTTP Basic Authentication, you may create a `COMPOSER_AUTH json` and make it available via the `COMPOSER_AUTH` environment variable if you have multiple private repositories on multiple private domains. + +Composer has the ability to read private repository access information from the environment variable: `COMPOSER_AUTH`. The `COMPOSER_AUTH` variables must be in a [specific JSON format](https://getcomposer.org/doc/articles/authentication-for-private-packages.md#http-basic). + +**Format example:** + +```bash +#!/bin/bash + +read -e COMPOSER_AUTH_JSON <<< { + "http-basic": { + "github.com": { + "username": "my-username1", + "password": "my-secret-password1" + }, + "repo.example2.org": { + "username": "my-username2", + "password": "my-secret-password2" + }, + "private.packagist.org": { + "username": "my-username2", + "password": "my-secret-password2" + } + } +} +EOF + +terminus secret:site:set ${SITE_NAME} COMPOSER_AUTH ${COMPOSER_AUTH_JSON} --type=env --scope=ic +``` diff --git a/source/content/guides/secrets/07-local.md b/source/content/guides/secrets/07-local.md new file mode 100644 index 0000000000..cdb437cae2 --- /dev/null +++ b/source/content/guides/secrets/07-local.md @@ -0,0 +1,70 @@ +--- +title: Pantheon Secrets Guide +subtitle: Local Development Usage +description: Developing locally presents some unique challenges once Pantheon Secrets are built into your workflow. These are some tips to help you get past struggling with trying to reproduced secret behavior while developing locally. +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/local +reviewed: "2024-08-22" +showtoc: true +--- +## Local Environment Usage + +The [Pantheon Secrets SDK](https://github.com/pantheon-systems/customer-secrets-php-sdk) includes a `CustomerSecretsFakeClient` implementation that is used when the SDK runs outside of Pantheon infrastructure. This client uses a secrets JSON file to build the secrets information emulating what happens on the platform using the Secrets service. + +To get this file, you should use the [plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin/) `secret:site:local-generate` command and then set an environment variable into your local environment (or docker container if you are running a docker-ized environment) with name `CUSTOMER_SECRETS_FAKE_FILE` and use the absolute path to the file as the value. + + +### LANDO example + +1. To setup this using lando, you should modify your `.lando.yml` like this: + ```yaml + services: + appserver: + overrides: + environment: + CUSTOMER_SECRETS_FAKE_FILE: /app/secrets.json + ``` + +2. Generate the secrets file like this: + ```bash{promptUser: user} + terminus secret:site:local-generate --filepath=./secrets.json + ``` + +3. And rebuild lando application: + ```bash{promptUser: user} + lando rebuild -y + ``` + +Now, you will be able to use your secrets through the SDK. + + +### DDEV example + +1. CD to your ddev root directory. + +2. To setup using DDEV, add the following to your `~/.ddev/config.yml` + ```yaml + web_environment: + - CUSTOMER_SECRETS_FAKE_FILE=./secrets.json + ``` + +3. Generate the secrets file + ```bash{promptUser: user} + terminus secret:site:local-generate --filepath=./secrets.json + ``` + +4. Restart your ddev environment + ```bash{promptUser: user} + ddev restart + ``` + +## Restrictions +For secrets that do not have the "user" scope, the `secret:site:local-generate` command will set the value of the secret to "null". Edit this file and replace the null values with appropriate test values for local development. diff --git a/source/content/guides/secrets/08-troubleshooting.md b/source/content/guides/secrets/08-troubleshooting.md new file mode 100644 index 0000000000..1644b2ea73 --- /dev/null +++ b/source/content/guides/secrets/08-troubleshooting.md @@ -0,0 +1,102 @@ +--- +title: Pantheon Secrets Guide +subtitle: Troubleshooting +description: Securely store secrets in the Pantheon Platform. +contributors: [stovak] +contenttype: [guide] +innav: [true] +categories: [secrets] +cms: [drupal, wordpress] +audience: [development] +product: [secrets] +integration: [--] +tags: [reference, cli, local, terminus, workflow] +permalink: docs/guides/secrets/troubleshooting +reviewed: "2024-08-22" +showtoc: true +--- + +## Default secret value does not exist +Setting an environmental override when no site or organization secret has been set, results in an error like this: + +``` +terminus secret:site:set site.dev mysecretnonexist foobar +[error] An error happened when trying to set the secret. +[error] Secret 'mysecretnonexist' does not exist. You should create the default secret value first. +``` + +A site-level or organization-level secret must be set first before you can set an environmental override. + +## Invalid key name +There are some validations in place for the key name based on the key type. As an example, a secret name of type env must match the following regex: `^[a-zA-Z_][a-zA-Z0-9_]*$`. Failure to comply with those validations results in errors like this: + +``` +terminus secret:site:set site 1nvalid value --type=env + [error] An error happened when trying to set the secret. + [error] Invalid key name '1nvalid': Environment variable names must start with a letter or underscore, and can only contain letters, numbers, and underscores. +``` + +Either make your secret name match the expected pattern or change the type if that’s an option. + +## Integrated Composer Build fails on private packages + +This is the most common error when sites are using secrets and Integrated Composer. This may manifest in different ways and may be caused by different problems. This playbook tries to cover them. + +### Error getting a private package during the IC build + +This is the most common error; an example message associated to this error is: + +``` +Failed to download vendor/package from dist +``` +(where vendor/package may be any private package) + +Some possible causes for this error: + +- **Problem:** Secrets are not correctly set for the site. Secrets for Integrated Composer to use need to be type `composer` and have scope `ic`. Secret types and scopes are covered in the [Basic Concepts](/guides/secrets/02-basic-concepts) documentation. + + **Solution:** ask the client to delete and recreate the secret if scope and type do not match for the given secret name + +- **Problem:** Secret value/token may be expired + + **Solution:** ask the client to set the secret again to an updated value + +- **Problem**: Site may be running on a PHP version below 8.0. If this is the case, there will be a message in the job output: “Skipping setting up secrets as it is not supported in PHP below 8.0” + + **Solution**: Upgrade the client to a supported PHP version. + +- **Problem:** Errors with paid WordPress plugins. + + Example error message associated to this: + "Could not find a license key for ACF PRO. No valid license key could be found" + + Possible causes for this error: + + - This error happens when [https://packagist.org/packages/pivvenit/acf-pro-installer](https://packagist.org/packages/pivvenit/acf-pro-installer) is used and the ACF_PRO_KEY is not available + - Please note that the plugin is no longer supported by the developer as ACF now has built-in composer support. It’s a good idea to switch to the composer-based version. + + **Solution:** + + If the plugin is still in use: + - Look for the secret with name ACF_PRO_KEY, it should be of type env and scope ic. Delete and recreate if type or scope doesn’t match. + - Make sure the site is running PHP >= 8 + +- **Problem:** Error cloning private package via SSH. IC builds + secrets management is intended to clone over https and not over ssh as that would require a ssh key and the process to set things up is way more complex than http auth. + + An example error message associated to this error is: + + ``` + Failed to execute git clone --mirror -- 'git@github.com:biltmoreco/advanced-custom-fields-pro.git' '/home/pantheon-app/.cache/composer/vcs/git-github.com-biltmoreco-advanced-custom-fields-pro.git/' + ``` + + **Solution:** Change the repository definition (in composer.json) to use https instead of ssh. In this example, the repository would be https://github.com/biltmoreco/advanced-custom-fields-pro.git + + +## Rate limiting +The service supports up to 3 requests per second per user through Terminus. If you hit that limit, the API will return a `429` error code and the plugin will throw an error. + +The PHP SDK and `pantheon_get_secret()` function are not affected by this rate limiting. + +## Still having issues? + +[Contact support](/guides/support/contact-support/) diff --git a/source/content/guides/solr-drupal/02-solr-drupal.md b/source/content/guides/solr-drupal/02-solr-drupal.md index 18f1d7b8ec..e843864814 100644 --- a/source/content/guides/solr-drupal/02-solr-drupal.md +++ b/source/content/guides/solr-drupal/02-solr-drupal.md @@ -10,8 +10,8 @@ audience: [development] product: [search] integration: [--] tags: [solr, search, modules] -contributors: [carolynshannon, joan-ing] -reviewed: "2022-12-13" +contributors: [carolynshannon, joan-ing, jazzsequence] +reviewed: "2024-08-09" showtoc: true permalink: docs/guides/solr-drupal/solr-drupal editpath: solr-drupal/02-solr-drupal.md @@ -71,10 +71,6 @@ Ensure you review our documentation on [Git](/guides/git/git-config), [Composer] Each Pantheon environment (Dev, Test, Live, and Multidevs) has its own Solr server. Indexing and searching in one environment does not impact any other environment. -## Enable Access to Pantheon Search - -As a Limited Availability participant, your will need to manually enable access to Solr 8 for your site, for each environment in which you would like to create an index (Dev, Test, Live, and Multidevs). - ### Enable at the Site Level You must enable Pantheon Search at the site-level and add the Apache Solr Index Server. This can be done by using either the Terminus CLI or through the Site Dashboard. @@ -115,26 +111,6 @@ You must configure the `pantheon.yml` for the platform environment after you ena For more information, refer to the documentation on [Specifying a Solr version](/pantheon-yml#specify-a-solr-version) -#### Verify `pantheon.yml` is Configured Correctly - -After you specify the Solr 8 version in the Dev environment of your Drupal site, verify that the environment is configured to use Solr 8. The configured Solr environment will have several `PANTHEON_INDEX_*` variables, one of which will be `PANTHEON_INDEX_PORT`. If Solr 8 is configured correctly, the `PANTHEON_INDEX_PORT` value will be `443`. If any other value is displayed, your site is still configured to use Solr 3. - -1. Run the command below: - - ```bash{promptUser:user} - terminus drush SITE.ENV -- ev "phpinfo();" | grep PANTHEON_INDEX_PORT - ``` - -1. Confirm that the `PANTHEON_INDEX_PORT` value is `443`. The output from the command above should look similar to the example below. - - ```bash{promptUser:user} - terminus drush solr8-sandbox.dev -- ev "phpinfo();" | grep PANTHEON_INDEX_PORT - [warning] This environment is in read-only Git mode. If you want to make changes to the codebase of this site (e.g. updating modules or plugins), you will need to toggle into read/write SFTP mode first. - PANTHEON_INDEX_PORT => 443 - $_SERVER['PANTHEON_INDEX_PORT'] => 443 - $_ENV['PANTHEON_INDEX_PORT'] => 443 - ``` - ## Install and Enable the Search API Pantheon Module To install and enable the Search API Pantheon Module, access to Solr 8 must be enabled and `pantheon.yml` should be configured to use the Solr 8 version as described in the steps above. diff --git a/source/content/guides/support/01-scope.md b/source/content/guides/support/01-scope.md index 3f1b056342..4d02cef000 100644 --- a/source/content/guides/support/01-scope.md +++ b/source/content/guides/support/01-scope.md @@ -14,21 +14,21 @@ type: guide showtoc: true permalink: docs/guides/support/ editpath: support/01-scope.md -reviewed: "2022-12-13" +reviewed: "2024-09-10" --- ![Screenshot of the Support Tab](../../../images/dashboard/support-tab.png) ## Support Features and Response Times -Pantheon offers a range of Account options that include the features required for mission critical sites, such as 24x7x365 emergency on-call, debugging assistance, and concierge pre-launch load testing for Diamond Elite sites. +Pantheon offers a range of support options for mission-critical sites, such as 24x7x365 emergency ticket, debugging assistance, and concierge pre-launch load testing for Diamond Elite sites. | Account Tier | Silver | Gold | Platinum | Diamond | |-----------------------------------------------------------|-----------------------------------|-----------------------------------|------------------------|--------------------| | **Scope** | Platform | Technical | Performance | Dedicated Team | -| [**Chat**](/guides/support/contact-support/#real-time-chat-support) | 24x5 | 24x7 | 24x7: Priority | 24x7: Top Priority | -| [**Tickets**](/guides/support/contact-support/#ticket-support) | ❌ | 24x5: 8 Hours | 24x7: 2 Hours | 24x7: 1 Hour | -| [**Emergency On-Call**](/guides/support/contact-support/#premium-technical-support-and-on-call-services) | ❌ | ❌ | 24x7: 1 Hour | 24x7: 15 Minutes | +| [**Live chat**](/guides/support/contact-support/#live-chat) | 24x5 | 24x7 | 24x7: Priority | 24x7: Top Priority | +| [**General support ticket**](/guides/support/contact-support/#general-support-ticket) | ❌ | 24x5: 8 Hours | 24x7: 2 Hours | 24x7: 1 Hour | +| [**Emergency ticket**](/guides/support/contact-support/#emergency-ticket) | ❌ | ❌ | 24x7: 1 Hour | 24x7: 15 Minutes | | [**Professional Services**](/guides/professional-services) | ❌ | Available for Purchase | Available for Purchase | Available for Purchase | Pantheon's [Sales](https://pantheon.io/contact-sales?docs) and Billing teams are generally available on business days, Monday through Friday, 9AM to 5PM PST. diff --git a/source/content/guides/support/02-contact-support.md b/source/content/guides/support/02-contact-support.md index 0be655c1dd..2df062c84d 100644 --- a/source/content/guides/support/02-contact-support.md +++ b/source/content/guides/support/02-contact-support.md @@ -14,7 +14,7 @@ type: guide showtoc: true permalink: docs/guides/support/contact-support/ editpath: support/02-contact-support.md -reviewed: "2020-12-13" +reviewed: "2024-09-10" --- This section provides information on how to open a support ticket as well as other ways to contact support. @@ -25,45 +25,41 @@ We recommend you begin your Support journey from the affected [Personal Workspac -## Ticket Support +#### Provide a detailed description +For every method of contacting Pantheon Support documented on this page, please prepare and include a **detailed description** for the issue you're experiencing, such as: +- Steps to reproduce the issue (including URLs or paths to files). +- Environments affected (Multidev/Dev/Test/Live), if applicable. +- When the issue began. +- Error messages received, if applicable. +- Links to screenshots or screencasts of the behavior, if necessary. -The ticket support feature is available to certain Account packages and account types. For details, refer to the [support feature table](/guides/support/#support-features-and-response-times). Tickets are associated with the site from which the ticket is opened. Please be sure that if you maintain several sites, that you open the ticket from the correct site's dashboard. +## General support ticket -1. [Go to the workspace](/guides/account-mgmt/workspace-sites-teams/workspaces#switch-between-workspaces) or [Site Dashboard](/guides/account-mgmt/workspace-sites-teams/sites#site-dashboard) affected by the issue. +The ticket support feature is available to certain Account packages and account types. For details, refer to the [support feature table](/guides/support/#support-features-and-response-times). Tickets are associated with the site from which the ticket is opened. Please be sure that if you maintain several sites, that you open the ticket from the correct site's dashboard. -1. Click **Support**, then **Open Ticket**. This automatically includes the site/workspace and user information. +1. [Go to the workspace](/guides/account-mgmt/workspace-sites-teams/workspaces#switch-between-workspaces). -1. Choose the **ticket type**. +1. Go to the **Support** tab, then select **Open support ticket**. 1. Enter a subject (summary of your issue). -1. Provide a detailed summary of your support request, such as: - - Steps to reproduce the issue (including URLs or paths to files). - - Environments affected (Multidev/Dev/Test/Live), if applicable. - - When the issue began. - - Error messages received, if applicable. - - Links to screenshots or screencasts of the behavior, if necessary. +1. Provide a [detailed description](#provide-a-detailed-description) of your support request. -1. Click **Open Ticket** +1. Click **Submit ticket** After a ticket is submitted, you can view details for your support requests. If are you are part of an Workspace, your support tickets are visible to all members except [Unprivileged users](/guides/account-mgmt/workspace-sites-teams/teams#organizations-roles-and-permissions). -## Real Time Chat Support +## Live Chat Start a chat with our Support Team to ask questions or request assistance on issues within our [scope of support](#scope-of-support). This support feature is available to all users and sites across all plans, including Sandbox. To receive the highest level of support available to your site or Workspace, remember to access the chat from the Workspace if available. -1. [Go to the workspace](/guides/account-mgmt/workspace-sites-teams/workspaces#switch-between-workspaces) or [Site Dashboard](/guides/account-mgmt/workspace-sites-teams/sites#site-dashboard) affected by the issue. +1. [Go to the workspace](/guides/account-mgmt/workspace-sites-teams/workspaces#switch-between-workspaces). -1. Click **Support**, **Launch Chat**, then **New Conversation**. +1. Go to the **Support** tab, then select **Start chat**. -1. Provide a detailed summary of your support request, such as: - - Steps to reproduce the issue (including URLs or paths to files). - - Environments affected (Multidev/Dev/Test/Live), if applicable. - - When the issue began. - - Error messages received, if applicable. - - Links to screenshots or screencasts of the behavior, if necessary. +1. Provide a [detailed description](#provide-a-detailed-description) of your support request. You can download a transcript of your chat with the button: @@ -71,12 +67,24 @@ You can download a transcript of your chat with the -Some in-browser ad or tracking blockers can interfere with the **Launch Chat** button. If you don't see it, try allowlisting `pantheon.io` or disabling the browser extension. Intercom has posted more details on [why this happens](https://www.intercom.com/help/en/articles/2546256-troubleshooting-when-the-messenger-doesn-t-appear) on their site. +Some in-browser ad or tracking blockers may interfere with the **Start chat** button. If you don't see the button, try allowlisting `pantheon.io` or disabling the browser extension. Intercom has provided more details on [why this happens](https://www.intercom.com/help/en/articles/2546256-troubleshooting-when-the-messenger-doesn-t-appear) on their site. -## Premium Technical Support and On-Call Services +## Emergency ticket +**Diamond** and **Platinum** customers also have the option to open an **emergency ticket** (formerly On-call help) for business-critical issues. Pantheon escalates emergency tickets to our support engineers, even during off-hours. If your issue is non-business-critical, please open a [general support](#general-support-ticket) ticket instead. + +1. [Go to the workspace](/guides/account-mgmt/workspace-sites-teams/workspaces#switch-between-workspaces). -Diamond and Platinum Account customers can call Pantheon's premium technical support line directly for any technical issues, escalations, site, billing, or overages queries. The phone number can be found in your Workspace, in the Support tab. +1. Go to the **Support** tab, then select **Open emergency ticket**. + +1. Enter a subject (summary of your issue). + +1. Provide a [detailed description](#provide-a-detailed-description) of your support request. + +1. Click **Submit ticket** + +After a ticket is submitted, you can view details for your support requests. If are you are part of an Workspace, your support tickets are visible to all members except [Unprivileged users](/guides/account-mgmt/workspace-sites-teams/teams#organizations-roles-and-permissions). -Diamond and Platinum customers also have the option to page Pantheon's operations response team, either via the Pantheon Dashboard or via an emergency 800-number. Pantheon on-call immediately escalates to the on-call engineering team. The scope of on-call support is limited to emergencies and business critical issues. +## Call Us +**Diamond** and **Platinum** customers can call the 24/7 Premium Support Hotline for any technical issues, escalations, site, billing, or overages queries. You can find the phone number in the Support tab of your workspace. diff --git a/source/content/guides/support/07-faq.md b/source/content/guides/support/07-faq.md index aea8f06e40..dd7e4eede1 100644 --- a/source/content/guides/support/07-faq.md +++ b/source/content/guides/support/07-faq.md @@ -13,20 +13,20 @@ type: guide showtoc: true permalink: docs/guides/support/faq/ editpath: support/06-faq.md -reviewed: "2020-12-13" +reviewed: "2024-09-10" --- ### Can I request a feature be added to the platform? Yes. For more details, talk to your Customer Success Manager or [contact sales](https://pantheon.io/contact-us). -### Is there a support number we can call? If so, is this service available for every package? +### Is there a support number we can call? Is this service available for all account tiers? -Diamond and Platinum customers have access to Pantheon On-Call, which includes an emergency 800-number to page an on-call engineer. For more details, [contact sales](https://pantheon.io/contact-us). +Diamond and Platinum customers can call the 24/7 Premium Support Hotline for any technical issues, escalations, site, billing, or overages queries. You can find the phone number in the Support tab of your workspace. Note that this is strictly for filing a ticket, and you will not reach a support engineer by using this method. -### If we open a ticket, do you provide 24/7 support for outages, or are there time restrictions? +### Is there 24/7 support for emergencies like incidents or outages? Is this service available for all account tiers? -Diamond, Platinum and Gold customers can file a downtime ticket for outages on our Support page, and we provide 24/7 on-call support for all platform issues affecting Diamond and Platinum customers. +Diamond and Platinum customers can open an emergency ticket for business-critical issues. Pantheon escalates emergency tickets to our support engineers, even during off-hours. To ensure effective triage, please open the emergency ticket from the workspace of the affected site. ### What if I can't login to the Pantheon Dashboard? diff --git a/source/content/guides/wordpress-composer/01-introduction.md b/source/content/guides/wordpress-composer/01-introduction.md index 5e8ce60e68..41467a67b2 100644 --- a/source/content/guides/wordpress-composer/01-introduction.md +++ b/source/content/guides/wordpress-composer/01-introduction.md @@ -15,7 +15,7 @@ showtoc: true permalink: docs/guides/wordpress-composer --- -[Composer](https://getcomposer.org/) is a widely-used PHP dependency and package manager that provides a simplified method to manage packages (plugins, themes and -- with the [WordPress (Composer Managed) upstream](/wordpress-composer-managed), WordPress core itself) used by a WordPress site. +[Composer](https://getcomposer.org/) is a widely-used dependency and package manager for PHP. Composer provides an easy way to manage packages used by a WordPress site. Packages can be plugins, themes, other PHP libraries and even WordPress core itself. At the most basic level, Composer requires: diff --git a/source/content/guides/wordpress-composer/02-wordpress-composer-managed.md b/source/content/guides/wordpress-composer/02-wordpress-composer-managed.md index 408f82aabf..ca4263062d 100644 --- a/source/content/guides/wordpress-composer/02-wordpress-composer-managed.md +++ b/source/content/guides/wordpress-composer/02-wordpress-composer-managed.md @@ -17,12 +17,6 @@ permalink: docs/guides/wordpress-composer/wordpress-composer-managed anchorid: wordpress-composer-managed --- - - -The WordPress Composer Managed upstream is available for [Early Access](/oss-support-levels#early-access) participants. Features for WordPress Composer Managed are in active development. Pantheon's development team is rolling out new functionality often while this product is in Early Access. Visit [our community Slack](https://pantheon-community.slack.com/) if you don't already have an account) to connect with other Pantheon users also using the upstream (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/)). Please review Pantheon's [Software Evaluation Licensing Terms](https://legal.pantheon.io/#contract-hkqlbwpxo) for more information about access to our software. - - - This section provides information on how to use Bedrock with Integrated Composer on a WordPress site. WordPress does not natively support [Composer](https://getcomposer.org/), however, [Bedrock](https://roots.io/bedrock/) is a WordPress-specific framework for using Composer on WordPress sites. @@ -123,6 +117,20 @@ composer update vendor/package Replace `vendor/package` with the package name you want to update. This will update only the named package to the latest version that matches the version constraints in your `composer.json` file. +## Troubleshooting +### Restore overwritten `composer.json` +Sometimes, when a given upstream update includes changes to the `composer.json` file, it can conflict with your site's `composer.json` file. In these cases, applying the upstream update could result in the loss of content in your `composer.json` file. + +After applying such an update, check the commit log in the site dashboard. If you see many packages have been **removed**, you'll know the site's `composer.json` file has been overwritten by the upstream and needs to be resotred: + +![Pantheon update removing Composer packages](../../../images/wordpress-composer/02-wordpress-composer-json-removals.png) + +The easiest way to resolve this is to simply back up a copy of your current `composer.json` file locally before applying core updates. Then, apply the updates on Pantheon and `git pull` them into your local repository. From there, you can then restore the contents of `composer.json` based on your local back up of the file, run `composer update` and commit the changes. + +This may miss out on any actual updates to the `composer.json` in the upstream, so it's a good idea to check the [`composer.json` in the upstream repository](https://github.com/pantheon-upstreams/wordpress-composer-managed/blob/main/composer.json) to see if there are any changes you might want to incorporate into your own `composer.json` file. + +**Note:** If your site is using the Decoupled upstream for Front End Sites, the [`composer.json` is in the Decoupled WordPress (Composer Managed) upstream repository](https://github.com/pantheon-upstreams/decoupled-wordpress-composer-managed/blob/main/composer.json) + ## Report an Issue Create an [issue in the Github repo](https://github.com/pantheon-systems/wordpress-composer-managed/issues) for the team to review and address if you discover an issue with the WordPress Composer Managed upstream. diff --git a/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md b/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md index fcb778aad3..7c94e8882b 100644 --- a/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md +++ b/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md @@ -19,7 +19,7 @@ This section provides steps to create a new Pantheon WordPress site that will us -Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create a Composer-managed WordPress site with **Bedrock**. This upstream is currently in EA and **Terminus Build Tools** does not currently support the Bedrock-based WordPress (Composer Managed) upstream. +Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create a Composer-managed WordPress site with **Bedrock**. **Terminus Build Tools** does not currently support the Bedrock-based WordPress (Composer Managed) upstream. diff --git a/source/content/guides/wordpress-composer/04-multisite-configuration.md b/source/content/guides/wordpress-composer/04-multisite-configuration.md new file mode 100644 index 0000000000..bdc95a0349 --- /dev/null +++ b/source/content/guides/wordpress-composer/04-multisite-configuration.md @@ -0,0 +1,72 @@ +--- +title: WordPress with Composer on Pantheon +subtitle: Multisite Configuration +description: Learn how to configure a WordPress multisite with Composer on Pantheon. +contenttype: [guide] +innav: [false] +categories: [dependencies] +cms: [wordpress] +audience: [development] +product: [--] +integration: [--] +tags: [wordpress] +contributors: [jazzsequence] +layout: guide +showtoc: true +permalink: docs/guides/wordpress-composer/multisite-configuration +anchorid: multisite-configuration +--- + +This section provides information on how to configure your WordPress (Composer Managed) site on Pantheon for WordPress multisite. This guide assumes that you have already set up a [WordPress Multisite upstream](/guides/multisite/#request-a-wordpress-multisite) and created a new site using that upstream. If you haven't already, you should also read through our [guide on WordPress Multisite](/guides/multisite) before beginning this process. + +Because Bedrock uses `Config::define()` and `config/application.php` instead of traditional `define()` statements in `wp-config.php`, you will not be able to use WP-CLI via Terminus to enable multisite as documented in our standard [multisite configuration guide](/guides/multisite/config/). + + + +Adjust placeholders in code snippets as needed throughout this guide. This includes placeholders such as `` and `` in Terminus commands, in addition to placeholders in brackets `<>` in larger code blocks. + + + +## Set Up WordPress Multisite + +1. Set the site's connection mode to Git: + + ```bash{promptUser: user} + terminus connection:set .dev git + ``` +2. Open the `config/application.php` file in your site's codebase and add the following line anywhere _above_ the `Config::apply();` line: + + ```php + Config::define( 'WP_ALLOW_MULTISITE', true ); + ``` +3. Visit your development site's WordPress admin and navigate to **Tools** > **Network Setup**. + ![Network Setup page](../../../images/wordpress-composer/04-multisite-network-setup.png) +4. Choose **Sub-domains** or **Sub-directories** (depending on your needs), fill in the Network Title and Admin Email, and click **Install**. +5. You will be given instructions to update your `config/application.php` file. Below where you added the `WP_ALLOW_MULTISITE` line, copy and paste the code provided. The `SUBDOMAIN_INSTALL` value will be `true` or `false` depending on the option you chose in the previous step. For example, if you chose subdirectories, your `config/application.php` file should look like this: + + ```php + Config::define( 'MULTISITE', true ); + Config::define( 'SUBDOMAIN_INSTALL', false ); + // Use PANTHEON_HOSTNAME if in a Pantheon environment, otherwise use HTTP_HOST. + Config::define( 'DOMAIN_CURRENT_SITE', defined( 'PANTHEON_HOSTNAME' ) ? PANTHEON_HOSTNAME : $_SERVER['HTTP_HOST'] ); + Config::define( 'PATH_CURRENT_SITE', '/' ); + Config::define( 'SITE_ID_CURRENT_SITE', 1 ); + Config::define( 'BLOG_ID_CURRENT_SITE', 1 ); + ``` +6. Save your changes and commit them to your Git repository. WordPress will prompt you to log back in after you push the changes. +7. Log into your site. When you log back into your WordPress admin dashboard, you will see a new **My Sites** menu item in the top left corner. This is where you can manage your network of sites. You now have a WordPress subdirectory multisite network set up on a WordPress (Composer Managed)-based upstream. + ![My Sites](../../../images/wordpress-composer/04-multisite-my-sites.png) + +## Using Subdomain Multisite on Pantheon + +Pantheon does not support sub-subdomains on the `pantheonsite.io` platform domain. This means that sub-sites on a subdomain multisite will not be accessible by default. See the [Mapping Custom Hostnames](/guides/multisite/config/#map-custom-hostnames-subdomain-configurations-only) panel in the Multisite Configuration guide for how to set up a custom domain for your sub-sites. + +## Multisite Search and Replace with WordPress (Composer Managed) +Currently, the built-in dashboard [WordPress Multisite Search and Replace](/guides/multisite/search-replace/) does not support Composer-based WordPress multisites. To perform a search and replace on a WordPress (Composer Managed) multisite, you will need to use WP-CLI via Terminus manually. For more information, see our [WordPress Multisite Search and Replace](guides/multisite/workflows/#run-wp-cli-search-replace-manually) guide. + +## More Information + +* [WordPress Multisite Configuration](/guides/multisite/config/) +* [WordPress Multisite Search and Replace](/guides/multisite/search-replace/) +* [WordPress Multisite documentation](https://developer.wordpress.org/advanced-administration/multisite/) +* [WordPress Multisite Domain Mapping](https://developer.wordpress.org/advanced-administration/multisite/domain-mapping/) diff --git a/source/content/guides/wordpress-configurations/05-wordpress-cache-plugin.md b/source/content/guides/wordpress-configurations/05-wordpress-cache-plugin.md index 2fdb03c5eb..1d99451338 100644 --- a/source/content/guides/wordpress-configurations/05-wordpress-cache-plugin.md +++ b/source/content/guides/wordpress-configurations/05-wordpress-cache-plugin.md @@ -47,7 +47,7 @@ You can increase the default time to live value to improve the chances that a vi ### Override the default max age -Since the [1.4.0 update in the Pantheon Mu Plugin](/release-notes/2024/04/pantheon-mu-plugin-1-4-0-update), you can override the default `max-age` using a filter. This is useful if you want to set a different max age for specific pages or post types, or if you want to set it to a specific value programmatically. +Since the [1.4.0 update in the Pantheon MU Plugin](/release-notes/2024/04/pantheon-mu-plugin-1-4-0-update), you can override the default `max-age` using a filter. This is useful if you want to set a different max age for specific pages or post types, or if you want to set it to a specific value programmatically. ```php add_filter( 'pantheon_cache_default_max_age', function() { @@ -74,7 +74,7 @@ You can enable maintenance mode for others while working on your site. ## Use Pantheon Cache Functions Programmatically -There are three functions that are useful to developers within the [pantheon-page-cache.php](https://github.com/pantheon-systems/WordPress/blob/default/wp-content/mu-plugins/pantheon-mu-plugin/inc/pantheon-page-cache.php) file that houses the Pantheon Cache plugin code. You can call them from within your own custom code using various WordPress hooks, such as [save_post()](https://developer.wordpress.org/reference/hooks/save_post/). +There are functions that are useful to developers within the [Pantheon MU plugin](https://github.com/pantheon-systems/pantheon-mu-plugin/blob/main/inc/pantheon-page-cache.php). You can call them from within your own custom code using various WordPress hooks, such as [`save_post`](https://developer.wordpress.org/reference/hooks/save_post/). ### flush_site @@ -118,6 +118,8 @@ This function flushes the cache for an individual term or terms which are passed public function clean_term_cache( $term_ids, $taxonomy ) ``` +Additional filters are added and available only when the [Pantheon Advanced Page Cache](https://github.com/pantheon-systems/pantheon-advanced-page-cache/tree/e3b5552b0cb9268d9b696cb200af56cc044920d9?tab=readme-ov-file#adding-custom-keys) plugin is installed and active. + ## Automatically Clear Cache on Archive Pages for Specific Custom Post Type By default, adding a post, page or custom post type, clears the cache for the homepage and associated terms or categories associated with it. To clear cache for a specific page when a specific custom post type is added: @@ -131,16 +133,18 @@ add_action( 'save_post', 'custom_clearcache_archive_page' ); * @return void */ function custom_clearcache_archive_page( $post_id ){ - if(get_post_type() === 'book') { - pantheon_clear_edge_paths(['/books-on-startups-entrepreneurship-and-venture-capital/']); + if ( get_post_type() === 'book' ) { + pantheon_clear_edge_paths( ['/books-on-startups-entrepreneurship-and-venture-capital/'] ); } - if(get_post_type() === 'public-media') { - pantheon_clear_edge_paths(['/archives/media/']); + if( get_post_type() === 'public-media' ) { + pantheon_clear_edge_paths( ['/archives/media/'] ); } } ``` +The `pantheon_clear_edge_paths` function is declared in the PHP runtime and is only available on the Pantheon platform. + ## More Resources - [Testing Global CDN Caching](/guides/global-cdn/test-global-cdn-caching) diff --git a/source/content/guides/wordpress-developer/02-wordpress-best-practices.md b/source/content/guides/wordpress-developer/02-wordpress-best-practices.md index 9f2603924a..c64ea3dd49 100644 --- a/source/content/guides/wordpress-developer/02-wordpress-best-practices.md +++ b/source/content/guides/wordpress-developer/02-wordpress-best-practices.md @@ -10,7 +10,7 @@ audience: [development] product: [--] integration: [--] tags: [workflow, security, composer] -reviewed: "2022-05-16" +reviewed: "2024-08-12" showtoc: true permalink: docs/guides/wordpress-developer/wordpress-best-practices --- @@ -66,7 +66,9 @@ There are many plugins and themes in WordPress that require license keys. It is - Follow our [Frontend Performance](/guides/frontend-performance) guide to tune your WordPress site. -## Disable Anonymous Access to WordPress Rest API +## Disable Anonymous Access to the WordPress REST API + +### Option 1: Block the entire WordPress REST API The WordPress REST API is enabled for all users by default. You can disable the WordPress REST API for anonymous requests to improve security and avoid exposing admin users. This action improves site safety and reduces unexpected errors that can result in compromised WordPress core functionalities. @@ -91,6 +93,30 @@ add_filter( 'rest_authentication_errors', function( $result ) { }); ``` +### Option 2: Block only the `/users` WordPress REST endpoint + +If blocking the entire REST API is not feasible for your site, you can choose a more selective approach. The WordPress REST API exposes the complete users list at the `/wp-json/wp/v2/users` endpoint. This is by design -- the `/users` endpoint contains data that is public elsewhere on your site and availalbe in other public places in WordPress, notably the HTML output and RSS feeds including name, avatar, etc. These endpoints are public so that the data to view and render content from elsewhere in the REST API is available. For example, since a post links to the author user, making user information easily accessible makes it simpler to access from API tools and integrations. + +However, in many cases, exposing the `/user` endpoint is seen as a vulnerability in penetration testing. Additionally, if your site uses email addresses as usernames, it could be exposing every email address of a user that has a published post on the site. You can disable access to `/wp-json/wp/v2/users` with the following filter: + +```php +function restrict_user_endpoints( $access ) { + if ( ! is_user_logged_in() || ! current_user_can( 'list_users' ) ) { + $requested_route = $_SERVER['REQUEST_URI']; + if ( strpos( $requested_route, '/wp/v2/users' ) !== false ) { + return new WP_Error( 'rest_forbidden', 'Sorry, you are not allowed to do that.', array( 'status' => 403 ) ); + } + } + + return $access; +} +add_filter( 'rest_authentication_errors', 'restrict_user_endpoints' ); +``` + +This filter checks if a user is logged in and if they have access to the `list_users` capability in the WordPress admin. If neither is true, it returns a REST error and blocks access to `/users` and descendent endpoints (e.g. `/wp-json/wp/v2/users/1` for the user with an ID of 1 in the database) while still allowing access to those endpoints for logged-in users. + +For more information about WordPress user roles and capabilities, refer to the [Roles and Capabilities documentation](https://wordpress.org/documentation/article/roles-and-capabilities/) on WordPress.org. + ## Security Headers Pantheon's Nginx configuration [cannot be modified](/guides/platform-considerations/platform-site-info#htaccess) to add security headers, and many solutions (including plugins) written about security headers for WordPress involve modifying the `.htaccess` file for Apache-based platforms. diff --git a/source/content/guides/wordpress-developer/05-wordpress-login-attacks.md b/source/content/guides/wordpress-developer/05-wordpress-login-attacks.md index df19f2e3b1..90723a4090 100644 --- a/source/content/guides/wordpress-developer/05-wordpress-login-attacks.md +++ b/source/content/guides/wordpress-developer/05-wordpress-login-attacks.md @@ -67,11 +67,14 @@ SSO often includes or requires [MFA](#add-multi-factor-authentication-mfa) to he 1. Optional. Use plugins, such as [WP SAML Auth](https://wordpress.org/plugins/wp-saml-auth/) or [MiniOrange](https://plugins.miniorange.com/wordpress), to simplify the SSO integration with your IdP. +### Block the `/users` REST Endpoint for Unauthenticated Users + +The WordPress REST API endpoint at `/wp-json/wp/v2/users` shows a full list of all usernames on a WordPress site and associated metadata for users who have at least one published post in a public post type. While this information is available elsewhere, it can occasionally be prudent to disallow access to this list of users to unauthenticated users. Note: this should not _replace_ any of the other methods of avoiding attacks described above. Good site security should involve more than simply hiding the list of users on a site (especially when that information is already available, for example, in the site's HTML markup). + +Refer to the [WordPress Best Practices](/guides/wordpress-developer/wordpress-best-practices#option-2-block-only-the-users-wordpress-rest-endpoint) doc for a code snippet that you can use to block anonymous access to `/users`. + ## More Resources - [Using WP SAML Auth with Google Apps](/guides/wordpress-google-sso/) - [WordPress Security](/guides/wordpress-pantheon/wp-security) - [Secure Development on Pantheon](/guides/secure-development) - - - diff --git a/source/content/guides/wordpress-developer/10-wordpress-solr.md b/source/content/guides/wordpress-developer/10-wordpress-solr.md index 532f91d07e..5e989a4fa8 100644 --- a/source/content/guides/wordpress-developer/10-wordpress-solr.md +++ b/source/content/guides/wordpress-developer/10-wordpress-solr.md @@ -10,17 +10,17 @@ audience: [development] product: [search] integration: [plugins] tags: [solr, plugins] -contributors: [cityofoaksdesign] +contributors: [cityofoaksdesign, ccharlton] showtoc: true permalink: docs/guides/wordpress-developer/wordpress-solr -reviewed: "2022-12-13" +reviewed: "2024-09-09" --- This section provides information on how to use Apache Solr with your WordPress Pantheon site. [Apache Solr](/solr) is a system for indexing and searching site content. All plans except for Basic can use Pantheon Solr. - +Currently, Pantheon provides Apache Solr v3.6 for WordPress search for all plans except the Basic plan. diff --git a/source/content/guides/wordpress-pantheon/04-wordpress-launch-check.md b/source/content/guides/wordpress-pantheon/04-wordpress-launch-check.md index fca6740748..74cf491bb1 100644 --- a/source/content/guides/wordpress-pantheon/04-wordpress-launch-check.md +++ b/source/content/guides/wordpress-pantheon/04-wordpress-launch-check.md @@ -30,45 +30,6 @@ This mechanism does not actually perform requests on your site, and in doing so WP Launch Check is a site audit extension for WP-CLI designed for Pantheon customers, although it is fully usable outside of Pantheon. -## WPScan (Recommended) - -WP Launch Check uses the [WPScan API](https://wpscan.com/api) to check for outdated or vulnerable plugins. The service sends alerts when your plugins need to be updated. Follow the steps below to use this service. - -1. Obtain an [API token](https://wpscan.com/wordpress-security-scanner) from the WPScan website by creating an account. - -1. Add the token to your site's `wp-config.php` file using the following PHP code: - - ```php:title=wp-config.php - define( 'WPSCAN_API_TOKEN', '$your_api_token' ); - ``` -1. Define the environment. - - You'll also need to define which environment you want WPScan to run on using the `PANTHEON_WPSCAN_ENVIRONMENTS` constant. This constant is required to use the WPScan functionality, and allows you to decide whether or not scans are done on multiple environments, or just one. - - To scan one environment: - - ```php:title=wp-config.php - define( 'PANTHEON_WPSCAN_ENVIRONMENTS', 'live' ); - ``` - - To scan multiple environments: - - ```php:title=wp-config.php - define( 'PANTHEON_WPSCAN_ENVIRONMENTS', ['dev', 'test', 'live'] ); - ``` - - To scan all environments: - - ```php:title=wp-config.php - define( 'PANTHEON_WPSCAN_ENVIRONMENTS', '*' ); - ``` - - - -Scanning multiple or all environments exhausts your daily API request quota faster. - - - ## Run Launch Check Manually You can manually perform a site audit with WP Launch Check from the command line using [Terminus](/terminus). @@ -120,10 +81,6 @@ The `wp_options` table stores several types of data for your site, including: If your website is running slow and you receive the following message in the database stats: `consider autoloading only necessary options`, review [Optimize Your wp-options Table and Autoloaded Data](/optimize-wp-options-table-autoloaded-data). -### Probable Exploits - -This check will display a list of exploited patterns in code, the file name that has the exploit, line number, and match. - ### Object Cache This tells you if Object Caching and Redis are enabled. @@ -139,11 +96,11 @@ Performance and Elite WordPress site(s) that are currently running WP Redis are ### Plugins -This check lists all your enabled plugins and alerts you when they need to be updated. It also checks for any vulnerabilities. +This check lists all your enabled plugins and alerts you when they need to be updated. - **Green:** All of your plugins are up-to-date - **Yellow:** Highlighted plugins need to be updated -- **Red:** Displays all vulnerabilities and unsupported plugins +- **Red:** Displays unsupported plugins #### Unsupported Plugins diff --git a/source/content/horizontal-scalability.md b/source/content/horizontal-scalability.md index c037e4183f..8a2e27a05d 100644 --- a/source/content/horizontal-scalability.md +++ b/source/content/horizontal-scalability.md @@ -60,7 +60,7 @@ Elite sites have the added benefit of managed resource provisioning, both for an When an Elite site encounters massive sudden or unexpected increases in traffic, the Pantheon platform alerts Pantheon Support, who ensure that the most appropriate level of platform resources are provisioned for the site to handle the traffic spike. -For an anticipated increase in traffic, open a [Support ticket](/guides/support/contact-support/#ticket-support) with the following information: +For an anticipated increase in traffic, open a [Support ticket](/guides/support/contact-support/#general-support-ticket) with the following information: - **How much extra traffic?** diff --git a/source/content/local-dns-cache.md b/source/content/local-dns-cache.md new file mode 100644 index 0000000000..67531686cd --- /dev/null +++ b/source/content/local-dns-cache.md @@ -0,0 +1,124 @@ +--- +title: Debug Local DNS Cache +description: Recommendations for addressing SSH / Git authentication failures due to stale local DNS. +tags: [cdn] +reviewed: "2024-09-13" +contenttype: [doc] +innav: [true] +categories: [cache] +--- +DNS caching issues are critical for Pantheon developers to understand and manage. Stale DNS entries can lead to SSH/Git authentication failures, potentially disrupting your workflow and deployments. This guide provides solutions to mitigate these issues, ensuring smooth operations across your Pantheon sites. + +## Issue Symptoms +Pantheon application containers are sometimes migrated during routine platform maintenance. Following an application container migration, it is possible for Local DNS cache to cause SSH / Git authentication failures resulting in errors like `Permission denied (publickey)` or the following error, as the result of an operation like `git clone`: + +``` +fatal: Could not read from remote repository. + +Please make sure you have the correct access rights +and the repository exists. +``` + +Manually retrying will resolve the issue, which is fine enough in the context of a single site but not so easy to handle across hundreds of sites. Those with large site portfolios using continuous integration and automated deployments might see this issue surface as a large spike in failed deployments across many sites. + +## Before You Begin +### Use Cases +The scripts below provide a flexible and automated approach to managing local DNS cache issues when working with Pantheon sites. By flushing stale DNS entries and retrying failed commands, you can ensure smoother SSH / Git operations and reduce the likelihood of deployment failures due to stale DNS entries. + +These scripts are particularly valuable for: + +- Large-scale deployments managing multiple Pantheon sites +- CI/CD pipelines where automated Git operations are frequent +- Developers experiencing intermittent SSH/Git authentication failures + +### Prerequisites +Before implementing these solutions, ensure you have: + +- Terminus [installed](/terminus/install#install-terminus) and [authenticated](/terminus/install#authenticate) +- Appropriate permissions to execute system commands (for DNS cache flushing) +- Git installed and configured for your Pantheon sites + +### Best Practices +* Implement these scripts in your local development environment to catch issues early +* Use Option 2 to minimize unnecessary cache flushes +* Regularly update your local Git configurations to match Pantheon's latest recommendations + + +## Option 1: Eliminate Local DNS Caching +The first option is to assume the DNS cache is always stale and to flush caches prior to any interaction with a Pantheon codeserver. In the example below, `flush_dns_cache()` is called prior to executing any git command. + +### Considerations +**Pros:** + +- Ensures fresh DNS resolution for every Git operation +- Simplifies troubleshooting by eliminating DNS caching as a variable + +**Cons:** +- May introduce slight performance overhead due to frequent cache flushing +- Requires elevated permissions to flush DNS cache on some systems + +### Usage +1. Click the download file button below to download `flush_dns_and_clone.sh` +1. Replace the last line of the `flush_dns_and_clone.sh` file with the [clone command from your site dashboard](/guides/git/git-config#clone-your-site-codebase). +1. Execute the script as part of your deployment workflows by running: + ```bash{promptUser: user} + ./flush_dns_and_clone.sh + ``` +This script will flush the DNS cache based on your operating system and then proceed with the git clone command. + + + + +GITHUB-EMBED https://github.com/pantheon-systems/documentation/blob/main/source/scripts/flush_dns_and_clone.sh.txt bash GITHUB-EMBED + + +## Option 2: Conditionally Flush Stale Local DNS and Retry Git Command Failures +In the second option, any git clone or push command error results in calling the `check_dns_cache()` function to flush stale local DNS entries, and then the respective git command is retried. See [below](#detailed-function-explanations) for a more detailed explanation of the functions used in the script. + +### Considerations + +**Pros:** + +- More efficient than Option 1, as it only flushes DNS cache when necessary +- Automatically retries failed Git commands, reducing manual intervention + +**Cons:** + +- Slightly more complex implementation compared to Option 1 +- Requires setting up environment variables (`SITE_ID`, `ENV_ID`, `BRANCH`) +- May increase execution time for Git operations due to potential retries +- Depends on external commands (dig, terminus) which need to be available in the environment + +### Usage +1. Click the download file button below to download `conditional_flush_and_retry.sh` +1. Create environment variables within your CI pipeline for `SITE_ID`, `ENV_ID`, and `BRANCH` +1. Execute the script as part of your deployment workflows by running: + ```bash{promptUser: user} + ./conditional_flush_and_retry.sh + ``` + + + +GITHUB-EMBED https://github.com/pantheon-systems/documentation/blob/main/source/scripts/conditional_flush_and_retry.sh.txt bash GITHUB-EMBED + +#### Detailed Function Explanations + +* `flush_dns_cache()`: This function detects the operating system and executes the appropriate DNS cache flushing command. + +* `check_dns_cache()`: This function compares the cached IP with the actual IP of the Git host. If they differ, it triggers a DNS cache flush. + +* `push_code()`: This function encapsulates Git clone and push operations with retry logic, calling `check_dns_cache()` on failures. + +#### Large Portfolios +For large site portfolios: + +* Consider implementing a cooldown period between retries to prevent overwhelming Pantheon's services +* Monitor the frequency of DNS cache flushes and adjust the retry logic if necessary + + +## Troubleshooting +### Permission denied when flushing DNS cache +Ensure your script has sudo privileges or run with elevated permissions. + +### Git commands still failing after DNS flush +Verify your [SSH keys](/ssh-keys) are correctly set up in your Pantheon account. diff --git a/source/content/monthly-maintenance.md b/source/content/monthly-maintenance.md new file mode 100644 index 0000000000..f431d7fe46 --- /dev/null +++ b/source/content/monthly-maintenance.md @@ -0,0 +1,24 @@ +--- +title: Monthly Platform Maintenance +description: Understand Pantheon's monthly maintenance schedule and policy. +contributors: [rachelwhitton] +contenttype: [doc] +reviewed: 2024-08-08 +--- + +Pantheon uses monthly maintenance windows to perform essential updates and improvements to the platform’s software and infrastructure. This hour-long window will not impact site visitors or site availability. Access to the Pantheon Dashboard and workflows may experience temporary interruptions. + +## Schedule +The following schedule is used to perform monthly platform maintenance: + +* **Frequency**: Monthly +* **Day**: Second Tuesday of each month +* **Time**: 6 PM to 7 PM Pacific Time +* **Duration**: 1 hour + +### Communication and Support +An update on the [Status page](https://status.pantheon.io/) will be posted on the first Thursday of each month to alert you about upcoming maintenance the following Tuesday. At the same time, the Dashboard will feature a banner about the upcoming maintenance. If no maintenance is required for a given month, no status page will be posted. + +When necessary, we will leverage the same window to perform maintenance that may impact live sites. In these cases, we will notify you at least 30 days before the maintenance window. + +If you have any questions during scheduled maintenance windows, please [contact support](/guides/support/contact-support/). diff --git a/source/content/partials/dashboard-site-creation-1.md b/source/content/partials/dashboard-site-creation-1.md index 6c41cd8c10..5878ee9b72 100644 --- a/source/content/partials/dashboard-site-creation-1.md +++ b/source/content/partials/dashboard-site-creation-1.md @@ -18,7 +18,7 @@ reviewed: "" If you select Drupal, you will have the option to select the Drupal version you want to use. - ![Select Drupal version](../../images/create-new-site-cms-drupal.png) + ![Select Drupal version](../../images/create-new-site-cms-drupal-11crop.png) 1. Enter the following information and click **Continue**: - Sitename @@ -42,6 +42,3 @@ reviewed: "" ![Site creation completed](../../images/create-site-done.png) You've now created the core portion of your Dev environment; now you have to install the CMS. - - - diff --git a/source/content/pivotal-tracker.md b/source/content/pivotal-tracker.md index a2ebe59eb9..6e4d1786bd 100644 --- a/source/content/pivotal-tracker.md +++ b/source/content/pivotal-tracker.md @@ -28,10 +28,10 @@ Be sure to: curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar && php installer.phar install ``` -- Install the [Terminus Secrets Plugin](https://github.com/pantheon-systems/terminus-secrets-plugin): +- Install the [Terminus Secrets Manager Plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin): ```bash{promptUser: user} - curl https://github.com/pantheon-systems/terminus-secrets-plugin/archive/1.x.tar.gz -L | tar -C ~/.terminus/plugins -xvz + terminus plugin:install terminus-secrets-manager-plugin ``` ## Create a Machine User in Pivotal Tracker @@ -52,45 +52,11 @@ As a best practice, start by creating a new machine user in Tracker. This user i ## Prepare your site: Securely Store User Credentials on Pantheon -Next, we need to provide Pantheon with the credentials for our new machine user in Pivotal Tracker. We'll securely store these values in the [private path](/guides/secure-development/private-paths#private-path-for-files) of Pantheon's filesystem. -We use the filesystem private path in this section because we don't want to track sensitive data like passwords in the codebase with git. - -1. First, let's check for existing secrets using Terminus (replace ``): - - ```bash{promptUser: user} - SITE= - terminus secrets:list $SITE.dev - ``` - - If no existing keys are found, run the following to create a new `secrets.json` file and upload it to Pantheon: - - ```bash{outputLines: 2} - echo '{}' > secrets.json - `terminus connection:info $SITE.dev --field=sftp_command` - ``` - - If the `files/private` directory doesn't exist, create it: - - ```bash{promptUser: user} - mkdir files/private - ``` - - Put the secrets file into the `private` directory: - - ```bash{outputLines: 1-3} - sftp> cd files/private - sftp> put secrets.json - sftp> bye - rm secrets.json - ``` - - Otherwise, continue to the next step. - -2. Use Terminus to write your Pivotal Tracker URL value in the private `secrets.json` file (replace ``): +2. Use Terminus to store your Pivotal Tracker URL value in Pantheon Secrets (replace ``): ```bash{promptUser: user} - terminus secrets:set $SITE.dev tracker_token + terminus secrets:site:set $SITE.dev tracker_token ``` diff --git a/source/content/plugins-known-issues.md b/source/content/plugins-known-issues.md index 82cbf99c50..3aa566fe18 100644 --- a/source/content/plugins-known-issues.md +++ b/source/content/plugins-known-issues.md @@ -2,7 +2,7 @@ title: WordPress Plugins and Themes with Known Issues description: A list of WordPress plugins, themes, and functions that are not supported and/or require workarounds. tags: [plugins, themes, code] -contributors: [aleksandrkorolyov, jocastaneda, carl-alberto, jkudish] +contributors: [aleksandrkorolyov, jocastaneda, carl-alberto, jkudish, miriamgoldman] contenttype: [doc] showtoc: true innav: [true] @@ -11,7 +11,7 @@ cms: [wordpress] audience: [development] product: [--] integration: [--] -reviewed: "2024-07-12" +reviewed: "2024-09-06" --- This page lists WordPress plugins, themes, and functions that may not function as expected or are currently problematic on the Pantheon platform. This is not a comprehensive list (see [other issues](#other-issues)). We continually update it as problems are reported and/or solved. If you are aware of any modules or plugins that do not work as expected, please [contact support](/guides/support/contact-support/). @@ -786,6 +786,16 @@ ___ ___ +## PhastPress + + + +**Issue:** [PhastPress](https://wordpress.org/plugins/phastpress/) is a site optimization plugin that creates an SQLite database on Pantheon's filesystem. This is problematic as it can vastly increase the amount of filesystem storage your site consumes and run up against resource limits. This plugin is not recommended on Pantheon. + +**Solution**: Consider other optimization plugins, such as [Autoptimize](https://wordpress.org/plugins/autoptimize/) and [Flying Scripts](https://wordpress.org/plugins/flying-scripts/). + +___ + ## Redirection @@ -1319,6 +1329,30 @@ You will need to make this change every time the plugin is updated. ___ +## WP Cerber Security, Antispam & Malware Scan + + + +WP Cerber is a premium security plugin (with a free version available) that is only available through the [WP Cerber website](https://wpcerber.com/). Previously, it was available on the WordPress plugin repository, but it was [removed](https://wordpress.org/plugins/wp-cerber/) due to a violation of the repository's guidelines. + +**Issue:** The WP Cerber Anti-Spam Engine makes pages uncacheable on the Pantheon Global CDN. WP Cerber creates a unique, cache-busting cookie for each visitor, which prevents users from seeing cached pages. + +**Solution:** Disable the Anti-Spam Engine features in the WP Cerber plugin settings. + +1. Navigate to the **WP Cerber** menu in the WordPress dashboard and select **Anti-Spam**. + +1. Disable the following options: + - **Protect registration form** + - **Protect comment form** + - **Protect other forms** + + ![WP Cerber Anti-Spam Engine settings](../images/plugins-known-issues/wp-cerber-anti-spam-settings.png) + +1. In your Pantheon dashboard, clear the cache for the environment. + +Your pages should now be cacheable on the Pantheon Global CDN. +___ + ## WP Reset diff --git a/source/content/relaunch.md b/source/content/relaunch.md index 38ee8adef5..f4f642ad49 100644 --- a/source/content/relaunch.md +++ b/source/content/relaunch.md @@ -2,7 +2,7 @@ title: Relaunch Existing Pantheon Site description: Take a new site live by moving custom domains from one Site Dashboard to another, with minimal HTTPS interruptions. tags: [dns, https, launch, migrate] -reviewed: "2020-09-08" +reviewed: "2024-09-03" contenttype: [doc] innav: [true] categories: [launch] @@ -92,6 +92,10 @@ The new Site Plan will be billed immediately. ## Relaunch Procedure + + + + For a fast, smooth relaunch, consider having two browser tabs open, one with the old Site Dashboard, and one with the new. 1. In the new Site Dashboard, [upgrade the site from free to a paid plan](/guides/legacy-dashboard/site-plan#purchase-a-new-plan). @@ -124,6 +128,62 @@ For a fast, smooth relaunch, consider having two browser tabs open, one with the 1. In the old Site Dashboard, [remove the existing card as a payment method for the site](/guides/legacy-dashboard/site-billing/#do-not-bill-this-site-to-a-card). If you're a contract customer, you can skip this step. + + + + + +For a fast, smooth relaunch, consider having two browser tabs open, one with the old Site Dashboard, and one with the new. + +1. In the new Site Dashboard, [upgrade the site from free to a paid plan](/guides/legacy-dashboard/site-plan#purchase-a-new-plan). + +1. In the old Site Dashboard, remove the custom domain affected by the relaunch: + + ** Live** > ** Domains / HTTPS** > **Details** > **Remove Domain** + +1. In the new Site Dashboard, connect the custom domain affected by the relaunch and **skip** ownership verification. + + ** Live** > ** Domains / HTTPS** > **Connect Domain** + + + Do *not* update DNS yet. The Site Dashboard instructs you to configure DNS after connecting the domain, however for this relaunch procedure you should not change record values until instructed in step 7 below. + + Once you make this change, traffic will be routed to the new site. However, if you do not complete the rest of the steps as outlined here, you may run into cases where the new site has an invalid HTTPS certificate. + + + +1. In the Live environment tab of the Site Dashboard for the old site, click **Clear Caches**. + +1. Repeat on the Live environment of the new site. + +1. Wait for HTTPS to provision for the newly connected domains: + + ** Live** > ** Domains / HTTPS** > **Details** + + This process typically takes about an hour. + +1. From the DNS hosting service (not Pantheon), replace values in DNS records pointed to Pantheon with new values provided in the Site Dashboard. + + + +1. Wait for TTL to expire. + +1. Test and confirm that the new site is accessible via the custom domain over HTTPS (e.g., `https://www.example.com/`). + +1. Repeat steps 2-6 above for each affected domain. Note `www.example.com` and `example.com` are different domains. + +1. In the new Site Dashboard, [standardize traffic for the primary domain](/guides/domains). + +1. In the old Site Dashboard, [downgrade the site from a paid plan to Sandbox](/guides/legacy-dashboard/site-plan/#cancel-current-plan). + +1. In the old Site Dashboard, [remove the existing card as a payment method for the site](/guides/legacy-dashboard/site-billing/#do-not-bill-this-site-to-a-card). If you're a contract customer, you can skip this step. + + + + + + + ## Frequently Asked Questions ### Why is this process needed? diff --git a/source/content/sftp.md b/source/content/sftp.md deleted file mode 100644 index 71988e4507..0000000000 --- a/source/content/sftp.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: On-Server Development -description: Develop on Pantheon directly via SFTP. -contributors: [scottmassey] -permalink: docs/:basename -tags: [files, sftp, code] -searchboost: 50 -layout: video -type: video -contenttype: [doc] -innav: [true] -categories: [sftp] -cms: [--] -audience: [development] -product: [--] -integration: [--] ---- - - - -Pantheon allows you to quickly and easily write code or add modules and plugins directly on the platform using on-server development. - -All the code on your Pantheon site is stored in a repository, which is a remote canonical storehouse of code along with its history of changes. - -You make changes to your code in 1 of 2 ways. You can use Git, the repository’s native language, via the command line. Or as we’re discussing today, on-server development with SFTP. - -SFTP mode works by basically making your Dev environment temporarily writable, and aware of any changes you make. These changes are eventually pulled to Test and Live via version control. - -Let’s begin by switching to SFTP mode. Then use the connection settings in the dashboard with Transmit, my SFTP client. And add the host name or server, and then my username. For password, I’m going to use my SSH Key, but you can also use your dashboard password. And then finally, I’m going to add the port number. - -When I connect, I should be able to see my Dev environment code. My SFTP client will upload whatever I save, so I can make changes, and see and test them as I go. If I look at the dashboard, I can see that it’s aware that a change has been made. - -So let’s look at the site. I’ll see the change in the date formatting that I just made on the homepage. I like the way that looks, so I’m going to commit it to the repo with a relevant message. It’s really important and a best practice to make regular commits. - -While I’m doing on-server development, I can get some other work done, such as updating a module or plugin to the dashboard user interface. Since this plugin update is basically just a code change, of course I’m going to go back to dashboard and commit it. - -For those of us who like to use command line tools, if I have [Terminus](/terminus) installed, I can use Drush or WP-CLI to download modules to the Dev environment. In this case, I’ll run the command that downloads and activates the WordPress plugin for [Optimizely](https://wordpress.org/plugins/optimizely/). As with the first 2 examples, nothing lasts forever unless it’s stored in the Git repository. So I’ll add a message and commit it. - -While I’m doing on-server development, the Dev environment is writable, but it’s also blocking anyone from pushing to it via Git, so I switch it back to Git mode on the dashboard. - -Whether you’re a Git user or an FTP user, on-server Development can be a pretty handy tool. Give it a shot and see if you can integrate it into your workflow. Learn more about [developing on Pantheon directly with SFTP mode](/guides/sftp). diff --git a/source/content/ssh-keys.md b/source/content/ssh-keys.md index fee503a270..a2af2479f2 100644 --- a/source/content/ssh-keys.md +++ b/source/content/ssh-keys.md @@ -44,7 +44,7 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519` 1. Open your terminal and enter the following command to generate a key: ```bash{promptUser: user} - ssh-keygen -t rsa + ssh-keygen -t rsa -m PEM ``` Do not edit the default location of `~/.ssh/id_rsa` unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key. @@ -79,7 +79,7 @@ Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support `ed25519` 1. Open your terminal and enter the following command to generate a key. This command works for Windows 10: ```bash{promptUser: winshell} - ssh-keygen -t rsa + ssh-keygen -t rsa -m PEM ``` Do not edit the default location of `~/.ssh/id_rsa` unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key. diff --git a/source/content/supported-drupal.md b/source/content/supported-drupal.md index aec40d2849..7c498c46f9 100644 --- a/source/content/supported-drupal.md +++ b/source/content/supported-drupal.md @@ -10,18 +10,32 @@ cms: [drupal] audience: [development] product: [--] integration: [--] +reviewed: "2024-10-04" --- The following table indicates availability of the specified Drupal version, as well as our usage recommendations and our support scope. | Drupal Version | Available | Recommended | Supported | | ----------- | :---------: | :---------: | :---------: | +| 11 | ✔ | ✔ | ✔ | 10 | ✔ | ✔ | ✔ | -| 9 | ✔ | ✔ | ✔ | -| 8 | ✔ | ❌ | ✔ | +| 9 |✔ | ❌ | ✔ | +| 8 |✔ | ❌ | ✔ | | 7 | ✔ | ❌ | ✔ | | 6 | ❌ | ❌ | ❌ | +## Drupal 10 and 11 on Pantheon +Refer to [Create a New CMS Site](/add-site-dashboard) for how to create a new Drupal 10 or 11 site from the Pantheon dashboard. + +If you already have a Drupal 10 site on Pantheon, you can upgrade your existing site to [Drupal 11 via Composer](https://www.drupal.org/docs/upgrading-drupal/upgrading-from-drupal-8-or-later/how-to-upgrade-from-drupal-10-to-drupal-11). + +## Drupal 8 and 9 on Pantheon +Drupal 8 and 9 are not available as an option during site creation in the Pantheon dashboard, however they can still be created on the platform using [Terminus](/terminus). For example: + +```bash{promptUser: user} +terminus site:create