From 6a42518c9511ade5af96aeeb014e0a305a001ca0 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 08:39:08 -0700 Subject: [PATCH 01/13] Add Cloud docset texts --- docs/.vuepress/config.js | 3 +- docs/.vuepress/sets/craft-cloud.js | 67 +++++ .../theme/components/DocSetPanel.vue | 12 - docs/cloud/README.md | 1 + docs/cloud/assets.md | 142 ++++++++++ docs/cloud/billing.md | 57 ++++ docs/cloud/builds.md | 141 ++++++++++ docs/cloud/clients.md | 22 ++ docs/cloud/compatibility.md | 79 ++++++ docs/cloud/config.md | 96 +++++++ docs/cloud/databases.md | 171 ++++++++++++ docs/cloud/deployment.md | 38 +++ docs/cloud/domains.md | 127 +++++++++ docs/cloud/environments.md | 97 +++++++ docs/cloud/extension.md | 57 ++++ docs/cloud/faq.md | 170 ++++++++++++ docs/cloud/getting-started.md | 123 +++++++++ docs/cloud/launch-checklist.md | 32 +++ docs/cloud/local-dev.md | 44 ++++ docs/cloud/migrating.md | 97 +++++++ docs/cloud/plugin-development.md | 98 +++++++ docs/cloud/private-packages.md | 22 ++ docs/cloud/project-management.md | 39 +++ docs/cloud/quotas.md | 81 ++++++ docs/cloud/regions.md | 34 +++ docs/cloud/static-caching.md | 246 ++++++++++++++++++ docs/cloud/troubleshooting.md | 40 +++ 27 files changed, 2123 insertions(+), 13 deletions(-) create mode 100644 docs/.vuepress/sets/craft-cloud.js create mode 100644 docs/cloud/README.md create mode 100644 docs/cloud/assets.md create mode 100644 docs/cloud/billing.md create mode 100644 docs/cloud/builds.md create mode 100644 docs/cloud/clients.md create mode 100644 docs/cloud/compatibility.md create mode 100644 docs/cloud/config.md create mode 100644 docs/cloud/databases.md create mode 100644 docs/cloud/deployment.md create mode 100644 docs/cloud/domains.md create mode 100644 docs/cloud/environments.md create mode 100644 docs/cloud/extension.md create mode 100644 docs/cloud/faq.md create mode 100644 docs/cloud/getting-started.md create mode 100644 docs/cloud/launch-checklist.md create mode 100644 docs/cloud/local-dev.md create mode 100644 docs/cloud/migrating.md create mode 100644 docs/cloud/plugin-development.md create mode 100644 docs/cloud/private-packages.md create mode 100644 docs/cloud/project-management.md create mode 100644 docs/cloud/quotas.md create mode 100644 docs/cloud/regions.md create mode 100644 docs/cloud/static-caching.md create mode 100644 docs/cloud/troubleshooting.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 2a58c5cb3..5c25b573c 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -40,6 +40,7 @@ module.exports = { docSets: [ require("./sets/craft-cms"), require("./sets/craft-commerce"), + require("./sets/craft-cloud"), require("./sets/craft-nitro"), require("./sets/getting-started-tutorial") ], @@ -53,7 +54,7 @@ module.exports = { prevLinks: true, searchMaxSuggestions: 10, nav: [ - { text: "Knowlege Base", link: "https://craftcms.com/knowledge-base" } + { text: "Knowledge Base", link: "https://craftcms.com/knowledge-base" } ], codeLanguages: { twig: "Twig", diff --git a/docs/.vuepress/sets/craft-cloud.js b/docs/.vuepress/sets/craft-cloud.js new file mode 100644 index 000000000..1a3d4b625 --- /dev/null +++ b/docs/.vuepress/sets/craft-cloud.js @@ -0,0 +1,67 @@ +module.exports = { + title: "Craft Cloud", + handle: "cloud", + icon: "/docs/icons/icon-cloud.svg", + baseDir: "cloud", + abandoned: false, + searchPlaceholder: "Search Cloud docs (Press “/” to focus)", + primarySet: true, + sidebar: { + "/": [ + { + title: "Introduction", + collapsable: false, + children: [ + "", + "getting-started", + "extension", + "config", + ], + }, + { + title: "Workflow", + collapsable: false, + children: [ + "deployment", + "environments", + "builds", + "databases", + "assets", + "local-dev", + "launch-checklist", + ], + }, + { + title: "Platform Info", + collapsable: false, + children: [ + "compatibility", + "static-caching", + "quotas", + "regions", + "domains", + "plugin-development", + ], + }, + { + title: "Collaboration", + collapsable: false, + children: [ + "project-management", + "billing", + "clients", + "migrating", + "private-packages", + ], + }, + { + title: "Help", + collapsable: false, + children: [ + "faq", + "troubleshooting", + ], + }, + ], + }, +}; diff --git a/docs/.vuepress/theme/components/DocSetPanel.vue b/docs/.vuepress/theme/components/DocSetPanel.vue index a8bebb7e1..42127ce7b 100644 --- a/docs/.vuepress/theme/components/DocSetPanel.vue +++ b/docs/.vuepress/theme/components/DocSetPanel.vue @@ -30,18 +30,6 @@ {{ set.setTitle ? set.setTitle : set.title }} - - - -
  • - - - - - - Craft Cloud - -
    • diff --git a/docs/cloud/README.md b/docs/cloud/README.md new file mode 100644 index 000000000..bd042ce61 --- /dev/null +++ b/docs/cloud/README.md @@ -0,0 +1 @@ +# Welcome to Craft Cloud diff --git a/docs/cloud/assets.md b/docs/cloud/assets.md new file mode 100644 index 000000000..06ec2ab11 --- /dev/null +++ b/docs/cloud/assets.md @@ -0,0 +1,142 @@ +# Assets + +Each of the environments in your Craft Cloud projects come with a generous [storage quota](/knowledge-base/cloud-quotas). + +To take advantage of that storage (and other features, like the built-in CDN and [image transform](#transforms) service), you must use the [Cloud extension](/knowledge-base/cloud-extension)’s built-in filesystem type. + +## New Filesystems + +New projects can start using it right away—new filesystems don’t require any special handling. You can [create a new filesystem and volume](/docs/5.x/reference/element-types/assets.html) the same way you would with any other filesystem type. Cloud filesystems do not require any credentials—they’re provided automatically by Cloud’s runtime. + +When you are ready to stage or launch the project, you can [upload your local asset library](#uploading-to-a-bucket) to the equivalent subpath in the target Cloud environment’s storage bucket. Live assets can be referenced from a [local development environment](#local-development), in read-only mode. + +## Converting a Filesystem + +Existing projects may require some additional work to ensure their filesystems are migrated properly. This process will differ based on the filesystem’s *current* type—and if multiple filesystem types are represented in your configuration, you may need to follow different steps for each one. + +::: warning +Filesystems’ base paths cannot overlap! Even if you only need a single filesystem on Cloud, we recommend using the Cloud filesystem’s **Subpath** option to make room at the root of your volume for other filesystems, later. +::: + +Changes to your filesystems + volumes will be applied via [Project Config](/docs/5.x/system/project-config.html), the next time you deploy your environment. + +### Local + +Local filesystems are the most straightforward to migrate. Take note of the current filesystem’s **Base Path** setting, as we’ll copy this into the new Cloud filesystem, to take advantage of the files already on your development environment’s disk. + +From your Local filesystem’s settings screen, change the **Filesystem Type** to **Cloud**. Copy the old **Base Path** and **Base URL** settings into the corresponding **Base Path** and **Base URL** fields, within the **Local Filesystem** section. + +The **Subpath** setting is appended to the **Base Path** and **URL** values, automatically. + +::: tip +You are welcome to relocate the on-disk files at this time, provided you update the **Base URL** and **Base Path** settings to match. It can be useful to keep all your Cloud fallback assets in an aptly-named directory like `@webroot/cloud-fallbacks`. + +Remember to add whatever directory you choose to your `.gitignore`! +::: + +Repeat this process for each of your Local filesystems—they will not work on Cloud! Double-check that you have replaced them all by visiting **Settings** → **Filesystems** and scanning down the **Type** column. + +See the [Synchronizing Assets](#synchronizing-assets) section to learn about how to seed your Cloud storage with local assets. + +### Remote + +Craft doesn’t have a technical distinction between “local” and “remote” filesystems, but we’re addressing them separately here because the migration experience may differ greatly based on your existing storage provider. + +We recommend downloading all the files from your remote filesystem (using whatever tool is compatible with that storage infrastructure), then switching the filesystem type and setting its **Subpath**, **Base Path**, and **Base URL** values. + +Once the filesystem is working locally, you can [upload](#uploading-to-a-bucket) the assets to one of your project’s environments, ensuring they end up in the correct **Subpath** of the main `assets/` directory. + +## Synchronizing Assets + +You may upload and download assets from your environments’ storage bucket at any time. + +::: warning +We generally discourage direct modification of your production bucket’s files (after an initial import), as it can cause issues for control panel users—Craft can lose track of files if it is not the source of a change. +::: + +Both of the following processes require credentials for the target environment’s storage bucket. These secrets are available in a suitable format by visiting the **Access** tab of an environment in your Cloud project. + +You can use a GUI (like [Transmit](https://panic.com/transmit/)) or CLI (like the [official AWS client](https://aws.amazon.com/cli/)) to perform transfers in either direction. Usage examples (like the commands in the following sections) are provided in-context, for common tools. + +### Uploading to a Bucket + +Your project’s storage bucket is identified via the credentials you generated via the **Access** screen, but it is your responsibility to upload assets to the correct path. + +Let’s look at a command that uploads everything within a local `web/craft-cloud-assets/` folder to a Cloud storage bucket. + +```bash +cd path/to/project/root +aws s3 sync ./web/craft-cloud-assets/ s3://{project-uuid}/{environment-uuid}/assets/ +``` + +This command shows a URI beginning with `s3://`, followed by two segments (both UUIDs) that identify the target project and environment. + +The third segment in the path (`assets/`) is mandatory. This is the top-most directory that any Craft asset filesystem will write to, and files uploaded outside of it will be undiscoverable by Craft—and may collide with artifacts uploaded to the bucket during a build. + +Read more about the [`sync` command](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/sync.html) in the official AWS CLI documentation. If you are not confident about where files will end up, consider using `--dry-run` flag to list the operations that the CLI *would* attempt! + +::: warning +If you want to synchronize files from only one filesystem, ensure the local *and* remote paths are set properly. The example assumes you want an exact replica of the `web/craft-cloud-assets/` directory in your storage bucket—whether that represents a single filesystem mounted at that base path, or multiple filesystems with unique base paths, within it. +::: + +Clients that support setting a `Cache-Control` header or metadata when uploading files should use the value selected in the corresponding filesystem’s settings. + +### Downloading from a Bucket + +The same process can be used in reverse to download assets to your local environment: + +```bash +cd path/to/project/root +aws s3 sync --delete s3://{project-uuid}/{environment-uuid}/assets/ ./web/craft-cloud-assets/ +``` + +::: tip +For projects with large asset libraries (especially those over our soft 15GB per-environment [limit](/knowledge-base/cloud-quotas)), consider reaching out to us for recommendations about importing directly from other platforms. Credentials last for 1 hour—but as long as you use the `sync` command, it will be able to pick up where it left off. +::: + +### Copying Assets Between Environments + +Automated environment duplication/synchronization is a planned feature of Cloud. In the meantime, you can follow the instructions above to download and re-upload assets—or reach out to us if the time required for such an operation would be prohibitive. + +## Transforms + +The [Cloud extension](/knowledge-base/cloud-extension) transparently enhances Craft’s [asset transform](/docs/5.x/development/image-transforms.html) APIs by generating and caching images at the edge, using special pre-signed URLs. Existing transforms will work seamlessly on Cloud, whether predefined via [named transforms](/docs/5.x/development/image-transforms.html#applying-named-transforms-to-images) and as [ad-hoc transforms](/docs/5.x/development/image-transforms.html#defining-transforms-in-your-templates) (except for one [limitation](#limitations), noted below). + +These images don’t contribute to your [storage quota](/knowledge-base/cloud-quotas), and there are no limits on the number of transforms or compute time. + +### Content Negotiation + +When no format is explicitly defined for a transform (or the transform uses the **Auto** format), our workers may create and return a more modern WEBP or AVIF file, if the client supports it. + +### Limitations + +Our workers treat the [`stretch` mode](/docs/5.x/development/image-transforms.html#stretch) similarly to how the CSS `object-fit: cover` property works—instead of independently scaling an image’s width and height to the specified dimensions, it enlarges the image proportionately to fill the space. This difference will only manifest if you are using the `stretch` mode, and setting _both_ the `height` and `width` properties in such a way that the transformed image’s aspect ratio would be different from the source. + +Additional technical limitations include: + +- The maximum image size is 70MB; +- Images must be smaller than 100 megapixels, and animated images must contain fewer than 50 megapixels across all frames; +- The longest edge of an image is 12,000 pixels (or 1,600 pixels when transcoded to AVIF); + +In some situations where the requested transformation would result in a less efficient file (either by size or computation time), images may be delivered in a format other than what is requested. + +### SVGs + +SVGs are sanitized for security, but otherwise not modified in the process of creating a “transform.” + +## Local Development + +To simplify local and offline development, the Cloud filesystem supports a “local fallback” directory setting, which determines where assets are stored when running outside of the Cloud infrastructure. + +If you would like to temporarily rewrite asset URLs to use the CDN (even in local development), grab these variables from your Cloud project and add them to your `.env` file: + +```bash +# Copy from Project > Environment > Variables: +CRAFT_CLOUD_PROJECT_ID="..." +CRAFT_CLOUD_ENVIRONMENT_ID="..." + +# Set directly in .env: +CRAFT_CLOUD_USE_ASSET_CDN=1 +``` + +The Cloud extension will construct predictable production URLs for _existing_ assets. Note that uploading new assets to a remote Cloud bucket (or creating transforms from existing images) is not yet supported from local environments. The remote bucket is read-only in this scenario. diff --git a/docs/cloud/billing.md b/docs/cloud/billing.md new file mode 100644 index 000000000..e71b2fd8a --- /dev/null +++ b/docs/cloud/billing.md @@ -0,0 +1,57 @@ +# Billing + +Every Cloud project starts with a [free 7-day trial](#trials). At the end of the trial, you pay for the next month or a year of service. We currently do not support switching from monthly to yearly billing, or vice-versa. + +Like the Plugin Store and Developer Support plans, all Craft Cloud payments are processed with [Stripe](https://stripe.com/). + +## Trials + +You must have a valid payment method on file to start a seven-day trial of Craft Cloud, but you will not be billed until the end of the trial. If you cancel prior to your first bill, you will not be charged for any services. + +Trials provide access to all Cloud features, except for custom domains. Connecting a custom domain will prompt you to skip the trial and immediately start a subscription. Either way, you always have access to a [preview domain](/knowledge-base/cloud-domains). + +## Personal Accounts + Organizations + +Payment methods for personal accounts and organizations are separate. You will only be able to create Cloud projects in an account or organization that has a current payment method on file. + +**All Cloud projects are billed to the primary payment method on the account or organization it was created in.** + +Read more about [managing payment methods](/knowledge-base/craft-console-organizations#managing-payment-information) on Craft Console. + +## Billing History + +View the billing history for a Cloud project by navigating to its **Settings** screen. You can view *all* invoices for the current account or organization by clicking the gear icon in the toolbar at the top of any screen, then selecting **Billing**. + +## Cancellation + +To cancel an active Cloud project subscription, navigate to the project’s **Settings** screen in Craft Console and click **Cancel Project** within the **Danger Zone** section. + +### Reactivation + +Canceled projects can be reactivated until the end of the current billing period. Partial refunds are not issued for early cancellation or deletion of a project. + +### Deletion + +Once a project is canceled, you may immediately delete it via the same **Danger Zone**. We do not provide refunds for projects deleted prior to the end of the final billing period. + +::: warning +Deleted projects *immediately* stop serving traffic, and cannot be reactivated or recovered. +::: + +## Disputes and Refunds + +Please email or use our [contact form](https://craftcms.com/contact) if you have questions or concerns about billing. For prompt support, use the email associated with your Craft Console account, and include the Project’s **Name** and **ID**. Your Project ID can be found in its Craft Console URL: + +``` +/accounts/{org-name}/cloud/projects/{project-id} +``` + +## Failed Payments + +We will notify you as soon as we detect problems with the payment method on file, and prior to any automated changes in your project’s status or availability. Set up a new payment method as soon as possible to avoid service disruptions! + +::: tip +All billing-related communication will be sent from notifications@craft.cloud. If your project is managed within a Craft Console [organization](/knowledge-base/craft-console-organizations), all its owners will be notified of billing issues. +::: + +**Keep a valid payment method on file and monitor the inbox associated with your Craft Console account to avoid billing issues.** We strongly recommend using [organizations](kb:craft-console-organizations) for Craft Cloud projects—adding a second owner ensures that critical billing notifications are sent to users that can act on them. diff --git a/docs/cloud/builds.md b/docs/cloud/builds.md new file mode 100644 index 000000000..0057b67cc --- /dev/null +++ b/docs/cloud/builds.md @@ -0,0 +1,141 @@ +# Build Pipeline and Artifacts + +As part of every [deployment](/knowledge-base/cloud-deployment), Craft Cloud assembles all the code and configuration required to run your PHP application and build front-end assets. + +Everything about the build process is dictated by your repository, and [the `craft-cloud.yaml` config file](/knowledge-base/cloud-config). + +## PHP + +Your project’s `composer.json` and `composer.lock` files determine what PHP packages are installed. By default, Cloud expects both files to be at the root of your repository—but your Composer root can be [customized](/knowledge-base/cloud-config#config-schema). If either file is missing, the build will fail. + +Cloud installs packages by running `composer install`. + +## Node + +Similarly, Cloud looks for `package.json` and `package-lock.json` files at the root of your repository (or at a path set in your [config file](/knowledge-base/cloud-config#config-schema)). Unlike the PHP build step, if `package-lock.json` is *missing*, this step is skipped and the deployment will continue. + +To enable the Node build step, you must set a `node-version` in your [Cloud config file](/knowledge-base/cloud-config#config-schema). + +### Build Command + +Cloud executes the `build` script via `npm run build` after installing the listed packages with `npm clean-install`. You can change which script is run with the `npm-script` setting in `craft-cloud.yaml`—or the directory the command is run in with `node-path`. + +Special environment variables are exposed to your Node build process: + +- `CRAFT_CLOUD_PROJECT_ID`: UUID of the project the build is running in. +- `CRAFT_CLOUD_ENVIRONMENT_ID`: UUID of the build’s target environment. +- `CRAFT_CLOUD_BUILD_ID`: This build’s UUID. You will receive a new build ID for each deployment—even if they have the same `GIT_SHA`. +- `CRAFT_CLOUD_CDN_BASE_URL`: The root URL of your environment’s storage bucket. +- `CRAFT_CLOUD_ARTIFACT_BASE_URL`: See [Artifact URLs](#artifact-uRLs), below. +- `GIT_SHA`: The current commit hash being built. +- `NODE_ENV`: Always `production`, for Cloud builds (even in non-primary environments). + +Custom environment variables are currently _not_ injected into the build container. + +## Artifacts + +At the end of the build step, the contents of the project’s “artifact path” (the web root, by default) are copied to your storage bucket. + +::: warning +You can specify a different `artifact-path` in `craft-cloud.yaml`, but when using something other than your web root, files in your web root will no longer be published or accessible. Generally speaking, you should only change the `webroot`, and let Cloud keep the settings synchronized. +::: + +### Artifact URLs + +If you need to refer to the final, published URL of a build artifact from your build scripts, a file they generate, or from your Craft app, a special `CRAFT_CLOUD_ARTIFACT_BASE_URL` is provided to every environment. From Node, you can access this variable via `process.env.CRAFT_CLOUD_ARTIFACT_BASE_URL`—but be aware that it will _not_ be available (or useful) when your scripts are evaluated in a browser. + +On Cloud, that URL will always look something like this: + +```txt +https://cdn.craft.cloud/{environment-uuid}/builds/{build-uuid}/artifacts +``` + +Within that `artifacts/` directory, the file structure of your existing artifact path will be preserved. This means that—in most cases—a _relative_ path will work as you’d expect (say, for ES6 modules or CSS `@import` statements). + +::: tip +There is no need for filename-based cache-busting, as all artifact URLs will change with every build! +::: + +The [Cloud extension](/knowledge-base/cloud-extension) also provides the `cloud.artifactUrl()` helper function for generating URLs to files published during your build. If you have historically used the `siteUrl()` or `url()` functions to link a stylesheet or JavaScript file (or any other static asset) in your web root, use this function instead. + +Outside of Cloud, `cloud.artifactUrl()` falls back to the automatically-determined `@web` alias—and anything in your web root will resolve normally. The special `@artifactBaseUrl` alias mirrors this behavior, and can be used in Project Config—or [anywhere else that evaluates aliases](/docs/5.x/configure.html#control-panel-settings): + +```twig +{# Register a `script` tag to a static asset: #} +{% js '@artifactBaseUrl/dist/js/app.js' %} + +{# Equivalent to: #} +{% js cloud.artifactUrl('dist/js/app.js') %} + +{# …or a manually-constructed `script` tag with the corresponding `src`! #} +``` + +If your local development setup serves assets at a _different_ host (like Vite or a webpack dev server running on a different port), you may want to explicitly set the `CRAFT_CLOUD_ARTIFACT_BASE_URL` variable: + +```sh +CRAFT_CLOUD_ARTIFACT_BASE_URL="http://my-project.ddev.site:9000/" +``` + +This will override the default base URL returned by `cloud.artifactUrl()`. + +### Hot-linking Build Artifacts + +In case you need to link to a build artifact (or any other static file uploaded to the CDN) from _outside_ your site, we provide a stable URL to the current build: + +``` +https://cdn.craft.cloud/{environment-uuid}/builds/current/artifacts +``` + +The `current` segment takes the place of a specific build ID, and will always point to the most recent successful build. + +### Rewriting Artifact URLs + +As an alternative to replacing root-relative asset references in your templates, you can create [rewrite rules](/knowledge-base/cloud-redirects) to proxy individual files (or entire directories) from the CDN: + +```yml +rewrites: + - pattern: + pathname: '/assets/dist/*' + destination: '{artifactBaseUrl}{request.uri}' +``` + +You can also serve artifacts from an [additional domain or subdomain](/knowledge-base/cloud-domains), as a kind of white-labeled CDN: + +```yml +rewrites: + - pattern: + hostname: 'static.mydomain.com' + destination: '{artifactBaseUrl}{request.uri}' +``` + +A rule like this means that your Craft application is responsible for generating the appropriate URLs; the Cloud extension will continue use the canonical CDN URLs for `@artifactBaseUrl` and `cloud.artifactUrl(...)`. As a result, you are apt to need your own [alias](/docs/5.x/configure.html#aliases) in all of the same situations as you would have used the built-in helpers. + +### Reading Files + +Reading the contents of a build artifact from the CDN _can_ incur a performance penalty, but when properly cached, the impact will be minimal. + +::: tip +Only files that are created _during a build_ must be loaded from the CDN. Anything that is already committed to your `artifact-path` will be available on-disk at runtime. +::: + +#### SVGs + +Embedding an SVG generated by your build process with Craft’s `svg()` Twig function requests a copy from the CDN each time it is called. Consider pre-processing SVGs in a development environment and committing them to Git to make them available on the function’s disk at runtime. + +#### Manifests and Build Hashes + +Some front-end build tools write out a “manifest” that maps predictable artifact names (like `my-app.js`) to a build-specific filename that includes an unpredictable hash or digest (like `my-app.656e74f158356.js`) as a means of cache-busting stale assets. + +**This is not necessary on Craft Cloud, as each build’s assets are published to a unique URL.** + +If you would like to continue to support this workflow, your configuration may require an update to point to the `manifest.json` file on our CDN instead of by path on the local disk. Use `file_get_contents()` to load the contents of a remote file into memory, and the Cloud extension’s `craft\cloud\Helper::artifactUrl('path/to/manifest.json')` to get the build-specific URL. + +Users of the [Twigpack](https://plugins.craftcms.com/twigpack?craft5) plugin are protected from performance impacts by its built-in cache. The [Asset Rev](https://plugins.craftcms.com/assetrev?craft5) plugin memoizes manifest files for the duration of a request, but it does _not_ cache them between requests. + +::: tip +Craft Cloud’s [static cache](/knowledge-base/cloud-static-caching) can also mitigate latency issues when interacting with remote files. +::: + +### Common Toolchains + +We have provided special instructions for [Vite](https://nystudio107.com/docs/vite/#craft-cloud) and [Twigpack](https://nystudio107.com/docs/twigpack/#craft-cloud) in their respective documentation. diff --git a/docs/cloud/clients.md b/docs/cloud/clients.md new file mode 100644 index 000000000..7410f7f49 --- /dev/null +++ b/docs/cloud/clients.md @@ -0,0 +1,22 @@ +# Working with Clients + +Craft Cloud is part of Craft Console, so features that support teams like multi-user [organizations](/knowledge-base/craft-console-organizations) and access control are built in: + +- As a *developer* or agency, you can create organizations and projects on behalf of clients; +- As a *client*, you can invite your development partner to an organization and let them configure a project; + +Either way, taking advantage of organizations is key to collaborating on Cloud. + +::: tip +Our [Managing a Craft Cloud Project](/knowledge-base/cloud-project-management) article covers the project lifecycle in greater detail. +::: + +## Payment Methods + +An organization’s owner is responsible for maintaining its payment methods. A valid payment method is required to start a Cloud project; whenever a monthly or yearly bill is due, the organization’s primary payment method is automatically charged. + +Organization owners will be notified if there are [billing issues](/knowledge-base/cloud-billing) any of its Cloud projects. + +## Transferring Projects + +Currently, Cloud projects cannot be transferred between organizations, or between personal accounts and organizations. diff --git a/docs/cloud/compatibility.md b/docs/cloud/compatibility.md new file mode 100644 index 000000000..a78cc9c38 --- /dev/null +++ b/docs/cloud/compatibility.md @@ -0,0 +1,79 @@ +# Services and Compatibility + +Craft Cloud was designed to be compatible with a wide variety of projects—but for security and performance, we did have to make some decisions about what versions of Craft (and the software it depends on) we would officially support. This article covers those limitations, as well as some common features and configurations that may require special attention when moving a project to Cloud. + +::: tip +If you maintain a plugin or module, review our [Cloud for Plugin Developers](/knowledge-base/cloud-plugin-development) guide, as well! +::: + +## Craft + +Your project must be updated to at least {globalset:productVitals:vitalsCloudMinCraftVersion} to be able to install the [Cloud extension](/knowledge-base/cloud-extension), which provides essential functionality like automatic [configuration](/knowledge-base/cloud-config) and the [Cloud filesystem](/knowledge-base/cloud-assets). Version {globalset:productVitals:vitalsCloudMinExtensionVersion} of the extension is required to deploy your project. + +## PHP + +PHP {globalset:productVitals:custom_cloudMinPhpVersion} and newer are supported on Cloud. Pick a major and minor version via your project’s [`craft-cloud.yaml` config file](/knowledge-base/cloud-config). + +## Node + +Versions 16 and newer of Node are supported in our [builder](/knowledge-base/cloud-builds) via the `node-version` key in your [Cloud config file](/knowledge-base/cloud-config). We plan to add all [LTS releases](https://nodejs.org/en/about/previous-releases), moving forward. + +We recommend declaring only a major version (i.e. `20`) to receive security and stability updates, but minor releases (i.e. `18.6`) are supported. + +## Database Engines + +See our article on [working with databases](/knowledge-base/cloud-databases) for up-to-date information on supported MySQL and Postgres versions. MariaDB is not supported on Craft Cloud, and we no longer recommended it for Craft 5. + +## Mailers + +Craft Cloud does not have a built-in mail service. You must [configure your own adapter](/docs/5.x/system/mail.html) in Craft, as the default `sendmail` adapter will not work. + +## Filesystems + +**Local** filesystems will not work on Craft Cloud, and must be [converted](/knowledge-base/cloud-assets#converting-a-filesystem) to the Cloud filesystem provided by the extension. Remote filesystems provided by plugins that have not received updates from their maintainers to be compatible with Cloud may not be fully functional. + +## Configuration + +Some [Craft settings](/docs/5.x/configure.html) behave differently when running on Cloud. + +### General Config + +The [`resourceBasePath`](/docs/5.x/reference/config/general.html#resourcesbasepath) and [`resourceBaseUrl`](/docs/5.x/reference/config/general.html#resourcebaseurl) have no effect when running on Cloud. Asset bundles and anything that ends up in your [web root](#project-structure) are published to our CDN. + +We automatically enable Craft’s [`asyncCsrfInputs`](/docs/5.x/reference/config/general.html#asynccsrfinputs) setting to support [static caching](/knowledge-base/cloud-static-caching). + +### Application Config + +Changes made via `app.php` may not be honored when deployed to Cloud. Specifically, the [Cloud extension](/knowledge-base/cloud-extension) overrides these system components to guarantee they work in a Cloud-compatible way: + +- `assetManager` +- `cache` +- `mutex` +- `queue` +- `session` + +In addition, we automatically set properties on the `db` component via [environment overrides](/docs/5.x/configure.html#environment-overrides) to ensure Craft can connect to the current environment’s database. You may have connectivity issues if you use a `db.php` file, or add any other `CRAFT_DB_*` variables to an environment. + +### Project Structure + +If your project has a different directory structure than our official [starter project](/knowledge-base/using-the-starter-project), you may need to set some additional keys in your [Cloud config file](/knowledge-base/cloud-config). This includes the `webroot` and other `*-path` settings. + +## Workflow + +Cloud was built with teams in mind, so it reflects our recommendations for maintaining a healthy [development and deployment workflow](/docs/5.x/deploy.html). This means that… + +- …we require your code to be pushed to a Git provider; +- …direct access to the server/function filesystem is not allowed; +- …[Project Config](/docs/5.x/system/project-config.html) and changes that would alter `composer.json` (like running system updates) are discouraged; + +We believe these limitations will not affect most developers, but understand that they may involve some adjustment to processes. + +While `devMode` and `allowAdminChanges` are _possible_ to enable in Cloud environments, we strongly advise against it. Making changes to your project’s schema on Cloud can result in your database and Project Config files diverging, as well as data loss. + +Whenever possible, we recommend adopting one-way flows for code and content: code changes are made and tested locally, pushed to Git, then deployed; content changes are made in a live environment, backed up, and imported into your local environment. + +## Special Considerations + +### Headers + +Our infrastructure flattens duplicate HTTP response headers into a single, comma-separated one. If you are using the [`{% header … %}` tag](/docs/5.x/reference/twig/tags.html#header) in your templates or manipulating the response object’s `HeaderCollection` directly, you may see *slightly* different output from a Cloud response than you would in other environments. Rest assured, they are functionally equivalent in the HTTP spec! diff --git a/docs/cloud/config.md b/docs/cloud/config.md new file mode 100644 index 000000000..4aaf19eae --- /dev/null +++ b/docs/cloud/config.md @@ -0,0 +1,96 @@ +# Configuration + +Craft Cloud looks for a `craft-cloud.yaml` file in the root of the connected repository. + +This file has a specific syntax (YAML) and [schema](#config-schema) that determines a few things about how your project is [built](/knowledge-base/cloud-builds), [deployed](/knowledge-base/cloud-deployment), and served. If there are problems with your config file, the deployment will fail with an error describing the issue. + +::: tip +When you run `php craft setup/cloud` to install the [Cloud extension](/knowledge-base/cloud-extension), it will offer to generate a config file for you, then walk you through setting PHP and Node versions based on your project’s state. +::: + +## Config Schema + +Your `craft-cloud.yaml` must contain at least a `php-version` key: + +```yaml +# Versions must include major + minor, but no patch. +php-version: '8.2' +``` + +`composer.json`’s [`config.platform`](https://getcomposer.org/doc/06-config.md#platform) is only used to determine the default value that the CLI setup wizard presents. + +### Advanced Options + +These settings are optional, and should only be used when your project is incompatible with the platform defaults. + +```yaml +# Choose a major version of Node to use in your build step. +node-version: '18' + +# Directory NPM commands will be run in. +node-path: buildchain + +# Key/name of the `script` in package.json run at build time. +npm-script: build + +# The directory uploaded to our CDN at the end of the build step. +artifact-path: cms/web + +# The directory where your PHP application lives. +app-path: cms + +# Public directory, containing `index.php`. +webroot: web +``` + +Expanding on the above: + +- `node-version` — When declared, Cloud will use this Node version in your build step. (Default: None. If you wish to run a Node build step, you must specify a version!) +- `node-path` — This directory must contain `package.json` and `package-lock.json`. Your NPM script will be run here. (Default: `''`) +- `npm-script` — A single script name. Arbitrary Bash (including other `npx` commands) is not allowed. (Default: `build`) +- `artifact-path` — Anything emitted from your build step must be in this directory, or it will not be uploaded to the CDN or available to your running app, in any way. (Default: Inherits the value of `webroot`) +- `app-path` — `composer.json` and `composer.lock` must be located here. Cloud will run `composer install` in this directory. (Default: `''`) +- `webroot` — If your project uses a different directory for the public web root, you should specify it here. This is relative to `app-path`. (Default: `web`) + +::: tip +For the latest information on supported PHP and Node versions, see our [Cloud Services and Compatibility](/knowledge-base/cloud-compatibility) article. +::: + +### Redirects and Rewrites + +In addition to the above runtime and build settings, you can configure any number of [redirection and rewrite rules](/knowledge-base/cloud-redirects). These rules are evaluated _before_ the request reaches your Craft application, and can be used to normalize URLs, proxy assets or artifacts, redirect secondary domains, or map legacy URLs to your new site. + +### Directory Structure + +Multiple settings influence how Cloud locates key files in your project. The defaults agree with our official [starter project](https://github.com/craftcms/craft). + +If you have moved your `composer.json` or `package.json` into subdirectories, you will need to specify an `app-path` or `node-path`, respectively. Similarly, [changing your web root](/knowledge-base/moving-craft-files) will require setting a `webroot` value, unless it remains below `app-path`, in a directory named `web`. + +## Changing Settings + +You can update `craft-cloud.yaml` any time. The settings will be validated and used during the next deployment. If you want to test a setting, commit the changes to a branch, and deploy it to another environment! + +::: tip +If you encounter an error at build time, check out our [Troubleshooting](/knowledge-base/cloud-troubleshooting) guide. +::: + +## Headless and Decoupled Front-Ends + +If your front-end runs elsewhere (and Craft is deployed solely as a back-end or API), you may not need to run any build process on Cloud. Instead of blocking your deploys running the default `build` script, consider adding a `noop` script to your `package.json`… + +```json +{ + // ... + "scripts": { + "build": "webpack --production", + "noop": "exit 0" + } +} +``` + +…and updating `craft-cloud.yaml`, appropriately: + +```yaml +# ... +npm-script: 'noop' +``` diff --git a/docs/cloud/databases.md b/docs/cloud/databases.md new file mode 100644 index 000000000..5bf0de5a2 --- /dev/null +++ b/docs/cloud/databases.md @@ -0,0 +1,171 @@ +--- +related: + - uri: backups.md + label: Backing up and restoring Cloud databases + - uri: quotas.md + label: Resource limits on Cloud + - uri: extension.md + label: The Cloud extension +--- + +# Databases + +Craft Cloud supports [MySQL](#mySQL) and [Postgres](#postgres) databases. You will pick a database engine when creating a new Cloud project: if you are starting a new project, we recommend MySQL 8.0; existing projects should use the same engine and version used by their current infrastructure. + +Both engines support [automated and manual backups](/knowledge-base/cloud-backups) via Craft Console. + +::: tip +Using a `tablePrefix` from an earlier version of Craft? Follow [these instructions](#table-prefixes) to make your database Cloud-compatible. +::: + +## Database Engines + +Craft Cloud currently supports MySQL {globalset:productVitals:custom_cloudDbSupportMysql} and Postgres {globalset:productVitals:custom_cloudDbSupportPostgres} in [all regions](/knowledge-base/cloud-regions). + +## Connecting to your Database + +Each environment gets its own database. Connection details are automatically provided to your application via the [Cloud extension](/knowledge-base/cloud-extension), so no configuration is necessary! + +If you need to connect to your database from outside of Cloud (like with a database GUI), visit the **Access** screen of your environment to get credentials. + +## Backups + +In addition to automated nightly backups of your database, you can trigger a manual backup of any environment from Craft Console. + +→ Read more about [database backups](/knowledge-base/cloud-backups). + +::: warning +The **Database Backup** [utility](/docs/5.x/system/control-panel.html#utilities) is not currently supported on Cloud. Use the **Backups** screen in Craft Console to capture a backup. +::: + +## Importing Data + +From an existing Craft installation, run the [`db/backup` command](/docs/5.x/reference/cli.html#db-backup) to generate a Cloud-compatible database dump. To restore data from another Craft Cloud environment, instead capture and download a backup from the **Backups** screen of the source environment. + +The specific commands for importing a backup to Cloud depend on your driver, but they will always be run from your local machine (or from wherever your current Craft installation lives). Substitute the parameters in `{brackets}` with corresponding values from the [**Access** screen](#connecting-to-your-database) of the target Cloud environment. + +::: warning +The commands below will perform a “clean” import, erasing any existing content in the environment’s database! +::: + +### MySQL + +MySQL backups from Craft _or_ Cloud can be imported with this command: + +```bash +mysql \ + --host={cloud-db-hostname} \ + --port=3306 \ + --user={username} \ + --password={password} \ + --database={database} \ + < path/to/backup.sql +``` + +::: warning +Due to idiosyncrasies in the MySQL backup format, your `mysql` client binary must match the version the dump was created with—ideally down to the minor version. For example, if a MySQL dump is created from a server running 8.0.28, then it should be restored with the 8.0.28 `mysql` client version. Some GUI tools (like Table Plus) allow you to specify a version when performing a restore. +::: + +### Postgres + +Postgres backups come in a few different formats. Craft uses the `plaintext` format by default, but backups from Cloud are captured in the `custom` format for interoperability. + +To import a `plaintext` backup, run this command: + +```bash +psql \ + --host="{hostname}" \ + --username="{username}" \ + --dbname "{database}" \ + --password \ + < path/to/backup.sql +``` + +`custom` format backups must be restored with the [`pg_restore` command](https://www.postgresql.org/docs/current/app-pgrestore.html), and require additional flags: + +```bash +pg_restore \ + --host="{hostname}" \ + --username="{username}" \ + --dbname "{database}" \ + --password \ + --no-owner \ + --clean \ + --single-transaction \ + --if-exists \ + --no-acl \ + < path/to/backup.sql +``` + +As of Craft 4.10, you can choose the format Craft uses to back up a Postgres database with the [`backupCommandFormat` setting](/docs/5.x/reference/config/general.html#backupcommandformat). + +Make sure the version of `pg_restore` matches the version of `pg_dump` that was used to create the backup. Some GUI tools (like Table Plus) make it possible to choose the version when using binary backups. + +When dumping and restoring, the `--password` flag forces a password prompt—you do not need to provide a value as part of the original command. If you need to perform either operation in an automated or non-interactive environment, you can set a [temporary `PGPASSWORD` variable](https://www.postgresql.org/docs/current/libpq-envars.html): `PGPASSWORD=abc123 && pg_restore ...` + +## Table Prefixes + +The [`tablePrefix` setting](/docs/5.x/reference/config/db.html#tableprefix) (and the corresponding `CRAFT_DB_TABLE_PREFIX` environment variable) are not supported on Cloud. + +Run `php craft db/drop-table-prefix` in a local environment before importing your data into Cloud to rename the tables. After doing so, you should unset `tablePrefix` in `db.php` and remove `CRAFT_DB_TABLE_PREFIX` from your `.env`. + +## Tips + +Here are some common sources of issues when backing up or restoring databases. + +### Craft’s `backupCommand` + +Using a custom [`backupCommand` config setting](/docs/5.x/reference/config/general.html#backupcommand) can lead to unreliable backups. Be sure to check `general.php` _and_ your `.env` file for a `CRAFT_BACKUP_COMMAND` environment override! Try the default command and [reach out to support](/contact) if you still get malformed backups. + +### Backing up without Craft + +Craft (and Cloud) automatically determine the correct command and options for the configured driver when backing up your database—but if you only have access to a database (and not a functional Craft installation), you can still approximate Craft’s behavior. + +For MySQL, run this command: + +```bash +mysqldump \ + # Connection info: + --host={host} \ + --port={port} \ + --user={username} \ + --password={password} \ + # Additional flags: + --no-autocommit \ + --add-drop-table \ + --comments \ + --create-options \ + --dump-date \ + --routines \ + --set-charset \ + --triggers \ + --no-tablespaces \ + --quote-names \ + --set-gtid-purged=off \ + --quick \ + --single-transaction \ + --ignore-table=mydbname.cache \ + --ignore-table=mydbname.phpsessions \ + # Database name (passed as an argument, not an option): + {database} \ + > path/to/backup.sql +``` + +Postgres users should use `pg_dump`’s `custom` format for consistency: + +```bash +pg_dump \ + # Connection info: + --host="{hostname}" \ + --username="{username}" \ + --dbname="{database}" \ + --password \ + # Additional flags: + --format=custom \ + --schema=public \ + --exclude-table=public.cache \ + --exclude-table=public.phpsessions \ + > path/to/backup.sql +``` + +Note that in both cases, we ignore the `cache` and `phpsessions` tables. Cloud will recreate these if necessary during your next deployment, and they are not typically necessary in local development. diff --git a/docs/cloud/deployment.md b/docs/cloud/deployment.md new file mode 100644 index 000000000..ea3e3581f --- /dev/null +++ b/docs/cloud/deployment.md @@ -0,0 +1,38 @@ +# Deployment + +When you [trigger a deployment](#deployment-triggers) (by pushing code or manually starting one from Craft Console), Craft Cloud is actually doing three things, in sequence: + +1. [Build](#1-build-step) +2. [Migrate](#2-migrations) +3. [Release/Deploy](#3-deployment) + +This process reflects our general [deployment and workflow recommendations](/docs/5.x/deploy.html) laid out in the documentation—but it’s all handled for you! + +You can review an [environment](/knowledge-base/cloud-environments)’s deployment history (and the status of any active deployments) by navigating to its **Deployments** screen. + +### Deployment Triggers + +Each environment in Cloud defines its own **Deploy Trigger**, which determines when it is deployed. You may select from: + +- **On Push:** Deploys whenever a new commit is pushed to the selected **Branch**, or someone with access to your Cloud project manually starts one (see below). +- **Manual:** Deploys are only started manually, from Craft Console. + +**On Push** is a great option for teams with a well-defined Git flow that ensures only production-ready changes are committed or merged into the selected branch. + +## 1. Build Step + +The first thing Cloud does is assemble PHP and Node dependencies, and package them into a new function. This process is described in greater detail in our [Build Process and Artifacts](/knowledge-base/cloud-builds) article. + +If your project uses Node (or has unique PHP requirements), we strongly recommend familiarizing yourself with this stage of the deployment! + +## 2. Migrations + +On your new function, Cloud executes `php craft cloud/up` (a special version of `php craft up`), which applies project config changes and database migrations, and publishes all asset bundles. This must complete successfully for the deployment to continue—if a migration fails, the last-deployed version of your project will continue to serve requests. + +A record of this command (and its output) is added to the **Commands** section in that environment. + +## 3. Deployment + +When Cloud determines that the previous two steps have run without issue, it will begin serving requests from the newly-built functions. + +You can observe the progress of a deployment from the **Deployments** screen of each environment. There are no limits to the number of times you deploy each month, or the total “build minutes” for those deployments—but each deployment must complete within 15 minutes. diff --git a/docs/cloud/domains.md b/docs/cloud/domains.md new file mode 100644 index 000000000..61685bc02 --- /dev/null +++ b/docs/cloud/domains.md @@ -0,0 +1,127 @@ +# Domains + +Sites hosted on Craft Cloud can serve traffic on any domain you own. + +To [set up a domain on Cloud](#adding-a-domain), you will need access to its DNS records, which are often managed via your registrar or existing host. + +## Preview Domains + +Every environment in your Cloud project gets a unique preview domain. Preview domains always end in `preview.craft.cloud`, and will include your project handle and the first segment of the environment’s UUID. A complete preview domain looks something like this: + +```txt +project-my-handle-environment-b62dec18.preview.craft.cloud +``` + +To find your preview domain, click the globe icon next to any environment in the project navigation menu. If you don't see this icon, it’s likely because it hasn’t been [deployed](/knowledge-base/cloud-deployments) yet! + +::: tip +Changing the handle of a project or environment may take a moment to update in our routing layer. If you have other services that rely on a consistent hostname (say, for the delivery of webhooks), consider temporarily pointing a [subdomain](#subdomains) at the environment. +::: + +## Adding a Domain + +In your Cloud project, navigate to **Domains**, then click **New domain**. + +Provide the root domain you wish to add, and select an environment, if you want to tie it to one right away. You aren’t required to point the new root domain at Cloud, but any custom domains you do connect must go through a brief verification process before Cloud will respond to requests on it (or any subdomain thereof). + +Verifying a domain does _not_ automatically start [routing traffic](#route-traffic) to the selected environment. Conversely, you may elect to perform [real-time validation](/knowledge-base/cloud-for-cloudflare-users#real-time-validation) by immediately sending traffic to Cloud. + +::: warning +A `www` [subdomain](#subdomains) is not automatically created for you. You must add it explicitly, if you wish to use it in addition to the bare domain. See the [redirection](#redirection) section to learn about normalizing access via `www` or non-`www` URLs. +::: + + + +### Verify Ownership + +To verify ownership or control of a domain, you will be asked to add a single `TXT` record wherever you manage the domain’s DNS. This record will begin with `_cf-custom-hostname`, and is followed by the domain or hostname you provided. (You may only need to enter a portion of this record when adding it to your DNS provider—many treat records as subdomains of the apex domain, automatically expanding `_cf-custom-hostname` to `_cf-custom-hostname.mydomain.com`.) + +### Certificate Validation + +Cloud will provide a `CNAME` and two `TXT` records that together complete a verification handshake with the certificate issuer. + +### Route Traffic + +Depending on your DNS provider (and the TTL or “time to live” of any existing records), it may take anywhere from a couple of minutes to 24 hours for traffic to be routed to Cloud. + +::: warning +DNS records are cached for different amounts of time by different providers around the globe. You may see changes before or after your client and their customers—especially if you access the Internet from different regions. + +Heroku has a great [guide](https://devcenter.heroku.com/articles/custom-domains) that covers some of this technology, in the same context. If you are unfamiliar with DNS, consider starting with the [domain name glossary](https://devcenter.heroku.com/articles/custom-domains#domain-name-glossary) section, or flipping through Cloudflare’s [How DNS Works](https://www.cloudflare.com/learning/dns/what-is-dns/) series! +::: + +To send traffic from a verified domain to your Cloud project, add the records below. Keep in mind that making changes to your DNS *can* result in downtime. Read more about how to [prepare for going live](/knowledge-base/cloud-launch-checklist). + +The preferred way of routing traffic to Cloud is via a `CNAME` record: + +| Record Type | Value | +| --- | --- | +| `CNAME` | `edge.craft.cloud` | + +All DNS providers support `CNAME` records on subdomains (like `www`), but some do not accept them at the root or “apex” domain—sometimes called “[`CNAME` flattening](#cname-flattening).” + +If your provider does *not* support `CNAME` flattening at the root, you can still connect your domain to Cloud. Instead of the single `CNAME` record, add the two `A` records provided in the **A Record** tab of the **Route Traffic** step. + +::: tip +You should never need to use `A` records for subdomains. +::: + +The only difference between `A` and `CNAME` records is that—in the unlikely event we add or change edge IPs—you may need to make updates to your DNS configuration. *We will not make this kind of infrastructure change without providing customers a reasonable timeline and clear instructions for making required updates.* + +#### CNAME Flattening + +Using `CNAME` records at the root domain (also sometimes referred to as `ALIAS` or `ANAME` records) is supported by these popular DNS providers: + +- [Cloudflare](https://developers.cloudflare.com/dns/cname-flattening/) +- [Namecheap](https://www.namecheap.com/support/knowledgebase/article.aspx/10128/2237/how-to-create-an-alias-record/) +- [Dreamhost](https://help.dreamhost.com/hc/en-us/articles/360035516812-Adding-custom-DNS-records) +- [EasyDNS](https://kb.easydns.com/knowledge/aname-records/) +- [DNS Made Easy](https://support.dnsmadeeasy.com/support/solutions/articles/47001001412-aname-records) +- [Porkbun](https://kb.porkbun.com/article/68-how-to-edit-dns-records) + +We have _not_ been able to verify CNAME flattening or ANAME support for these services: + +- AWS Route53 +- Google domains +- GoDaddy + +If your provider does not support CNAME flattening, but you would like to take advantage of it, we recommend switching to Cloudflare before launching on Cloud. When setting up a domain with Cloudflare, they copy all your existing records, and give you an opportunity to tweak them before cutting over. + +### Subdomains + +Each domain can have any number of subdomains. Subdomains can point to the same environment as the primary domain (great for multi-site projects) or a different environment (perfect for a staging environment). + +You may also directly add and verify a non-apex domain if your project will never need to serve traffic from the apex—but we only recommend this in limited circumstances. + +## SSL + +Every domain that sends traffic to Craft Cloud is automatically protected with SSL by [Cloudflare](https://cloudflare.com). You do not need to manage certificates, redirection, or any other configuration—Cloud takes care of this for you, at the edge. + +Cloud also sets the `@web` alias to ensure all URLs are generated with the secure `https://` protocol. The only place we *don’t* know what `@web` should be is on the CLI—if you need to generate URLs from a command (or queue job), you may need to define this alias in your [application config](/docs/5.x/configure.html#aliases). + +## Nameservers + +Craft Cloud *does not* include domain registration or DNS management tools. You and your clients will still need to arrange the purchase and setup of a domain. + +## Pricing + +Every Cloud project includes one root domain, and as many subdomains as you need. You can purchase additional root domains at any time. Read more at [Cloud pricing](/cloud). + +## Redirection + +After adding your apex domain _and_ a `www` subdomain, you can create a [redirection rule](/knowledge-base/cloud-redirects) that matches one or the other to ensure traffic is always served at a single address. + +## Troubleshooting + +### Tools + +Some ISPs cache DNS lookups more aggressively than others, and can influence when and what records you see from your own internet connection. + +- Use [DNS Checker](https://dnschecker.org) from any web browser to verify your changes from multiple locations. +- The unix command line tool `dig` can be used to query specific DNS providers. For example, you can use Cloudflare’s own [1.1.1.1](https://one.one.one.one) resolver like this: `dig @1.1.1.1 craftcms.com` + +### Cloudflare Users + +All traffic enters Craft Cloud’s infrastructure via Cloudflare, which means it (and your projects!) are protected by enterprise-grade security features. However, this can complicate ownership and certificate verification for existing Cloudflare users who have proxying enabled on the domain’s current apex records. + +If you are in this situation (what Cloudflare calls [Orange-to-Orange](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/)), you will need to [follow this guide](/knowledge-base/cloud-for-cloudflare-users) to validate and connect your domain. diff --git a/docs/cloud/environments.md b/docs/cloud/environments.md new file mode 100644 index 000000000..bcb21fa09 --- /dev/null +++ b/docs/cloud/environments.md @@ -0,0 +1,97 @@ +# Environments + +Craft Cloud projects allow you to manage multiple distinct environments or “versions” of your site, each with their own [resources](#resources) and [settings](#environment-settings). Environments are perfect for testing changes before rolling them out to a live site. + +Team plans include two environments; Pro plans include three. + +## Features + +Most of your work in Cloud will be in the context of an environment. Each environment’s landing page has a summary of actions that are available to you. + +### Deployments + +View current and past deployments, or start a new one. Read more about [deploying to Craft Cloud](/knowledge-base/cloud-deployment). + +### Logs + +Review + search logs from your live app. + +### Backups + +Create and download snapshots of your [database](/knowledge-base/cloud-databases). Backups are created nightly, and you can start a new one at-will—they’re retained for 30 days, either way. + +### Variables + +Configure this’s environment variables. Adding, updating, or removing a variable requires a deployment to take effect—but you can make multiple changes, then trigger a deployment to keep related or dependent changes in sync. + +Cloud automatically sets a number of variables that are essential to your application. These are listed in the **System Variables** section, and they cannot be changed or overridden. + +### Commands + +Run a Craft console command from your browser. History and logs for past commands are available here, as well. + +Every deploy also triggers a `cloud/up` command, so you’ll see those records among any commands you’ve manually run. + +### Access + +Get credentials to this environment’s database and [asset storage](/knowledge-base/cloud-assets). Don’t share these details with anyone! + +### Settings + +Rename the environment, or change the branch it’s associated with (and when it will be [deployed](/knowledge-base/cloud-deployment)). + +## Resources + +Every environment gets its own database. Data is not automatically cloned from one environment to another, so you will need to manually restore a backup—that backup could come from another Cloud environment, or a local development database. + +All environments in a project share a single asset storage bucket, but they are separated into top-level directories named after their environment’s ID (or, more accurately, its UUID). + +Cloud generates a [preview domain](/knowledge-base/cloud-domains) for each environment—or allows you to connect a [custom domain](/knowledge-base/cloud-domains#adding-a-domain) or [subdomain](/knowledge-base/cloud-domains#subdomains) thereof. + +## Environment Settings + +When you create an environment, you’ll give it a name, select a Git branch, and choose a [deployment trigger](/knowledge-base/cloud-deployment#deployment-triggers). All three options can be changed any time from the environment’s **Settings** screen. + +## Production Environment + +In your project’s main **Settings** screen, you can select a **Production Environment**. This setting has three effects: + +### Warming + +The production environment’s function is kept “warm” by our infrastructure by periodically invoking it. + +To conserve compute resources (and therefore energy consumption), Cloud allows non-production environments’ functions to “sleep” after about 15 minutes. This means that—following a period of no activity—there may be a 1–2 second delay prior to the first request being served. + +These invocations do not fully bootstrap Craft, so they will be invisible to your application. + +### Front-End URLs + +Craft Console uses the production environment’s preview domain (or a custom domain connected to it, once verified) when generating public URLs to the project. You may see these at the project level—but when you’re managing a single environment, those URLs will always link to that environment. + +### robots.txt + +For any environment that is not marked as production, Craft Cloud will serve requests to `robots.txt` with this body: + +``` +User-agent: * +Disallow: / +``` + +So they don’t get indexed by search engines. Production environments will allow the application to dictate the contents of `robots.txt`. + +## Deleting an Environment + +Environments can be deleted at any time. Keep in mind that their resources will be destroyed, and they will immediately stop serving traffic. **Everything below will be unrecoverable:** + +- Your **database** and everything in it will be deleted; +- Any **assets** uploaded to the environment will be deleted; +- We remove all **system and custom variables** belonging to the environment; +- The environment’s **settings**, **deployment history**, **command history**, **logs**, and **temporary credentials** are all deleted; + +::: warning +Always capture a database backup—and download it—before destroying an environment. +::: + +Domains pointed at a deleted environment will also stop resolving. + +Instead of deleting an environment, we recommend creating a new one, then pointing custom domains at that—the “old” environment can stay around until you’re confident the new one is properly configured. You are not billed for inactive environments. diff --git a/docs/cloud/extension.md b/docs/cloud/extension.md new file mode 100644 index 000000000..0394b5c4d --- /dev/null +++ b/docs/cloud/extension.md @@ -0,0 +1,57 @@ +# Craft Extension + +To run a project on Craft Cloud, it must require our first-party `craftcms/cloud` package. + +In technical terms, the Cloud extension is a self-bootstrapping Yii module. Practically, it provides… + +- …a special [filesystem type](/knowledge-base/cloud-assets) that interfaces seamlessly with Cloud’s storage solution; +- …automatic and reliable configuration of your project’s database connection, cache, queue, and other application components; +- …[Twig helpers](/docs/5.x/reference/twig/functions.html) for generating [special URLs](#resource-uRLs); + +For most projects—and in local development—the extension will be largely undetectable. It only initializes functionality in environments that suggest (through the presence of special variables) it is necessary. + +::: tip +Note that Cloud applies additional configuration directly to Craft via special, non-optional [environment overrides](/docs/5.x/configure.html#environment-overrides). +::: + +## Installation + +You can install the extension with one command, in any project running Craft CMS 4.5.10 or later (but only projects on {globalset:productVitals:vitalsCloudMinCraftVersion} or later can be deployed to Cloud): + +```bash +php craft setup/cloud +``` + +If you would prefer to use Composer directly, require the `craftcms/cloud` package. After installation, perform one-time setup by running `php craft cloud/setup`. + +You will be prompted for some information about your project, and the wizard will write a [Craft Cloud configuration file](/knowledge-base/cloud-config) to the project’s root. + +## Special Features + +### Cloud Filesystem + +We recommend that new projects use the [Craft Cloud filesystem type](/knowledge-base/cloud-assets) for all [asset volumes](/docs/5.x/reference/element-types/assets.html). Other remote filesystem types may be compatible with Cloud, but will *not* support automatic fallback to your local disk, in development environments. + +### Application Components + +The extension replaces configuration for Craft’s cache, database, mutex, queue, and session [application components](/docs/5.x/reference/config/app.html) to ensure that they are configured in a way that is compatible with Cloud infrastructure. + +### Resource URLs + +By default, Craft publishes asset bundles to the public web root and generates URLs according to [`resourceBasePath`](/docs/5.x/reference/config/general.html#resourcebasepath) and [`resourceBaseUrl`](/docs/5.x/reference/config/general.html#resourcebaseurl). _These settings have no effect, when running on Cloud._ + +To conserve resources, Cloud’s compute layer doesn’t serve *any* static asset requests. Instead, these files are pre-generated and pushed to our CDN when your project is deployed. + +#### Build Artifacts + +Other static assets in your web root will also be uploaded to our CDN at build time. See our article on [build artifacts](/knowledge-base/cloud-builds#artifact-urls) for more information about generating URLs for these files. + +### Additional Configuration + +The Cloud extension includes some [additional settings](https://github.com/craftcms/cloud-extension-yii2), but they are intended only for debugging and advanced use cases, like emulating Craft Cloud infrastructure, locally. *Configuration that is necessary for your site to run on Cloud will be applied automatically.* + +## Further Reading + +Additional technical details and the extension’s source are available in the [readme on GitHub](https://github.com/craftcms/cloud-extension-yii2). + +If you encounter a bug or compatibility issues with another plugin (public or private), please [file an issue](https://github.com/craftcms/cloud-extension-yii2/issues/new/choose) or [contact support](/contact?whatCanWeHelpYouWith=Support)! diff --git a/docs/cloud/faq.md b/docs/cloud/faq.md new file mode 100644 index 000000000..ea984dbe0 --- /dev/null +++ b/docs/cloud/faq.md @@ -0,0 +1,170 @@ +# FAQ + +Here are the top questions we get asked about [Craft Cloud](https://craftcms.com/cloud), our first-party hosting platform. + +## Status + Help + +### Can I monitor Craft Cloud’s health? + +Our [status page](https://status.craftcms.com) inclues information about Craft Cloud and all our other web services. More information about health checks is available in the [Cloud Status](/knowledge-base/cloud-status) article. + +A link to the status page is available in the footer of every page on . + +### Where can I find more information on Craft Cloud? + +The [Knowledge Base](/knowledge-base/cloud) is the best place to find answers to your Cloud questions—in particular, our [Getting Started](/knowledge-base/cloud-getting-started) guide and the [Troubleshooting Common Problems on Craft Cloud](/knowledge-base/cloud-troubleshooting) are pathways into many platform concepts. + +If you have questions about our software products, check out the [Craft CMS](/docs/5.x) or [Craft Commerce](/docs/commerce/5.x) documentation. + +### How do I get support for my Craft Cloud project? + +Your Craft Cloud subscription entitles you to complementary [developer support](/support-services)! Start a new conversation from our [contact page](/contact?whatCanWeHelpYouWith=Support) using the email associated with your [Craft Console](/knowledge-base/what-is-craft-console) account, or email us directly at <{globalset:productVitals:custom_cloudSupportEmail}>. + +### How fast are support response times? + +Response times will be similar to normal Craft CMS developer support—we assign priority to incoming issues and address them in an equitable way. We have support personnel in each of Craft Cloud’s [regions](/knowledge-base/cloud-regions) (US, Canada, EU, APAC). + +Information about our support tiers is available on the [Developer Support](/support-services) page. + +### Is there a roadmap for Craft Cloud? + +Yes! Check out the [Roadmaps](https://craftcms.com/roadmap) page. Our plans for Craft Cloud appear [at the bottom of the page](https://craftcms.com/roadmap#cloud). + +### How do I request a feature for Craft Cloud? + +We welcome feature requests via the [public discussion board](https://github.com/craftcms/cloud/discussions), or via <{globalset:productVitals:custom_cloudSupportEmail}>. + +## Service + Features + +### Can I point multiple domains to a single Craft Cloud environment? + +Yes! This is a perfect way to manage multi-site installations. + +Each project gets one free domain, and unlimited subdomains; additional domains can be added [for a fee](/cloud#cloud-infrastructure). + +### Which Git providers do you support? + +We currently support connecting GitHub, Gitlab, and BitBucket repositories. + +### What’s the minimum version of Craft and PHP that Craft Cloud supports? + +Craft Cloud requires Craft CMS {globalset:productVitals:vitalsCloudMinCraftVersion} and PHP {globalset:productVitals:custom_cloudMinPhpVersion}. Your `composer.lock` file determines what version of Craft gets installed; your PHP version must be defined in your project’s [`craft-cloud.yaml` configuration file](/knowledge-base/cloud-config). + +### Is there are a trial for Craft Cloud? + +Yes, all Craft Cloud projects start with a free 7-day trial. Read more about trials in our [Billing](/knowledge-base/cloud-billing) article. + +### Which specific regions do you cover? + +We currently have presence in North America (Oregon, USA), Canada (Quebec), Europe (Frankfurt, Germany), and Asia-Pacific (Sydney, Australia). + +Read more about [region support](/knowledge-base/cloud-regions). + +### Is data encrypted at-rest? + +Yes—your [assets](/knowledge-base/cloud-assets) and database are both encrypted at-rest. More information is available in our dedicated [databases](/knowledge-base/cloud-databases) article. + +### What kind of firewall do you have in place for Cloud? + +All Craft Cloud projects are protected by our Cloudflare WAF, with a “reasonable” setup of default rules. We make specific changes to the firewall as needs arise. + +Some customers have their own Cloudflare accounts in front of ours, allowing them to manage specific WAF rules before requests make it to Craft Cloud. Cloudflare refers to this as the “[Orange-to-Orange](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/)” scenario; more information about this setup is available in the [Craft Cloud for Cloudflare](/knowledge-base/cloud-for-cloudflare-users) article. + +### Can I edit my .htaccess or nginx config file? + +Nope, sorry! Craft Cloud is serverless, and doesn’t use a traditional HTTP server like nginx or Apache. + +### Can I SSH into my server? + +Craft Cloud’s serverless architecture means there is nothing to SSH into! Images are built during each deployment, and spun up and destroyed based on traffic—even though the [ephemeral filesystem](/knowledge-base/cloud-migrating-projects) takes some getting used to, its inherent stability and security are an essential part of what makes Cloud such a great place to host your Craft project. + +### Can I run Craft console commands? + +Yes! From any environment in Craft Console, select **Commands**, then type in the Craft command you want to run. Arbitrary shell commands are not allowed. + +Read more about [running](/knowledge-base/cloud-commands) and [scheduling](/knowledge-base/cloud-cron) commands on Cloud. + +### Does Craft Cloud support MariaDB? + +No, Craft Cloud only supports MySQL {globalset:productVitals:custom_cloudDbSupportMysql} and Postgres {globalset:productVitals:custom_cloudDbSupportPostgres}. If you are migrating a site to Cloud, make sure its database can be neatly imported into MySQL 8, first. + +### How do I roll back a deployment? + +Currently, there is no automatic way to do this. + +As a result of each environment being connected to a git repository, you can revert problematic commits and re-deploy. If changes were made to the database that need to be rolled back (say, via a migration), the database will need to be restored to an appropriate point. Migrations are only run once Cloud has finished building your application image. Failed builds are never deployed! + +Read more about [deployments](/knowledge-base/cloud-deployment) and our [build pipeline](/knowledge-base/cloud-builds). + +### Can I sync code/databases/assets between environments? + +You can populate environments’ storage from whatever source(s) you want, but there is not currently an automated tool for this. + +- **Code:** Select the same branch as another environment, and start a deployment. +- **Database:** [Capture and download a backup](/knowledge-base/cloud-backups), then [restore it](/knowledge-base/cloud-backups#restoring-backups) to the secondary environment. +- **Assets:** Manually copy files from one bucket to another. Read more about [synchronizing assets](/knowledge-base/cloud-assets#synchronizing-assets). + +Database and asset access credentials can be retrieved from your Craft Cloud console on a per-environment basis via the **Access** menu. + +### Do I have to supply my own SSL certificate for my site? + +Nope! SSL is included with every domain connected to your Craft Cloud project, and requests are automatically redirected to HTTPs. + +### Can I supply my own custom SSL certificate for my site? + +Yes! Please send us an email at <{globalset:productVitals:custom_cloudSupportEmail}> to get started. + +### Does Craft Cloud provide email services for my Craft project? + +We currently do not have a dedicated transactional email service. You are free to use any Craft-compatible mailer adapter or SMTP service. + +We cover [customizing Craft’s mailer](/docs/5.x/system/mail.html) in the documentation. + +### Does Craft Cloud provide a deployment pipeline? + +Yes! Read all about [deployments](/knowledge-base/cloud-deployment) and the [build pipeline](/knowledge-base/cloud-builds). + +### How can I statically cache the front end of my site? + +Craft Cloud has a built-in [static caching](/knowledge-base/cloud-static-cache) system that is designed to work seamlessly with Craft CMS. On-disk and rewrite-based caches will not work, as the Cloud filesystem is ephemeral—and files in the “web root” aren’t directly exposed to the web. + +### How do I work with assets locally and remotely? + +The [Cloud filesystem](/knowledge-base/cloud-assets) has a special “fallback” feature for working locally. + +### How do I move an existing project to Craft Cloud? + +Check out our [migration guide](/knowledge-base/cloud-migrating-projects)! As long as you are using Craft CMS {globalset:productVitals:vitalsCloudMinCraftVersion} or later, your project is apt to work on Craft Cloud with very few changes. + + +## Billing + Legal + +### How does billing work in Craft Cloud? + +Craft Cloud plans require a valid payment method on file in your Craft Console account or [organization](/knowledge-base/craft-console-organizations#managing-payment-information). Monthly and yearly plans are available. + +Read more about [billing on Craft Cloud](/knowledge-base/cloud-billing). + +### Do I need to purchase a Craft license for my site on Craft Cloud? + +Nope! A Craft license is included with your Craft Cloud plan. It is valid for as long as your plan is in good standing. + +You _do_ need to purchase licenses for any plugins you use, via the in-app Plugin Store. + +### Are there any resource limits on Craft Cloud? + +Metered resources are listed on our [Cloud Quotas](/knowledge-base/cloud-quotas) page. Technical limitations are covered in [Cloud Services + Compatability](/knowledge-base/cloud-compatibility). + +Use of Craft Cloud is also subject to our [Acceptable Use Policy](/acceptable-use-policy) and [Terms of Service](/terms-of-service). + +### What kinds of usage trigger additional charges? + +We have taken great care to make pricing stable for Cloud customers. As such, we do not use metered billing on any services—instead, we offer two [plans](/cloud#pricing), with add-ons for [asset storage](/knowledge-base/cloud-assets) and [domains](/knowledge-base/cloud-domains). + +Refer to the [resource limitations](/knowledge-base/cloud-quotas) page for a list of other metrics. + +{{ cloud.supportEmail }} + +### Do you offer SLAs? + +We only offer SLAs with enterprise agreements in place. Send an email to <{globalset:productVitals:custom_cloudSupportEmail}> to get started. diff --git a/docs/cloud/getting-started.md b/docs/cloud/getting-started.md new file mode 100644 index 000000000..e66fbefff --- /dev/null +++ b/docs/cloud/getting-started.md @@ -0,0 +1,123 @@ +# Getting Started + +Welcome to [Craft Cloud](/cloud), our new hosting platform tailor-made for Craft CMS! + +This article covers the critical path to deploying your first project to Cloud. For [new projects](#new-sites), we still recommend starting with a local development environment; most [existing projects](#existing-sites) can be moved to Cloud after a quick system update. + +The process looks something like this: + +1. ✏️ Spin up a Craft project locally +2. 🌩️ Push your code to a repository and connect it to a new Cloud project in Craft Console +3. 🚀 Kick off your first deploy + +Let’s get started! + +## Requirements + +In addition to a basic familiarity with Craft CMS, this guide will require… + +- …a [Craft Console](https://console.craftcms.com) account with a payment method on file; +- …a [GitHub](https://github.com), [BitBucket](https://bitbucket.org), or [Gitlab](https://gitlab.com) account; +- …access to your domain’s DNS records (when you’re ready to go live); + +You will be able to follow along using the seven-day free trial included with every Cloud project. + +## Preparing your Codebase + +Any Craft CMS site running version {globalset:productVitals:vitalsCloudMinCraftVersion} or later can be configured to run on Cloud. Plugins and custom modules must be compatible with at least PHP {globalset:productVitals:custom_cloudMinPhpVersion}, and the project must `require` version {globalset:productVitals:vitalsCloudMinExtensionVersion} of the [Cloud extension](/knowledge-base/cloud-extension). + +### New Sites + +Cloud projects begin the same way as any other. Follow the standard [installation instructions](/docs/5.x/install.html) to get a new site running locally, then run this command to get it Cloud-ready: + +```bash +ddev craft setup/cloud +``` + +Craft will install the [`craftcms/cloud` extension](/knowledge-base/cloud-extension), which handles all the necessary configuration, automatically. Your project will continue to work normally, in local development. + +Commit and push the project files to a fresh Git repository. + +### Existing Sites + +Update your project to at least Craft {globalset:productVitals:vitalsCloudMinCraftVersion}, then run the command above. Most projects will run on Cloud without modification—but we recommend reviewing the [compatibility guide](/knowledge-base/cloud-compatibility) if you’ve made any customizations via [application config](/docs/5.x/reference/config/app.html), custom modules, or private plugins. We also have a dedicated guide on [moving projects to Craft Cloud](/knowledge-base/cloud-migrating-projects) from other hosts. + +::: tip +Does your project use the `tablePrefix` setting or `CRAFT_DB_TABLE_PREFIX` config variable? Run `ddev craft db/drop-table-prefix` before continuing. +::: + +Commit and push the changes to your Git provider. You’re ready! + +## Gathering Materials + +With your project running locally, it’s the perfect time to collect a few things we’ll need later: + +1. Capture a [database backup](/knowledge-base/cloud-databases) and take note of the driver (Postgres or MySQL) and version; +1. Download a copy of all your assets (if feasible); +1. Document all your project-specific environment variables; + +## Your First Cloud Project + +If you haven’t already, create a [Craft Console](/knowledge-base/what-is-craft-console) account and add a [payment method](/knowledge-base/craft-console-organizations#managing-payment-information). + +::: tip +Cloud projects can be created from your personal Console account, or within an [organization](/knowledge-base/craft-console-organizations), but we strongly recommend using organizations whenever possible—especially for businesses and agencies that can benefit from delegated access. +::: + +From the **Cloud** tab, click **New Project**. Select from the available git providers (or connect a new one), then choose the repository your Craft project was pushed to, in the previous step. Don’t see your repo? Try [one of these troubleshooting tips](/knowledge-base/cloud-troubleshooting#repo-not-visible). + +### Project Settings + +When creating a project, you will be asked for a **Project Name** and **Handle**, what [**Region**](/knowledge-base/cloud-regions) it should be hosted in, and the [**Database Engine**](/knowledge-base/cloud-databases) you’d like to use. The database engine should match whatever you are using locally—if you just started a new project with DDEV, that would be MySQL 8. + +### Billing + Terms + +You can pay for Cloud projects monthly or annually. Discounts are provided on annual plans, and to verified [Partners](/become-a-partner). Learn more about how [billing](/knowledge-base/cloud-billing) works. + +All Cloud plans come with a free seven-day trial! + +## Deployment + +With your Cloud project connected to a Git repository, it’s time to set up an **Environment**. [Environments](/knowledge-base/cloud-environments) allow you to configure and deploy multiple versions of your project, independently—like a live site and a staging site. + +### Create an Environment + +Each environment is associated with a Git branch, and gets its own database, asset storage, environment variables, logs, [preview domain](/knowledge-base/cloud-domains#preview-domains), and deployment strategy. + +From your project’s dashboard, click **Environments**, then **New environment**. Give it a **Name**, and select your desired **Deploy Trigger** and **Branch**. Below the settings pane, you’ll have an opportunity to pre-populate the environment with project-specific variables that you would normally store in a `.env` file. You do _not_ need to copy database connection details, URLs, or variables you would only set in a development environment—most configuration will be handled for you, automatically! + +Click **Save**, and Cloud will create the environment’s resources. + +::: tip +If you selected “On Push” for your **Deployment Trigger**, Cloud will deploy this environment the next time you push a commit to the selected branch. Both “On Push” and “Manual” triggers allow you to visit the Deployments tab of the environment and click **Deploy** to build and deploy from the latest code. +::: + +### Importing a Database + +See our article on [working with Cloud databases](/knowledge-base/cloud-databases) to learn about the process of making and importing a database backup. The process will differ slightly for Postgres and MySQL users. + +### Importing Assets + +::: tip +If you just started a new project, you can skip this section, and review our [Assets on Craft Cloud](/knowledge-base/cloud-assets) article when you’re ready to set up your first asset volume. +::: + +Existing projects that use a **Local** asset filesystem will require an update to work on Cloud. See our article about [migrating to Cloud asset storage](/knowledge-base/cloud-assets#synchronizing-assets) for more information. While we do not impose limitations on the third-party services your app communicates with, their plugins may require updates to be fully compatible with Cloud. + +### Triggering a Deploy + +In your environment’s **Deployments** screen, click the **Deploy** button in the upper-right corner. + +Cloud will begin a new [build](/knowledge-base/cloud-builds), and your changes will be available at your [preview domain](/knowledge-base/cloud-domains#preview-domains) in a minute or two! + +## Preview Domains + +Every environment gets a [preview domain](/knowledge-base/cloud-domains#preview-domains) so you can make sure everything is working as expected *before* pointing your real domain at it. + +::: tip +Not seeing your changes? Deployment status is reflected on the **Deployments** overview page, and more information is available when clicking the commit message of a single deploy. +::: + +### Custom Domains + +When you’re ready to cut over, check out our guide on [using custom domains](/knowledge-base/cloud-domains). Your first custom domain (and any number subdomains thereof) are free with a Cloud project. diff --git a/docs/cloud/launch-checklist.md b/docs/cloud/launch-checklist.md new file mode 100644 index 000000000..a510ad583 --- /dev/null +++ b/docs/cloud/launch-checklist.md @@ -0,0 +1,32 @@ +# Launch Checklist + +Craft Cloud’s infrastructure is always ready for an influx of traffic—but there are still things that you can do to make launch day go more smoothly! + +## Preparation + +Make sure you have access to your domain’s DNS management tool well in advance of launch. We recommend using a DNS provider that supports [CNAME flattening](/knowledge-base/cloud-domains#cname-flattening)—but it’s not a requirement to connect a domain at Cloud. + +### Domain Validation + +This is typically the most volatile part of connecting a domain to Cloud—so make sure you’ve started the process by [adding the validation records](/knowledge-base/cloud-domains#adding-a-domain) to your DNS provider as soon as you know where the site will live. Don’t worry—validating a domain won't automatically send traffic to Cloud! + +### TTL + +A few days before going live, consider lowering the TTL on key DNS records to ~300 seconds (five minutes). In most cases, that would be your root domain’s `A` records—but it could also be a subdomain’s `CNAME` record. Check out our [domains article](/knowledge-base/cloud-domains) for more information about what you’ll be asked to update. + +This gives downstream providers’ caches time to expire, at which point they will re-fetch those records with the new (shorter) TTL—meaning subsequent updates will take less time to be picked up. + +## Cutting Over + +When it’s time to flip the switch, you’ll need to do two things: + +1. Promote your [environment](/knowledge-base/cloud-environments) to [production](/knowledge-base/cloud-environments#production-environment) by selecting it in the project’s **Settings** screen. This signals to Cloud that the function should be kept warm by the platform so there’s no delay when the first request comes in. +2. [Update your domains’ DNS records](/knowledge-base/cloud-domains). Any domains (or subdomains) that should point to your production environment will require changes. Existing Cloudflare users may need to [disable proxying](/knowledge-base/cloud-for-cloudflare-users) on the apex domain. + +## Deployments + +Chances are, you’ve been iterating and deploying changes frequently over the course of development. Now that the site is publicly accessible, make sure the [deployment trigger](/knowledge-base/cloud-deployment#deployment-triggers) in your environment’s **Settings** screen agrees with your team’s desired workflow. + +### Staging Environment + +If you would like to continue testing and previewing changes with your team (before deploying them to production), consider setting up a second “staging” environment—your Cloud project subscription includes three environments to use however you like! diff --git a/docs/cloud/local-dev.md b/docs/cloud/local-dev.md new file mode 100644 index 000000000..8ec496cfd --- /dev/null +++ b/docs/cloud/local-dev.md @@ -0,0 +1,44 @@ +# Local Development + +Craft Cloud has very little impact on your local development stack. Any changes required to make your project infrastructure-agnostic are apt to be in code or configuration—not tooling! + +Our [Moving to Craft Cloud](/knowledge-base/cloud-migrating-projects) article covers these changes in detail, but the bits and pieces relevant to local development are collected here. + +::: tip +DDEV remains our recommended development environment, as it supports all the PHP and database versions that Cloud does. +::: + +## The Cloud Extension + +The [Cloud extension](/knowledge-base/cloud-extension) allows us to dynamically override some of your Craft application’s configuration to take advantage of platform features, like connecting to the managed database and asset storage. + +Your configuration is *not* modified when your project is running outside of Cloud. It’s important to be aware when [moving to Cloud](/knowledge-base/cloud-migrating-projects), though, which components’ configuration *will* be overridden—especially if your local development environment is designed to reflect your production infrastructure, and you expect certain features (Redis, for instance) to be available at all times. + +When your local environment *does* need special configuration (say, to work with your team’s Docker Compose setup), that configuration should be handled with [environment variables](/docs/5.x/configure.html#environment-overrides) or [scoped to a specific environment](/docs/5.x/configure.html#multi-environment-configs). + +### Database Connection + +We recommend *against* using a `db.php` config file when working on a project that is deployed to Craft Cloud. Instead, use the special `CRAFT_DB_*` [environment variables](/docs/5.x/reference/config/db.html) to set only the connection properties your development environment relies on. + +::: tip +Make note of which variables you need for local development in a `.env.example` file so your teammates can get up to speed quickly! +::: + +## Assets and Filesystems + +The [Cloud filesystem](/knowledge-base/cloud-assets) has special settings for local development, under its **Local Filesystem** section. Ensure these settings make sense for your project’s structure: + +- The **Base Path** should be below your web root (if the assets you’ll be storing there have public URLs), typically beginning with the `@webroot` alias; +- The **Base URL** should agree, usually starting with the `@web` alias; + +To learn more about filesystem settings and synchronizing files, see our article on [working with assets](/knowledge-base/cloud-assets). + +### Static Assets + +References to files in your web root (like scripts and stylesheets) should use the `artifactUrl()` helper provided by the Cloud extension. Read more about [generating artifact URLs](/knowledge-base/cloud-builds#artifact-uRLs), especially if you use a development server for front-end assets like Vite or webpack! + +## Database Backups + +The [Databases on Craft Cloud](/knowledge-base/cloud-databases) article has instructions for capturing and restoring Cloud-compatible database backups. + +MySQL databases can be restored from a manual or automated Cloud backup with Craft itself (using the `php craft db/restore` command), but Postgres backups require direct use of `pg_restore`. diff --git a/docs/cloud/migrating.md b/docs/cloud/migrating.md new file mode 100644 index 000000000..9f72803c9 --- /dev/null +++ b/docs/cloud/migrating.md @@ -0,0 +1,97 @@ +Moving a Project to Cloud + +::: tip +Be sure and review our [Getting Started with Craft Cloud](/knowledge-base/cloud-getting-started) guide! +::: + +This guide collects information from multiple other articles about making an existing project compatible with Craft Cloud. + +Most projects will *not* need any special treatment, and will work with minimal configuration—just like a new project. Heavily-customized projects (including those with a non-standard [directory structure](/docs/5.x/system/directory-structure.html)) may require additional auditing or configuration. + +Projects based on our official Composer [starter project](/knowledge-base/using-the-starter-project) tend to enjoy a minimally disruptive migration process, but it’s still a good idea to fully review this document and the resources it links to. + +## Code + Configuration + +The first thing we’ll tackle is updates to your code and configuration. + +### Key Requirements + +Your Craft project must already be running Craft {globalset:productVitals:vitalsCloudMinCraftVersion} or later to be compatible with Cloud. In addition, you will need to install the first-party [Cloud extension](/knowledge-base/cloud-extension). + +### Cloud Config + +Cloud expects a `craft-cloud.yaml` file at the root of your repository. At a minimum, this file must contain a `php-version` key to tell Cloud what PHP runtime to use. It’s also where you’ll communicate to the builder where your Composer and Node “roots” are—if you have customized your project’s directory structure, you may need to provide additional keys in this config file. + +Read more about using the [Cloud config file](/knowledge-base/cloud-config). + +### Filesystems + +Craft Cloud does not have a persistent filesystem (it is [ephemeral](/docs/5.x/reference/config/bootstrap.html#craft-ephemeral) in nature), so **Local** filesystems must be migrated to use the **Cloud** filesystem provided by the Cloud extension. + +We have a dedicated article about [working with assets on Cloud](/knowledge-base/cloud-assets), and a section that [specifically addresses this migration](/knowledge-base/cloud-assets#synchronizing-assets). + +### Artifacts, Templates, and URLs + +When you deploy your site to Craft Cloud, an [automated build process](/knowledge-base/cloud-builds) takes care of generating artifacts via NPM and uploading them to our CDN. This means that they are not directly accessible in the webroot of your site—via the filesystem *or* over HTTP. See our recommendations for [handling references to those artifacts](/knowledge-base/cloud-builds#artifact-urls) in your templates. + +::: tip +You have control over the build process via [the `craft-cloud.yaml` config file](/knowledge-base/cloud-config). +::: + +You do _not_ need to set a `@web` [alias](https://craftcms.com/docs/5.x/configure.html#aliases) on Cloud, as all traffic to your site will arrive via our gateway, which sets and validates headers to prevent common security issues. + +### Application Config + +Craft Cloud automatically configures a number of key application components to make use of platform resources. If you have made any changes via `app.php` to support features of your current infrastructure, you may need to remove or [scope those modifications to a non-Cloud environment](/docs/5.x/configure.html#multi-environment-configs). + +### Environment Variables + +Your environment variables are managed via each environment’s **Variables** screen—not a `.env` file. Craft Cloud automatically sets a number of important variables, including all of your database connection details, the current site URL or domain, and some [config overrides](/docs/5.x/configure.html#config-overrides) that ensure a consistent experience. + +Before your first deployment, add any *custom* variables you reference in your code or project config. Sensitive values can be marked as “write-only” to prevent them from being lifted back out of Craft Console by another organization member. Those values are decrypted at runtime to a special [secrets file](/docs/5.x/configure.html#secrets), and will not appear in logs or be set at the process level. + +## Content + +This section is primarily concerned with importing your existing content to Craft Cloud. + +### Assets + +Once you’ve [converted your asset filesystems](/knowledge-base/cloud-assets#converting-a-filesystem) in a local environment, you must [upload the assets](/knowledge-base/cloud-assets#synchronizing-assets) within them. + +### Database + +Unlike assets, your database does not require any configuration changes—simply choose the database driver and version matching your current infrastructure when [setting up your Cloud project](/knowledge-base/cloud-getting-started). Keep in mind (per the above [application config](#application-config) section) that changes to your database connection component may be overridden when running on Cloud. A `db.php` file is not required for Craft Cloud; we recommend setting all connection information for local development (or other non-Cloud environments) via environment variables. + +Our [Craft Cloud Databases](/knowledge-base/cloud-databases) article contains sections on importing and exporting data. + +::: warning +Craft Cloud does not support the `tablePrefix` setting. See [this section](/knowledge-base/cloud-databases#table-prefixes) for information about renaming the tables in your project. +::: + +## Deployment + +Once you’ve made the required code changes and imported your content, run a [deployment](/knowledge-base/cloud-deployment). While it’s a good idea to test the updates locally, you do *not* need to deploy the updates to your legacy infrastructure—Cloud will apply any pending [Project Config](/docs/5.x/system/project-config.html) updates (say, from changing your filesystems’ configuration) at the end of the deployment. + +### Preview Domains + +Your project automatically gets a [preview domain](/knowledge-base/cloud-domains#preview-domains) to validate your configuration and content before going live. + +## Launch + +When it comes time to launch, there are likely three steps you’ll need to take: + +1. Configure a domain; +2. Import new content; +3. Reapply migrations and project config; + +Read about [using custom domains with Craft Cloud](/knowledge-base/cloud-domains) to prepare for the required DNS changes, or review a more complete [launch checklist](/knowledge-base/cloud-launch-checklist). + +The exact process will differ based on your project’s tolerance of downtime—but generally, it’s a good idea to put your existing site into [maintenance mode](/5.x/reference/cli.html#off), export and re-import the database (and upload new assets), then run a final deployment. + +::: tip +The AWS S3 CLI’s `sync` command is extremely useful for [uploading](/knowledge-base/cloud-assets) only new and modified assets. Consider running it periodically in your local environment to keep your content up-to-date—it also works when _uploading_ large asset libraries to your Cloud environment! +::: + +With your latest code and content on Cloud, [disable maintenance mode](/docs/5.x/reference/cli.html#on) and [update your DNS](/knowledge-base/cloud-domains) to point your live domain at our infrastructure! + +More information about launching projects on Cloud is available in the [Going Live](/knowledge-base/cloud-launch-checklist) article. diff --git a/docs/cloud/plugin-development.md b/docs/cloud/plugin-development.md new file mode 100644 index 000000000..748611b9f --- /dev/null +++ b/docs/cloud/plugin-development.md @@ -0,0 +1,98 @@ +# Plugin Development + +As long as your plugin’s design and implementation follows our established [best practices](/docs/5.x/extend/index.html), it should work on Craft Cloud without changes. All Craft features are available on Cloud, making the platform’s architectural differences inconsequential when using official, documented APIs. + +Plugins must be compatible with at least Craft 4.6 (the minimum version of Craft required to run on Cloud), but they may support earlier versions. + +::: tip +Want to test your plugin on Cloud? [Get in touch](/contact) for a free sandbox environment! +::: + +## Special Considerations + +There are still a few things about Craft Cloud that may require reevaluation of some assumptions about how web applications are run. The Cloud module and Craft itself provide everything you need to make your plugin reliable and resilient across the widest possible variety of hosting platforms. + +### Ephemeral Filesystem + +Craft Cloud sets the `CRAFT_EPHEMERAL` config override, which tells Craft to treat file writes as unreliable (or downright impossible). Plugins should honor this setting by checking `craft\helpers\App::isEphemeral()` before trying to perform any writes to the disk. + +If you must write files to disk, use the temporary directory determined by the system. **Do not hard-code this path or construct it dynamically.** Instead, use Craft’s [`Path` service](https://docs.craftcms.com/api/v5/craft-services-path.html) to get information about system directories’ locations: + +```php +$path = Craft::$app->getPath(); + +$tmp = $path->getTempPath(); +$storage = $path->getStoragePath(); +$cache = $path->getCachePath(); + +// ... +``` + +#### Logs + +Avoid writing logs directly to a file, as its contents will disappear as soon as the request ends. Always use the `Logger` component (`Craft::$app->getLogger()`) or the static `Craft::info()`, `Craft::warning()`, and `Craft::error()` convenience methods to ensure logs are sent to Cloud’s custom log target. + +### File Responses + +The Cloud extension automatically handles binary responses (like when a controller action ends with [`sendContentAsFile()`](https://docs.craftcms.com/api/v5/craft-web-response.html#method-sendcontentasfile)) by uploading the data to S3 and redirecting to a pre-signed URL. + +In general, we recommend _not_ sending binary responses that could otherwise be served as a static asset via [asset bundles](#asset-bundles)—the only situations in which Craft should be involved is when the data is based on some user input, like a dynamically-generated ZIP or PDF. Additionally, pre-signed URLs are unnecessary (and extremely inefficient) for files whose contents are static, predictable, or non-private. + +If you do need to customize the delivery of binary data, Cloud’s web runtime is implicitly authorized to interact with its environment’s storage bucket—see the Cloud module for [an example of how we get a URL](https://github.com/craftcms/cloud-extension-yii2/blob/2.x/src/web/ResponseEventHandler.php) to an uploaded object. + +### Asset Filesystems + +While we recommend that projects on Cloud use our first-party [Cloud filesystem](/knowledge-base/cloud-assets), it is not a requirement. Plugins that provide filesystem types may need to implement a custom uploader to send binary files directly to the storage provider (rather than POST them to the Craft application itself). + +The Cloud filesystem’s [client-side](https://github.com/craftcms/cloud-extension-yii2/blob/2.x/src/web/assets/uploader/UploaderAsset.php) and [server-side](https://github.com/craftcms/cloud-extension-yii2/blob/2.x/src/controllers/AssetsController.php) code is available for reference. + +### Other File Uploads + +In situations where you need a file from a user (like a plugin that works with CSVs), consider providing an asset selection input, instead: + +```twig +{% import forms from '_includes/forms' %} + +{{ forms.elementSelect({ + name: 'file', + elementType: 'craft\\elements\\Asset', + limit: 1, +}) }} +``` + +Doing so will take advantage of the existing volumes and filesystems, while still providing access to the underlying file’s content via `craft\elements\Asset::getStream()`. + +### Asset Bundles + +Craft Cloud pre-publishes all known asset bundles to our CDN at [build-time](/knowledge-base/cloud-builds) to conserve compute resources. + +Any static assets your plugin provides to the control panel or front-end must be encapsulated in an [Asset Bundle](/docs/5.x/extend/asset-bundles.html), and its `sourcePath` must begin with your plugin’s predefined alias. To register an asset bundle, call `Craft::$app->getView()->registerAssetBundle($myBundle)` from a controller or template. Publishing one-off or ad-hoc assets at runtime is **not** supported on Cloud. + +Asset bundles have some additional requirements: + +- Bundle classes must be instantiable _even if Craft is not installed_, or cannot connect to a database. Plugin settings and other system state may be unavailable to the build environment when we are publishing assets. +- Your plugin’s main `composer.json` should always have a `type` of `craft-plugin`, and any downstream packages containing asset bundles (i.e. utilities shared by multiple plugins) must have a `type` beginning with `craft` or `yii` to be picked up by our publishing routine. + +### Sessions + CSRF + +To help support Cloud’s [static caching](/knowledge-base/cloud-static-caching) system, avoid interacting with the session unnecessarily, during _site_ requests. + +Always use the [`csrfInput()` Twig function](/docs/5.x/reference/twig/functions.html#csrfinput) when rendering front-end forms to maintain compatibility with Craft’s [`asyncCsrfInputs` config setting](/docs/5.x/reference/config/general.html#asynccsrfinputs) (4.9.0+). _Building an input manually (or using `craft\web\Request::getCsrfToken()` directly) can leak one user’s CSRF tokens to another!_ + +## Other Best Practices + +Plugins that already embrace our existing [coding guidelines and best practices](/docs/5.x/extend/coding-guidelines.html) should be Cloud-ready—or take significantly less time to make compatible. + +In addition, these tips can help avoid hiccups when your plugins are deployed to Craft Cloud: + +- Implement batched jobs if your workload is [apt to exceed 15 minutes](/knowledge-base/cloud-quotas). It is often better to spawn many small jobs than a single long-running one. +- Don’t set cookies unless absolutely necessary—like in response to a user action. + - If possible, register JavaScript to fetch CSRF tokens *asynchronously*. Using `{{ csrfInput() }}` in a template outside the control panel will immediately set a cookie and prevent [static caching](/knowledge-base/cloud-static-caching). + +## Publishing Your Plugin + +Cloud-compatible plugins go through the same [submission and approval process](https://craftcms.com/docs/5.x/extend/plugin-store.html) as regular plugins. Once you’ve verified your plugin works on Cloud, be sure and check the **Tested on Craft Cloud** in its management screen on [Craft Console](https://console.craftcms.com/)! + +## Getting Help + +Please [reach out to us](/contact) if you have questions about your plugin’s compatibility. diff --git a/docs/cloud/private-packages.md b/docs/cloud/private-packages.md new file mode 100644 index 000000000..c11c1603d --- /dev/null +++ b/docs/cloud/private-packages.md @@ -0,0 +1,22 @@ +# Private Packages + +Craft Cloud supports private Composer packages with all the native authentication methods. + +::: tip +Read about Composer’s authentication system in the [official documentation](https://getcomposer.org/doc/articles/authentication-for-private-packages.md). +::: + +When you deploy a site that requires private packages, Cloud will use credentials provided via the project’s **Settings** → **Composer Auth** screen. + +Once you’ve added a username, password, or token, it cannot be retrieved—the values are only decrypted in our build pipeline when installing dependencies. + +## Auth Methods + +We currently support the following [authentication methods](https://getcomposer.org/doc/articles/authentication-for-private-packages.md#authentication-methods): + +- GitHub Token +- HTTP Basic +- Gitlab Token +- Gitlab OAuth +- Bitbucket OAuth +- HTTP Bearer diff --git a/docs/cloud/project-management.md b/docs/cloud/project-management.md new file mode 100644 index 000000000..a97bb2e0e --- /dev/null +++ b/docs/cloud/project-management.md @@ -0,0 +1,39 @@ +# Managing Projects + +Craft Cloud projects are always created via [Craft Console](/knowledge-base/what-is-craft-console). You can start projects with your [personal account](/knowledge-base/craft-console-organizations#individual-private-accounts), or within an [organization](/knowledge-base/craft-console-organizations#organizations). + +We generally recommend organizations for Cloud projects, as they support delegated access and other features that underpin safe collaboration. + +## Creating a Project + +Log in to your Craft Console account, then click **Cloud** in the main navigation. If this is your first project, you’ll see a welcome screen and a **New project** button; existing Cloud users will see a list of current projects. + +Use the menu in the upper-right corner to switch between your personal account and the organizations you are a member of. You must have a [payment method](/knowledge-base/craft-console-organizations#managing-payment-information) on file (in the current account context) to start a Cloud trial. + +Within an organization, only owners and administrators can create projects. If you don’t have adequate permissions, get in touch with the person who created the organization. + +## Project Ownership + Collaboration + +Projects owned by a personal account can only be managed via that account. **You cannot transfer a project to an organization after it is created.** + +If you suspect that a project will ever be supported by someone other than you, create an organization for it. Organizations are free, and provide a perfect place to consolidate a client or firm’s projects and licenses. + +::: warning +The Craft Console users who can access your project are not associated with the users in your Craft site, and vice-versa. It’s important to be aware, though, that anyone with access to your Cloud project can get access to its database and run commands that alter Craft users’ permissions. +::: + +Projects are billed to the primary payment method on file for the personal account or organization that owns it. + +### Inviting a User + +Read about [inviting users](/knowledge-base/craft-console-organizations#inviting-members-to-an-organization) in our Using Organizations article. + +## Connecting a Repository + +When creating a project, you will be asked to connect to a Git provider. + +This connection is established for your *personal* account, even if the project will be owned by an organization. Cloud interacts with the provider on behalf of anyone managing the project, after the authorization is granted. + +Whoever sets up a project must have the correct permissions at the provider (and grant access to any additional scopes) when establishing the connection. + +Follow [this guide](/knowledge-base/cloud-troubleshooting) if you need to reauthorize a provider. diff --git a/docs/cloud/quotas.md b/docs/cloud/quotas.md new file mode 100644 index 000000000..9483e365f --- /dev/null +++ b/docs/cloud/quotas.md @@ -0,0 +1,81 @@ +# Resource Limits + +Every Craft Cloud project comes with generous resource quotas and simple, predictable [pricing](/cloud#pricing). + +## Environments + +Projects are given three [environments](/knowledge-base/cloud-environments), one of which may be selected as the [production environment](/knowledge-base/cloud-environments#production-environment). You cannot currently purchase additional environments, but you may delete and recreate them whenever you need. + +## Storage + +We do have a couple of limits in place for storage to prevent platform abuse: + +- Each environment in a **Pro** project gets 20GB of asset storage; **Team** project environments get 10GB. +- Individual files are limited to 200MB; + +There are no limits on page views, database size, inbound transfer, or the number of content types, plugins, users, entries, or assets you manage within Craft CMS itself, beyond what is allowed by your [license](#craft-license). + +## Bandwidth + +Outbound transfer from your application and asset storage bucket are metered. + +If a response can be served from our edge (like a [statically-cached](/knowledge-base/cloud-static-caching) HTML document, an [image transform](https://craftcms.com/knowledge-base/cloud-assets#transforms), or any previously-requested asset or [build artifact](/knowledge-base/cloud-builds)), it does _not_ count toward your monthly bandwidth: + +- **Team** projects get 250GB of transfer per month, shared between environments. +- **Pro** projects get 500GB of transfer per month, shared between environments. + +All transfer from our edge and CDN to your clients is free. Most projects will not need to do anything to take advantage of our edge cache, but you can optimize your cache-hit ratio by following our [static caching guide](/knowledge-base/cloud-static-caching), and limit asset egress by creating thoughtful [named asset transforms](/docs/5.x/development/image-transforms.html). + +The following table shows some common resource sizes, and an approximation of the number of uncached requests that fit within the **Team** plan’s bandwidth quota: + +Media Type | Typical Size | Requests +--- | --- | --- +HTML Document | 30KB ([Source](https://almanac.httparchive.org/en/2022/markup#document-size)) | 8,000,000 +Image | 1MB ([Source](https://almanac.httparchive.org/en/2022/media#bytesizes)) | 250,000 +Resized Image | 350KB | ~700,000 + +These numbers do not represent any actual enforced limits on file sizes or number of requests—they are provided strictly as a means to compare against current or forecasted usage. + +::: tip +Keep in mind that each image will only be loaded from the origin _once_ unless they are replaced or modified such that the CDN must be purged. Effectively, your project would only approach these limits if it had many tens of thousands of unique assets that were each requested for the first time in a given month! +::: + +## Domains + +One [custom domain](/knowledge-base/cloud-domains) is included with every project. You may add as many subdomains as you need, but additional domains are billed at $20 per month. Adding a domain part way through a billing period immediately bills a prorated amount to the payment method on file. + +## Requests + Responses + +While we don’t impose limits on the *number* of total or concurrent requests, it’s important that they each finish within 60 seconds. Responses with _headers_ exceeding 16,000 bytes (total) may be dropped, so avoid sending long identifiers or setting large cookie values. If you need to associate a significant amount of data with a visitor, consider using the cache or a database table and tying it to the session by ID. + +Additionally, the maximum total response length is 6MB, before compression (regardless of its `Content-Type`). The average HTML document size is [about 30KB](https://almanac.httparchive.org/en/2022/markup#document-size), or roughly 0.5% of our cap—so very few sites and apps should be impacted. + +Asset uploads from the Craft control panel are _not_ subject to this 6MB limit, as they are uploaded directly to your bucket and served from our CDN. Asset uploads from the site’s front end are subject to this limit unless you provide a way to upload them directly to your bucket from the front end (similar to how the Craft control panel does it). + +Build artifacts are also _not_ subject to this limit, as they are served from our CDN. + +## Builds and Commands + +You can [deploy](/knowledge-base/cloud-deployment) as often as you like. There are no limits on the total number of “build minutes” per billing period, but each [build](/knowledge-base/cloud-builds) must complete within **15 minutes**. + +A brand new [starter project](/knowledge-base/using-the-starter-project) will typically deploy in about 90 seconds. Projects that use many plugins or have complex Node build steps will naturally take more time—long-running processes like automated tests may need to be offloaded to a different CI pipeline. + +The final [migration](/docs/5.x/deploy.html#migrate) phase of each deployment does *not* count toward the build time limit, but _are_ governed by the discrete command duration limit. + +Commands must complete within **15 minutes**, as well. This applies to automatically-triggered commands (like migrations) as well as those run manually from an environment’s **Commands** screen. + +Deployments and commands report their elapsed time (during execution), and store their final duration (when they complete or fail). + +::: warning +Migrations for major Craft or plugin version upgrades can sometimes exceed this limit on large sites. Test those upgrades locally before deploying to Cloud to get a sense for the total time required. +::: + +## Queue + +There are no limits to the number of concurrent or monthly queue jobs, but—like builds and commands—each job must be completed within **15 minutes**. For long-running tasks, plugin developers should implement `craft\queue\BaseBatchedJob` so that jobs can be [gracefully batched](/docs/5.x/extend/queue-jobs.html#batched-jobs) as that timeout approaches. + +## Craft License + +The included Craft Pro or Team license is valid as long as your project is active on Cloud, and is not transferrable to a self-hosted installation. Otherwise, its terms are identical to a normal Craft license—there are no additional restrictions on the variety or quantity of content you manage with the installation, nor the size of your audience. Cloud is subject to our [Acceptable Use Policy](/acceptable-use-policy). + +Plugin licenses are *not* included with your Cloud subscription and will need to be purchased separately. diff --git a/docs/cloud/regions.md b/docs/cloud/regions.md new file mode 100644 index 000000000..85c6a2a75 --- /dev/null +++ b/docs/cloud/regions.md @@ -0,0 +1,34 @@ +# Regions + +Craft Cloud is currently available in **North America**, **Canada**, **Europe**, and **Asia/Pacific**. You select a region when creating a new project. + +A project’s region determines where your [database](/knowledge-base/cloud-databases) and compute resources are located, but *not* your assets. + +## Choosing a Region + +Your project should live in the same region that your client (or your client’s audience) is in. Projects cannot be moved between regions, but you are welcome to deploy different projects in different regions. + +Cloud pricing is consistent across regions. + +### Caching + +The primary incentive to select a region is a reduction in latency for your audience and administrators. This typically only impacts uncached or dynamic responses that reach your application (like control panel requests). Any request that can be served from our global edge cache or CDN (like statically-cached HTML documents, build artifacts, and assets) will generally *not* be impacted by your selection. + +## Data Custodianship + +We encourage all customers to research their country’s data transfer laws. Craft Cloud’s management layer is deployed in the United States, but your project’s compute resources and database are always located in the chosen region. Assets uploaded to Cloud filesystems cannot be kept in a single region, by virtue of the underlying infrastructure’s geographic redundancy and delivery network. + +## Datacenter Geography + +Our region-specific infrastructure lives in these countries: + +- **North America**: United States +- **Canada**: Canada +- **Europe**: Germany +- **Asia/Pacific**: Australia + +## Timezones + +Craft Cloud’s entire infrastructure uses UTC clocks. Select the appropriate timezone (in **Settings** → **General**) when setting up your Craft installation to display date information correctly for your region. Dates in the database are stored in the system’s timezone. + +[Backups](./backups.md) are captured nightly, respective of your chosen region. diff --git a/docs/cloud/static-caching.md b/docs/cloud/static-caching.md new file mode 100644 index 000000000..64e94e900 --- /dev/null +++ b/docs/cloud/static-caching.md @@ -0,0 +1,246 @@ +# Static Caching + +All of Craft’s default caching features work as you would expect on Craft Cloud. + +To supplement this, we provide a static caching system that automatically detects (and purges!) cacheable HTML responses. These static page caches are created and invalidated using the same mechanism as Craft’s own template caches—so any time an element is updated, Cloud knows exactly which pages to purge. + +By default, only 200-level GET responses are candidates for static caching; redirection and errors (300-level and higher) are _not_ cached, unless you [explicitly opt in](#force-caching). + +## Static Cache vs. Template Caches + +Cloud’s static cache operates on *full pages*, which means that either the entire page is cached, or the entire page is served by your application. Whether you use additional caching strategies in your templates or back-end is up to you! + +Craft’s built-in `{% cache %}` tag can be combined with static caching—but because the caches are invalidated at the same time, they may be redundant. If you have a highly-dynamic front-end that isn’t possible to cache statically, the normal template cache system is still a great option for caching parts of a page. + +Most Craft features that rely on dynamic rendering are already set up to bypass the cache, including the entire control panel, live preview, any front-end pages that use the session or cookies. [Asynchronous CSRF](#csrf) can be enabled in Craft to make most front-end forms cachable. + +## Controlling the Cache + +The request’s entire URL (including query parameters) is used when determining whether to serve a page from the cache. + +In Craft versions 4.10 and 5.2, the [`expires` Twig tag](/docs/5.x/reference/twig/tags.html#expires) was introduced to simplify setting cache headers. Examples are provided below for this method as well as precise control of individual headers via the [`header` tag](/docs/5.x/reference/twig/tags.html#header). + +### Force Caching + +If you suspect requests are _missing_ the static cache (despite meeting the criteria above), and you know that a page _should_ be cacheable, you can explicitly send cache headers: + +```twig +{% expires in 30 minutes %} + +{# ...or prior to Craft 4.10 and 5.2... #} + +{% set halfHour = 60 * 30 %} +{% do craft.app.response.setCacheHeaders(halfHour) %} +``` + +Craft always sends the appropriate cache invalidation tags so that the page can be purged, later. + +::: warning +Manually caching a page in this way _can_ leak user-specific information. This is only appropriate for use when you are absolutely sure that a page includes no personal details or customizations! +::: + +### Opting Out + +You can explicitly flag a template or response as being _ineligible_ for full-page caching: + +```twig +{# Set “no-cache” headers by omitting a duration: #} +{% expires %} +``` + +In PHP, use the `Response` component available from any [controller](/docs/5.x/extend/controllers.html): + +```php +public function actionSaveWidget(): Response +{ + // ... + + $this->response->setNoCacheHeaders(); +} +``` + +This method also sets `Expires` and `Pragma` headers. When using the `expires` tag without any arguments, it ultimately calls the same function: + +```twig +{% do craft.app.response.setNoCacheHeaders() %} +``` + +## Duration + +The Cloud extension uses the same source of information as Craft when determining how long to statically cache a page (if it is cachable at all). This means that pages using elements with an **Expiry Date** sooner than the default [`cacheDuration` setting](/docs/5.x/reference/config/general.html#cacheduration) will only be cached as long as all the underlying content ought to be visible. As with Craft’s template caches system, there is not currently a mechanism in place to invalidate caches that _would_ contain elements with a future **Post Date**. + +If you have [manually set cache headers](#force-caching) at some point in the request, Craft will not overwrite those headers. + +::: tip +Previously, we used the Twig `{% header %}` tag to set the `Cache-Control` header. This is fine in situations where the template can dictate the final value of a header—but tagging pages for Cloudflare’s cache must be done _additively_ with the response’s [header collection](https://www.yiiframework.com/doc/guide/2.0/en/runtime-responses#http-headers), without replacing ones that may have been set earlier in the request. +::: + +## Manual Purging + +If you would like to clear your environment’s entire static page cache, visit the **Utilities** screen, check **Cloud Static Caches**, then **Clear Caches**. + +To clear a specific cache tag, use the CLI via the environment’s **Commands** screen: + +```bash +php craft cloud/static-cache/purge-tags tag-one tag-two +``` + +You can also directly purge URLs by one or more URL path prefix: + +```bash +php craft cloud/static-cache/purge-prefixes /vendors /listings +``` + +## Session & Cookies + +Using any functionality that relies on cookies will prevent a response from being cached. The following sections cover some common Craft features that involve the session and cookies. + +If you suspect a page is not being cached, look for a `Set-Cookie` header in the response, and check the [troubleshooting](#troubleshooting) section. + +### Users + +The `{% requireLogin %}`, `{% requireGuest %}`, `{% requireAdmin %}`, and `{% requirePermission %}` [Twig tags](/docs/5.x/reference/twig/tags.html) all use session data to dynamically redirect users. + +Reading the [`currentUser` variable](/docs/5.x/reference/twig/global-variables.html) does not implicitly start a session, and may result in the logged-out state of a page being cached. Any pages you anticipate including personalized content (like user dashboards) should include the [`{% expires %}` tag](#opting-out) so that they are excluded from the cache, or lazily fetch session-dependent regions [via Ajax](#including-via-ajax). + +### CSRF + +Use Craft’s [`asyncCsrfInputs` setting](/docs/5.x/reference/config/general.html#asynccsrfinputs) to make CSRF inputs generated with the [`csrfInput()` Twig function](/docs/5.x/reference/twig/functions.html#csrfinput) compatible with the static cache. Instead of outputting the `input` element and token directly (therefore opening a session), a placeholder is rendered and replaced after the browser/client loads the page and fetches a CSRF token via Ajax. + +You can also opt in to asynchronous CSRF inputs on a case-by-case basis: + +```twig +
    + {{ csrfInput({ async: true }) }} + + {# ... #} +
    +``` + +Avoid calling `craft.app.request.getCsrfToken()` directly, or manually building CSRF inputs. No-cache headers will be sent, _regardless of how you generate or access a token_! This means that outputting a CSRF token in the `` of every page (say, to avoid them being cached in a `{% cache %}` tag later in the document) will make it ineligible for static caching. + +### Flashes + +Any time you access session-dependent information like [flashes](/docs/5.x/development/forms.html#flashes), Craft sends no-cache headers. Form submissions via POST are never cached and will therefore re-render the page with any contextual [validation errors](/docs/5.x/development/forms.html#models-and-validation) as you would expect—but when the form itself is otherwise cachable (including using [asynchronous CSRF tokens](#csrf)), you can guard flash messages with a check for a flag: + +```twig +{# Access session data only when the `success` query param is set: #} +{% if craft.app.request.getQueryParam('success') %} + {% set flashes = craft.app.session.getAllFlashes(true) %} + + {% if flashes|length %} + {% for level, flash in flashes %} +

    {{ flash }}

    + {% endfor %} + {% endif %} +{% endif %} + +
    + {{ actionInput('entries/save-entry') }} + {{ csrfInput({ async: true }) }} + + {# Append a query parameter to the final redirection: #} + {{ redirectInput(url(craft.app.request.url, { success: true })) }} + + {# ... #} +
    +``` + +This allows Cloud to cache the form when it is initially requested, while always triggering no-cache headers after a submission by reading flashes from the session. + +### Commerce + +Any time you access a customer’s cart via `craft.commerce.carts.cart`, Commerce either reads or writes a [cart number](/docs/commerce/5.x/system/orders-carts.html#order-numbers) to the session. This is not apt to be a problem on pages that only on-session users will access (like the cart, checkout, or account), but it can mean that common ecommerce patterns make your site more difficult to conform with the expectations of Cloud’s static cache. + +In particular, displaying dynamic cart data on _every_ page (say, in the site’s header) means that Cloud will be unable to cache your site. See the [Including via Ajax](#including-via-ajax) section to learn about a technique that can help retain these dynamic sections of your site! + +## Dynamic Pages + +Pages that rely on dynamic content but don’t necessarily access session data are apt to be cached without some intervention. + +For example, shuffling, sorting, or querying records based on random values (i.e. `.orderBy('RAND()')`) do _not_ use the session, and cannot be detected by Cloud. If you wish to show randomized content on a page, you may need to [explicitly send no-cache headers](#controlling-the-cache), or reorder content with JavaScript, in the client. + +### Including via Ajax + +Dynamic or session-dependent sections of a page can be fetched asynchronously, while allowing the bulk of a page to be cached. + +Suppose you have a Commerce storefront on Cloud, and you want to make your homepage and cart pages fast, but still include information about the customer’s cart. Suppose you have this in your site’s header or layout: + +```twig +
    +

    {{ siteName }}

    +
    + Cart + + {# Register a JavaScript fragment: #} + {% js %} + const $count = document.getElementById('cart-count'); + + fetch('/ajax/components/cart-count') + .then(r => r.text()) + .then(html => $count.innerHTML = html); + {% endjs %} +
    +
    +``` + +This template doesn’t depend on the session, so Cloud would be able to cache it normally. When the page arrives in a customer’s browser, though, it fetches another HTML fragment via Ajax: + +```twig +{% set total = craft.commerce.carts.cart.totalQty %} + +{{ total }} {{ total == 1 ? 'item' : 'items' }} +``` + +Similarly, the templates for a randomized carousel might look like this: + +```twig + + +{# Essentially the same JavaScript fragment: #} +{% js %} + const $carousel = document.getElementById('carousel'); + + fetch('/ajax/components/carousel') + .then(r => r.text()) + .then(html => $carousel.innerHTML = html); +{% endjs %} +``` + +```twig +{# Send no-cache headers so this is always dynamic: #} +{% expires %} + +{% set slides = craft.entries() + .section('heroSlides') + .orderBy('RAND()') + .limit(5) + .all() %} + +{% for slide in slides %} +
    + {# ... #} +
    +{% endfor %} +``` + +As long as you can isolate these “islands” of state-dependent or dynamic markup in their own templates, you will be able to retrieve them later over Ajax. This is functionally distinct from a Twig `include` because the logic is never run during the main request; instead, it’s deferred to a second, lighter-weight request. + +## Troubleshooting + +You can check whether a response was served from the cache by examining its HTTP headers. A `HIT` value in the `cf-cache-status` header indicates that we were able to serve a statically-cached version of the page: + +``` +cf-cache-status: HIT +``` + +A `MISS` value on the other hand can mean two things: + +- The page was not found in the cache, so it was served from the origin; +- The response served from the origin included headers that prevented it from being cached; + +Of course, every page must be requested from the origin at least once for it to be present in the cache—so a `MISS` is not always indicative of a problem! If you observe repeated misses, you may need to audit your templates for use [features that involve the session and cookies](#session-cookies)—the most common offenders will result in a `Set-Cookie` header being sent. + +It's important to note that these conditions only apply to requests that would be served by Cloud’s compute layer. Requests for assets (including transforms) also go through our edge, but are governed by different rules and typically out of your control. diff --git a/docs/cloud/troubleshooting.md b/docs/cloud/troubleshooting.md new file mode 100644 index 000000000..8bb3d61da --- /dev/null +++ b/docs/cloud/troubleshooting.md @@ -0,0 +1,40 @@ +# Troubleshooting Common Problems + +### Why is my repository not showing up when starting a new project? + +When creating a project, we show you repositories you have access to through Git providers connected to your *personal* Craft Console account. If the repository is owned by someone else (even if they're a member of the same Craft Console organization), it may not be discoverable. Here are a few things to check: + +- Was the repository forked from another repository? We can only deploy from “upstream” repositories (those that are _not_ forks). +- Did you create or push code after reaching this screen? You may need to refresh the page, or wait a few minutes for the repository to be available in the API. +- Are you viewing the correct organization or context? Use the menu to the left of the search bar to switch providers and contexts. + +If none of the above work, you may need to reconnect the platform to Craft Console and grant additional permissions: + +1. Switch to your personal account with the menu in the upper-right corner; +2. Go to **Settings** (the gear icon in the upper-right corner), then **Integrations**; +3. Click **Disconnect** on the row with your Git provider; +4. Log in to your Git provider, and remove the app or integration: + - On GitHub, Craft Cloud is registered as an “OAuth App,” and can be managed in your account’s **Settings** → **Applications** → **Authorized OAuth Apps** screen. Click the three dots in the **Craft Cloud** row, then select **Revoke**. + - Instructions for other providers will be added as we roll out support! + +Return to the **Integrations** screen in your personal Craft Console account, then click **Connect**. Carefully review the permissions, and ensure that the organization your repository lives in is properly authorized. On GitHub, this means that it will either either have a green check mark ✓ next to it, or that you've clicked **Grant** in that row. If the organization only displays a **Request** button, you may need to contact one of the administrators for access. + +### Why did my build/deployment fail? + +Build failures always display an error in that [deployment](/knowledge-base/cloud-deployment)’s details page. If you believe you've encountered a temporary failure, you can try redeploying the latest commit by clicking **Deploy**—even if the environment is set to deploy **On Push**. + +The most common problems are: + +- **Issues cloning the repository.** Was it made private, renamed, or otherwise disconnected? +- **No PHP version was declared.** Make sure you have a `php-version` key in your [`craft-cloud.yaml` config file](/knowledge-base/cloud-config). +- **Unsupported software or package versions.** + - Your Cloud config file must include a `php-version`, set to a public release of PHP, version {globalset:productVitals:custom_cloudMinPhpVersion} or later. Patch versions are not supported. + - If you are using Node, `node-version` must be set to {globalset:productVitals:custom_cloudMinNodeVersion} or higher. Only major version numbers are supported. + - Craft CMS version {globalset:productVitals:vitalsCloudMinCraftVersion} or later is required. + - `craftcms/cloud` version {globalset:productVitals:vitalsCloudMinExtensionVersion} or later is required. +- **Errors when installing Composer packages.** Do you have a valid `composer.json` and `composer.lock` file in the connected repository? (It's technically possible—but exceedingly rare—for there to be connectivity issues when downloading packages. Check your logs, try again, or reach out to support if you continue to have problems at this stage in the build.) +- **Failures in the Node/NPM build script.** Something went wrong when installing your Node modules or while running the `build` script. Read more about the [build process](/knowledge-base/cloud-builds) and how we determine [what build script is run](/knowledge-base/cloud-config). + +Cloud will report specific errors that fall into one of these categories. Some errors may require that you investigate the build logs, which are also available in the deployment screen; the step that failed will display a red X. + +If you continue to have issues with a specific project, environment, or commit, [get in touch](https://craftcms.com/contact)! From 4506af3ecb44eab72aaf162b7669c0e978dc8609 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 08:40:11 -0700 Subject: [PATCH 02/13] Replace local KB links --- docs/cloud/assets.md | 10 ++++---- docs/cloud/billing.md | 2 +- docs/cloud/builds.md | 18 +++++++------- docs/cloud/clients.md | 4 +-- docs/cloud/compatibility.md | 18 +++++++------- docs/cloud/config.md | 10 ++++---- docs/cloud/databases.md | 8 +++--- docs/cloud/deployment.md | 4 +-- docs/cloud/domains.md | 10 ++++---- docs/cloud/environments.md | 12 ++++----- docs/cloud/extension.md | 8 +++--- docs/cloud/faq.md | 42 ++++++++++++++++---------------- docs/cloud/getting-started.md | 30 +++++++++++------------ docs/cloud/launch-checklist.md | 12 ++++----- docs/cloud/local-dev.md | 14 +++++------ docs/cloud/migrating.md | 32 ++++++++++++------------ docs/cloud/plugin-development.md | 10 ++++---- docs/cloud/project-management.md | 2 +- docs/cloud/quotas.md | 10 ++++---- docs/cloud/regions.md | 2 +- docs/cloud/troubleshooting.md | 6 ++--- 21 files changed, 132 insertions(+), 132 deletions(-) diff --git a/docs/cloud/assets.md b/docs/cloud/assets.md index 06ec2ab11..0bf51cf97 100644 --- a/docs/cloud/assets.md +++ b/docs/cloud/assets.md @@ -1,8 +1,8 @@ # Assets -Each of the environments in your Craft Cloud projects come with a generous [storage quota](/knowledge-base/cloud-quotas). +Each of the environments in your Craft Cloud projects come with a generous [storage quota](quotas.md). -To take advantage of that storage (and other features, like the built-in CDN and [image transform](#transforms) service), you must use the [Cloud extension](/knowledge-base/cloud-extension)’s built-in filesystem type. +To take advantage of that storage (and other features, like the built-in CDN and [image transform](#transforms) service), you must use the [Cloud extension](extension.md)’s built-in filesystem type. ## New Filesystems @@ -91,7 +91,7 @@ aws s3 sync --delete s3://{project-uuid}/{environment-uuid}/assets/ ./web/craft- ``` ::: tip -For projects with large asset libraries (especially those over our soft 15GB per-environment [limit](/knowledge-base/cloud-quotas)), consider reaching out to us for recommendations about importing directly from other platforms. Credentials last for 1 hour—but as long as you use the `sync` command, it will be able to pick up where it left off. +For projects with large asset libraries (especially those over our soft 15GB per-environment [limit](quotas.md)), consider reaching out to us for recommendations about importing directly from other platforms. Credentials last for 1 hour—but as long as you use the `sync` command, it will be able to pick up where it left off. ::: ### Copying Assets Between Environments @@ -100,9 +100,9 @@ Automated environment duplication/synchronization is a planned feature of Cloud. ## Transforms -The [Cloud extension](/knowledge-base/cloud-extension) transparently enhances Craft’s [asset transform](/docs/5.x/development/image-transforms.html) APIs by generating and caching images at the edge, using special pre-signed URLs. Existing transforms will work seamlessly on Cloud, whether predefined via [named transforms](/docs/5.x/development/image-transforms.html#applying-named-transforms-to-images) and as [ad-hoc transforms](/docs/5.x/development/image-transforms.html#defining-transforms-in-your-templates) (except for one [limitation](#limitations), noted below). +The [Cloud extension](extension.md) transparently enhances Craft’s [asset transform](/docs/5.x/development/image-transforms.html) APIs by generating and caching images at the edge, using special pre-signed URLs. Existing transforms will work seamlessly on Cloud, whether predefined via [named transforms](/docs/5.x/development/image-transforms.html#applying-named-transforms-to-images) and as [ad-hoc transforms](/docs/5.x/development/image-transforms.html#defining-transforms-in-your-templates) (except for one [limitation](#limitations), noted below). -These images don’t contribute to your [storage quota](/knowledge-base/cloud-quotas), and there are no limits on the number of transforms or compute time. +These images don’t contribute to your [storage quota](quotas.md), and there are no limits on the number of transforms or compute time. ### Content Negotiation diff --git a/docs/cloud/billing.md b/docs/cloud/billing.md index e71b2fd8a..61ee26a79 100644 --- a/docs/cloud/billing.md +++ b/docs/cloud/billing.md @@ -8,7 +8,7 @@ Like the Plugin Store and Developer Support plans, all Craft Cloud payments are You must have a valid payment method on file to start a seven-day trial of Craft Cloud, but you will not be billed until the end of the trial. If you cancel prior to your first bill, you will not be charged for any services. -Trials provide access to all Cloud features, except for custom domains. Connecting a custom domain will prompt you to skip the trial and immediately start a subscription. Either way, you always have access to a [preview domain](/knowledge-base/cloud-domains). +Trials provide access to all Cloud features, except for custom domains. Connecting a custom domain will prompt you to skip the trial and immediately start a subscription. Either way, you always have access to a [preview domain](domains.md). ## Personal Accounts + Organizations diff --git a/docs/cloud/builds.md b/docs/cloud/builds.md index 0057b67cc..7b982cc34 100644 --- a/docs/cloud/builds.md +++ b/docs/cloud/builds.md @@ -1,20 +1,20 @@ # Build Pipeline and Artifacts -As part of every [deployment](/knowledge-base/cloud-deployment), Craft Cloud assembles all the code and configuration required to run your PHP application and build front-end assets. +As part of every [deployment](deployment.md), Craft Cloud assembles all the code and configuration required to run your PHP application and build front-end assets. -Everything about the build process is dictated by your repository, and [the `craft-cloud.yaml` config file](/knowledge-base/cloud-config). +Everything about the build process is dictated by your repository, and [the `craft-cloud.yaml` config file](config.md). ## PHP -Your project’s `composer.json` and `composer.lock` files determine what PHP packages are installed. By default, Cloud expects both files to be at the root of your repository—but your Composer root can be [customized](/knowledge-base/cloud-config#config-schema). If either file is missing, the build will fail. +Your project’s `composer.json` and `composer.lock` files determine what PHP packages are installed. By default, Cloud expects both files to be at the root of your repository—but your Composer root can be [customized](config.md#config-schema). If either file is missing, the build will fail. Cloud installs packages by running `composer install`. ## Node -Similarly, Cloud looks for `package.json` and `package-lock.json` files at the root of your repository (or at a path set in your [config file](/knowledge-base/cloud-config#config-schema)). Unlike the PHP build step, if `package-lock.json` is *missing*, this step is skipped and the deployment will continue. +Similarly, Cloud looks for `package.json` and `package-lock.json` files at the root of your repository (or at a path set in your [config file](config.md#config-schema)). Unlike the PHP build step, if `package-lock.json` is *missing*, this step is skipped and the deployment will continue. -To enable the Node build step, you must set a `node-version` in your [Cloud config file](/knowledge-base/cloud-config#config-schema). +To enable the Node build step, you must set a `node-version` in your [Cloud config file](config.md#config-schema). ### Build Command @@ -56,7 +56,7 @@ Within that `artifacts/` directory, the file structure of your existing artifact There is no need for filename-based cache-busting, as all artifact URLs will change with every build! ::: -The [Cloud extension](/knowledge-base/cloud-extension) also provides the `cloud.artifactUrl()` helper function for generating URLs to files published during your build. If you have historically used the `siteUrl()` or `url()` functions to link a stylesheet or JavaScript file (or any other static asset) in your web root, use this function instead. +The [Cloud extension](extension.md) also provides the `cloud.artifactUrl()` helper function for generating URLs to files published during your build. If you have historically used the `siteUrl()` or `url()` functions to link a stylesheet or JavaScript file (or any other static asset) in your web root, use this function instead. Outside of Cloud, `cloud.artifactUrl()` falls back to the automatically-determined `@web` alias—and anything in your web root will resolve normally. The special `@artifactBaseUrl` alias mirrors this behavior, and can be used in Project Config—or [anywhere else that evaluates aliases](/docs/5.x/configure.html#control-panel-settings): @@ -90,7 +90,7 @@ The `current` segment takes the place of a specific build ID, and will always po ### Rewriting Artifact URLs -As an alternative to replacing root-relative asset references in your templates, you can create [rewrite rules](/knowledge-base/cloud-redirects) to proxy individual files (or entire directories) from the CDN: +As an alternative to replacing root-relative asset references in your templates, you can create [rewrite rules](redirects.md) to proxy individual files (or entire directories) from the CDN: ```yml rewrites: @@ -99,7 +99,7 @@ rewrites: destination: '{artifactBaseUrl}{request.uri}' ``` -You can also serve artifacts from an [additional domain or subdomain](/knowledge-base/cloud-domains), as a kind of white-labeled CDN: +You can also serve artifacts from an [additional domain or subdomain](domains.md), as a kind of white-labeled CDN: ```yml rewrites: @@ -133,7 +133,7 @@ If you would like to continue to support this workflow, your configuration may r Users of the [Twigpack](https://plugins.craftcms.com/twigpack?craft5) plugin are protected from performance impacts by its built-in cache. The [Asset Rev](https://plugins.craftcms.com/assetrev?craft5) plugin memoizes manifest files for the duration of a request, but it does _not_ cache them between requests. ::: tip -Craft Cloud’s [static cache](/knowledge-base/cloud-static-caching) can also mitigate latency issues when interacting with remote files. +Craft Cloud’s [static cache](caching.md) can also mitigate latency issues when interacting with remote files. ::: ### Common Toolchains diff --git a/docs/cloud/clients.md b/docs/cloud/clients.md index 7410f7f49..358906999 100644 --- a/docs/cloud/clients.md +++ b/docs/cloud/clients.md @@ -8,14 +8,14 @@ Craft Cloud is part of Craft Console, so features that support teams like multi- Either way, taking advantage of organizations is key to collaborating on Cloud. ::: tip -Our [Managing a Craft Cloud Project](/knowledge-base/cloud-project-management) article covers the project lifecycle in greater detail. +Our [Managing a Craft Cloud Project](management.md) article covers the project lifecycle in greater detail. ::: ## Payment Methods An organization’s owner is responsible for maintaining its payment methods. A valid payment method is required to start a Cloud project; whenever a monthly or yearly bill is due, the organization’s primary payment method is automatically charged. -Organization owners will be notified if there are [billing issues](/knowledge-base/cloud-billing) any of its Cloud projects. +Organization owners will be notified if there are [billing issues](billing.md) any of its Cloud projects. ## Transferring Projects diff --git a/docs/cloud/compatibility.md b/docs/cloud/compatibility.md index a78cc9c38..d9d089c0b 100644 --- a/docs/cloud/compatibility.md +++ b/docs/cloud/compatibility.md @@ -3,26 +3,26 @@ Craft Cloud was designed to be compatible with a wide variety of projects—but for security and performance, we did have to make some decisions about what versions of Craft (and the software it depends on) we would officially support. This article covers those limitations, as well as some common features and configurations that may require special attention when moving a project to Cloud. ::: tip -If you maintain a plugin or module, review our [Cloud for Plugin Developers](/knowledge-base/cloud-plugin-development) guide, as well! +If you maintain a plugin or module, review our [Cloud for Plugin Developers](development.md) guide, as well! ::: ## Craft -Your project must be updated to at least {globalset:productVitals:vitalsCloudMinCraftVersion} to be able to install the [Cloud extension](/knowledge-base/cloud-extension), which provides essential functionality like automatic [configuration](/knowledge-base/cloud-config) and the [Cloud filesystem](/knowledge-base/cloud-assets). Version {globalset:productVitals:vitalsCloudMinExtensionVersion} of the extension is required to deploy your project. +Your project must be updated to at least {globalset:productVitals:vitalsCloudMinCraftVersion} to be able to install the [Cloud extension](extension.md), which provides essential functionality like automatic [configuration](config.md) and the [Cloud filesystem](assets.md). Version {globalset:productVitals:vitalsCloudMinExtensionVersion} of the extension is required to deploy your project. ## PHP -PHP {globalset:productVitals:custom_cloudMinPhpVersion} and newer are supported on Cloud. Pick a major and minor version via your project’s [`craft-cloud.yaml` config file](/knowledge-base/cloud-config). +PHP {globalset:productVitals:custom_cloudMinPhpVersion} and newer are supported on Cloud. Pick a major and minor version via your project’s [`craft-cloud.yaml` config file](config.md). ## Node -Versions 16 and newer of Node are supported in our [builder](/knowledge-base/cloud-builds) via the `node-version` key in your [Cloud config file](/knowledge-base/cloud-config). We plan to add all [LTS releases](https://nodejs.org/en/about/previous-releases), moving forward. +Versions 16 and newer of Node are supported in our [builder](builds.md) via the `node-version` key in your [Cloud config file](config.md). We plan to add all [LTS releases](https://nodejs.org/en/about/previous-releases), moving forward. We recommend declaring only a major version (i.e. `20`) to receive security and stability updates, but minor releases (i.e. `18.6`) are supported. ## Database Engines -See our article on [working with databases](/knowledge-base/cloud-databases) for up-to-date information on supported MySQL and Postgres versions. MariaDB is not supported on Craft Cloud, and we no longer recommended it for Craft 5. +See our article on [working with databases](databases.md) for up-to-date information on supported MySQL and Postgres versions. MariaDB is not supported on Craft Cloud, and we no longer recommended it for Craft 5. ## Mailers @@ -30,7 +30,7 @@ Craft Cloud does not have a built-in mail service. You must [configure your own ## Filesystems -**Local** filesystems will not work on Craft Cloud, and must be [converted](/knowledge-base/cloud-assets#converting-a-filesystem) to the Cloud filesystem provided by the extension. Remote filesystems provided by plugins that have not received updates from their maintainers to be compatible with Cloud may not be fully functional. +**Local** filesystems will not work on Craft Cloud, and must be [converted](assets.md#converting-a-filesystem) to the Cloud filesystem provided by the extension. Remote filesystems provided by plugins that have not received updates from their maintainers to be compatible with Cloud may not be fully functional. ## Configuration @@ -40,11 +40,11 @@ Some [Craft settings](/docs/5.x/configure.html) behave differently when running The [`resourceBasePath`](/docs/5.x/reference/config/general.html#resourcesbasepath) and [`resourceBaseUrl`](/docs/5.x/reference/config/general.html#resourcebaseurl) have no effect when running on Cloud. Asset bundles and anything that ends up in your [web root](#project-structure) are published to our CDN. -We automatically enable Craft’s [`asyncCsrfInputs`](/docs/5.x/reference/config/general.html#asynccsrfinputs) setting to support [static caching](/knowledge-base/cloud-static-caching). +We automatically enable Craft’s [`asyncCsrfInputs`](/docs/5.x/reference/config/general.html#asynccsrfinputs) setting to support [static caching](caching.md). ### Application Config -Changes made via `app.php` may not be honored when deployed to Cloud. Specifically, the [Cloud extension](/knowledge-base/cloud-extension) overrides these system components to guarantee they work in a Cloud-compatible way: +Changes made via `app.php` may not be honored when deployed to Cloud. Specifically, the [Cloud extension](extension.md) overrides these system components to guarantee they work in a Cloud-compatible way: - `assetManager` - `cache` @@ -56,7 +56,7 @@ In addition, we automatically set properties on the `db` component via [environm ### Project Structure -If your project has a different directory structure than our official [starter project](/knowledge-base/using-the-starter-project), you may need to set some additional keys in your [Cloud config file](/knowledge-base/cloud-config). This includes the `webroot` and other `*-path` settings. +If your project has a different directory structure than our official [starter project](/knowledge-base/using-the-starter-project), you may need to set some additional keys in your [Cloud config file](config.md). This includes the `webroot` and other `*-path` settings. ## Workflow diff --git a/docs/cloud/config.md b/docs/cloud/config.md index 4aaf19eae..73dfa0ed3 100644 --- a/docs/cloud/config.md +++ b/docs/cloud/config.md @@ -2,10 +2,10 @@ Craft Cloud looks for a `craft-cloud.yaml` file in the root of the connected repository. -This file has a specific syntax (YAML) and [schema](#config-schema) that determines a few things about how your project is [built](/knowledge-base/cloud-builds), [deployed](/knowledge-base/cloud-deployment), and served. If there are problems with your config file, the deployment will fail with an error describing the issue. +This file has a specific syntax (YAML) and [schema](#config-schema) that determines a few things about how your project is [built](builds.md), [deployed](deployment.md), and served. If there are problems with your config file, the deployment will fail with an error describing the issue. ::: tip -When you run `php craft setup/cloud` to install the [Cloud extension](/knowledge-base/cloud-extension), it will offer to generate a config file for you, then walk you through setting PHP and Node versions based on your project’s state. +When you run `php craft setup/cloud` to install the [Cloud extension](extension.md), it will offer to generate a config file for you, then walk you through setting PHP and Node versions based on your project’s state. ::: ## Config Schema @@ -53,12 +53,12 @@ Expanding on the above: - `webroot` — If your project uses a different directory for the public web root, you should specify it here. This is relative to `app-path`. (Default: `web`) ::: tip -For the latest information on supported PHP and Node versions, see our [Cloud Services and Compatibility](/knowledge-base/cloud-compatibility) article. +For the latest information on supported PHP and Node versions, see our [Cloud Services and Compatibility](compatibility.md) article. ::: ### Redirects and Rewrites -In addition to the above runtime and build settings, you can configure any number of [redirection and rewrite rules](/knowledge-base/cloud-redirects). These rules are evaluated _before_ the request reaches your Craft application, and can be used to normalize URLs, proxy assets or artifacts, redirect secondary domains, or map legacy URLs to your new site. +In addition to the above runtime and build settings, you can configure any number of [redirection and rewrite rules](redirects.md). These rules are evaluated _before_ the request reaches your Craft application, and can be used to normalize URLs, proxy assets or artifacts, redirect secondary domains, or map legacy URLs to your new site. ### Directory Structure @@ -71,7 +71,7 @@ If you have moved your `composer.json` or `package.json` into subdirectories, yo You can update `craft-cloud.yaml` any time. The settings will be validated and used during the next deployment. If you want to test a setting, commit the changes to a branch, and deploy it to another environment! ::: tip -If you encounter an error at build time, check out our [Troubleshooting](/knowledge-base/cloud-troubleshooting) guide. +If you encounter an error at build time, check out our [Troubleshooting](troubleshooting.md) guide. ::: ## Headless and Decoupled Front-Ends diff --git a/docs/cloud/databases.md b/docs/cloud/databases.md index 5bf0de5a2..bf717a3fb 100644 --- a/docs/cloud/databases.md +++ b/docs/cloud/databases.md @@ -12,7 +12,7 @@ related: Craft Cloud supports [MySQL](#mySQL) and [Postgres](#postgres) databases. You will pick a database engine when creating a new Cloud project: if you are starting a new project, we recommend MySQL 8.0; existing projects should use the same engine and version used by their current infrastructure. -Both engines support [automated and manual backups](/knowledge-base/cloud-backups) via Craft Console. +Both engines support [automated and manual backups](backups.md) via Craft Console. ::: tip Using a `tablePrefix` from an earlier version of Craft? Follow [these instructions](#table-prefixes) to make your database Cloud-compatible. @@ -20,11 +20,11 @@ Using a `tablePrefix` from an earlier version of Craft? Follow [these instructio ## Database Engines -Craft Cloud currently supports MySQL {globalset:productVitals:custom_cloudDbSupportMysql} and Postgres {globalset:productVitals:custom_cloudDbSupportPostgres} in [all regions](/knowledge-base/cloud-regions). +Craft Cloud currently supports MySQL {globalset:productVitals:custom_cloudDbSupportMysql} and Postgres {globalset:productVitals:custom_cloudDbSupportPostgres} in [all regions](regions.md). ## Connecting to your Database -Each environment gets its own database. Connection details are automatically provided to your application via the [Cloud extension](/knowledge-base/cloud-extension), so no configuration is necessary! +Each environment gets its own database. Connection details are automatically provided to your application via the [Cloud extension](extension.md), so no configuration is necessary! If you need to connect to your database from outside of Cloud (like with a database GUI), visit the **Access** screen of your environment to get credentials. @@ -32,7 +32,7 @@ If you need to connect to your database from outside of Cloud (like with a datab In addition to automated nightly backups of your database, you can trigger a manual backup of any environment from Craft Console. -→ Read more about [database backups](/knowledge-base/cloud-backups). +→ Read more about [database backups](backups.md). ::: warning The **Database Backup** [utility](/docs/5.x/system/control-panel.html#utilities) is not currently supported on Cloud. Use the **Backups** screen in Craft Console to capture a backup. diff --git a/docs/cloud/deployment.md b/docs/cloud/deployment.md index ea3e3581f..1034a8b2b 100644 --- a/docs/cloud/deployment.md +++ b/docs/cloud/deployment.md @@ -8,7 +8,7 @@ When you [trigger a deployment](#deployment-triggers) (by pushing code or manual This process reflects our general [deployment and workflow recommendations](/docs/5.x/deploy.html) laid out in the documentation—but it’s all handled for you! -You can review an [environment](/knowledge-base/cloud-environments)’s deployment history (and the status of any active deployments) by navigating to its **Deployments** screen. +You can review an [environment](environments.md)’s deployment history (and the status of any active deployments) by navigating to its **Deployments** screen. ### Deployment Triggers @@ -21,7 +21,7 @@ Each environment in Cloud defines its own **Deploy Trigger**, which determines w ## 1. Build Step -The first thing Cloud does is assemble PHP and Node dependencies, and package them into a new function. This process is described in greater detail in our [Build Process and Artifacts](/knowledge-base/cloud-builds) article. +The first thing Cloud does is assemble PHP and Node dependencies, and package them into a new function. This process is described in greater detail in our [Build Process and Artifacts](builds.md) article. If your project uses Node (or has unique PHP requirements), we strongly recommend familiarizing yourself with this stage of the deployment! diff --git a/docs/cloud/domains.md b/docs/cloud/domains.md index 61685bc02..883525e87 100644 --- a/docs/cloud/domains.md +++ b/docs/cloud/domains.md @@ -12,7 +12,7 @@ Every environment in your Cloud project gets a unique preview domain. Preview do project-my-handle-environment-b62dec18.preview.craft.cloud ``` -To find your preview domain, click the globe icon next to any environment in the project navigation menu. If you don't see this icon, it’s likely because it hasn’t been [deployed](/knowledge-base/cloud-deployments) yet! +To find your preview domain, click the globe icon next to any environment in the project navigation menu. If you don't see this icon, it’s likely because it hasn’t been [deployed](deployments.md) yet! ::: tip Changing the handle of a project or environment may take a moment to update in our routing layer. If you have other services that rely on a consistent hostname (say, for the delivery of webhooks), consider temporarily pointing a [subdomain](#subdomains) at the environment. @@ -24,7 +24,7 @@ In your Cloud project, navigate to **Domains**, then click **New domain**. Provide the root domain you wish to add, and select an environment, if you want to tie it to one right away. You aren’t required to point the new root domain at Cloud, but any custom domains you do connect must go through a brief verification process before Cloud will respond to requests on it (or any subdomain thereof). -Verifying a domain does _not_ automatically start [routing traffic](#route-traffic) to the selected environment. Conversely, you may elect to perform [real-time validation](/knowledge-base/cloud-for-cloudflare-users#real-time-validation) by immediately sending traffic to Cloud. +Verifying a domain does _not_ automatically start [routing traffic](#route-traffic) to the selected environment. Conversely, you may elect to perform [real-time validation](users.md#real-time-validation) by immediately sending traffic to Cloud. ::: warning A `www` [subdomain](#subdomains) is not automatically created for you. You must add it explicitly, if you wish to use it in addition to the bare domain. See the [redirection](#redirection) section to learn about normalizing access via `www` or non-`www` URLs. @@ -50,7 +50,7 @@ DNS records are cached for different amounts of time by different providers arou Heroku has a great [guide](https://devcenter.heroku.com/articles/custom-domains) that covers some of this technology, in the same context. If you are unfamiliar with DNS, consider starting with the [domain name glossary](https://devcenter.heroku.com/articles/custom-domains#domain-name-glossary) section, or flipping through Cloudflare’s [How DNS Works](https://www.cloudflare.com/learning/dns/what-is-dns/) series! ::: -To send traffic from a verified domain to your Cloud project, add the records below. Keep in mind that making changes to your DNS *can* result in downtime. Read more about how to [prepare for going live](/knowledge-base/cloud-launch-checklist). +To send traffic from a verified domain to your Cloud project, add the records below. Keep in mind that making changes to your DNS *can* result in downtime. Read more about how to [prepare for going live](checklist.md). The preferred way of routing traffic to Cloud is via a `CNAME` record: @@ -109,7 +109,7 @@ Every Cloud project includes one root domain, and as many subdomains as you need ## Redirection -After adding your apex domain _and_ a `www` subdomain, you can create a [redirection rule](/knowledge-base/cloud-redirects) that matches one or the other to ensure traffic is always served at a single address. +After adding your apex domain _and_ a `www` subdomain, you can create a [redirection rule](redirects.md) that matches one or the other to ensure traffic is always served at a single address. ## Troubleshooting @@ -124,4 +124,4 @@ Some ISPs cache DNS lookups more All traffic enters Craft Cloud’s infrastructure via Cloudflare, which means it (and your projects!) are protected by enterprise-grade security features. However, this can complicate ownership and certificate verification for existing Cloudflare users who have proxying enabled on the domain’s current apex records. -If you are in this situation (what Cloudflare calls [Orange-to-Orange](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/)), you will need to [follow this guide](/knowledge-base/cloud-for-cloudflare-users) to validate and connect your domain. +If you are in this situation (what Cloudflare calls [Orange-to-Orange](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/)), you will need to [follow this guide](users.md) to validate and connect your domain. diff --git a/docs/cloud/environments.md b/docs/cloud/environments.md index bcb21fa09..e83872cf8 100644 --- a/docs/cloud/environments.md +++ b/docs/cloud/environments.md @@ -10,7 +10,7 @@ Most of your work in Cloud will be in the context of an environment. Each enviro ### Deployments -View current and past deployments, or start a new one. Read more about [deploying to Craft Cloud](/knowledge-base/cloud-deployment). +View current and past deployments, or start a new one. Read more about [deploying to Craft Cloud](deployment.md). ### Logs @@ -18,7 +18,7 @@ Review + search logs from your live app. ### Backups -Create and download snapshots of your [database](/knowledge-base/cloud-databases). Backups are created nightly, and you can start a new one at-will—they’re retained for 30 days, either way. +Create and download snapshots of your [database](databases.md). Backups are created nightly, and you can start a new one at-will—they’re retained for 30 days, either way. ### Variables @@ -34,11 +34,11 @@ Every deploy also triggers a `cloud/up` command, so you’ll see those records a ### Access -Get credentials to this environment’s database and [asset storage](/knowledge-base/cloud-assets). Don’t share these details with anyone! +Get credentials to this environment’s database and [asset storage](assets.md). Don’t share these details with anyone! ### Settings -Rename the environment, or change the branch it’s associated with (and when it will be [deployed](/knowledge-base/cloud-deployment)). +Rename the environment, or change the branch it’s associated with (and when it will be [deployed](deployment.md)). ## Resources @@ -46,11 +46,11 @@ Every environment gets its own database. Data is not automatically cloned from o All environments in a project share a single asset storage bucket, but they are separated into top-level directories named after their environment’s ID (or, more accurately, its UUID). -Cloud generates a [preview domain](/knowledge-base/cloud-domains) for each environment—or allows you to connect a [custom domain](/knowledge-base/cloud-domains#adding-a-domain) or [subdomain](/knowledge-base/cloud-domains#subdomains) thereof. +Cloud generates a [preview domain](domains.md) for each environment—or allows you to connect a [custom domain](domains.md#adding-a-domain) or [subdomain](domains.md#subdomains) thereof. ## Environment Settings -When you create an environment, you’ll give it a name, select a Git branch, and choose a [deployment trigger](/knowledge-base/cloud-deployment#deployment-triggers). All three options can be changed any time from the environment’s **Settings** screen. +When you create an environment, you’ll give it a name, select a Git branch, and choose a [deployment trigger](deployment.md#deployment-triggers). All three options can be changed any time from the environment’s **Settings** screen. ## Production Environment diff --git a/docs/cloud/extension.md b/docs/cloud/extension.md index 0394b5c4d..c42f6788b 100644 --- a/docs/cloud/extension.md +++ b/docs/cloud/extension.md @@ -4,7 +4,7 @@ To run a project on Craft Cloud, it must require our first-party `craftcms/cloud In technical terms, the Cloud extension is a self-bootstrapping Yii module. Practically, it provides… -- …a special [filesystem type](/knowledge-base/cloud-assets) that interfaces seamlessly with Cloud’s storage solution; +- …a special [filesystem type](assets.md) that interfaces seamlessly with Cloud’s storage solution; - …automatic and reliable configuration of your project’s database connection, cache, queue, and other application components; - …[Twig helpers](/docs/5.x/reference/twig/functions.html) for generating [special URLs](#resource-uRLs); @@ -24,13 +24,13 @@ php craft setup/cloud If you would prefer to use Composer directly, require the `craftcms/cloud` package. After installation, perform one-time setup by running `php craft cloud/setup`. -You will be prompted for some information about your project, and the wizard will write a [Craft Cloud configuration file](/knowledge-base/cloud-config) to the project’s root. +You will be prompted for some information about your project, and the wizard will write a [Craft Cloud configuration file](config.md) to the project’s root. ## Special Features ### Cloud Filesystem -We recommend that new projects use the [Craft Cloud filesystem type](/knowledge-base/cloud-assets) for all [asset volumes](/docs/5.x/reference/element-types/assets.html). Other remote filesystem types may be compatible with Cloud, but will *not* support automatic fallback to your local disk, in development environments. +We recommend that new projects use the [Craft Cloud filesystem type](assets.md) for all [asset volumes](/docs/5.x/reference/element-types/assets.html). Other remote filesystem types may be compatible with Cloud, but will *not* support automatic fallback to your local disk, in development environments. ### Application Components @@ -44,7 +44,7 @@ To conserve resources, Cloud’s compute layer doesn’t serve *any* static asse #### Build Artifacts -Other static assets in your web root will also be uploaded to our CDN at build time. See our article on [build artifacts](/knowledge-base/cloud-builds#artifact-urls) for more information about generating URLs for these files. +Other static assets in your web root will also be uploaded to our CDN at build time. See our article on [build artifacts](builds.md#artifact-urls) for more information about generating URLs for these files. ### Additional Configuration diff --git a/docs/cloud/faq.md b/docs/cloud/faq.md index ea984dbe0..ee9001c8d 100644 --- a/docs/cloud/faq.md +++ b/docs/cloud/faq.md @@ -6,13 +6,13 @@ Here are the top questions we get asked about [Craft Cloud](https://craftcms.com ### Can I monitor Craft Cloud’s health? -Our [status page](https://status.craftcms.com) inclues information about Craft Cloud and all our other web services. More information about health checks is available in the [Cloud Status](/knowledge-base/cloud-status) article. +Our [status page](https://status.craftcms.com) inclues information about Craft Cloud and all our other web services. More information about health checks is available in the [Cloud Status](status.md) article. A link to the status page is available in the footer of every page on . ### Where can I find more information on Craft Cloud? -The [Knowledge Base](/knowledge-base/cloud) is the best place to find answers to your Cloud questions—in particular, our [Getting Started](/knowledge-base/cloud-getting-started) guide and the [Troubleshooting Common Problems on Craft Cloud](/knowledge-base/cloud-troubleshooting) are pathways into many platform concepts. +The [Knowledge Base](/knowledge-base/cloud) is the best place to find answers to your Cloud questions—in particular, our [Getting Started](started.md) guide and the [Troubleshooting Common Problems on Craft Cloud](troubleshooting.md) are pathways into many platform concepts. If you have questions about our software products, check out the [Craft CMS](/docs/5.x) or [Craft Commerce](/docs/commerce/5.x) documentation. @@ -22,7 +22,7 @@ Your Craft Cloud subscription entitles you to complementary [developer support]( ### How fast are support response times? -Response times will be similar to normal Craft CMS developer support—we assign priority to incoming issues and address them in an equitable way. We have support personnel in each of Craft Cloud’s [regions](/knowledge-base/cloud-regions) (US, Canada, EU, APAC). +Response times will be similar to normal Craft CMS developer support—we assign priority to incoming issues and address them in an equitable way. We have support personnel in each of Craft Cloud’s [regions](regions.md) (US, Canada, EU, APAC). Information about our support tiers is available on the [Developer Support](/support-services) page. @@ -48,27 +48,27 @@ We currently support connecting GitHub, Gitlab, and BitBucket repositories. ### What’s the minimum version of Craft and PHP that Craft Cloud supports? -Craft Cloud requires Craft CMS {globalset:productVitals:vitalsCloudMinCraftVersion} and PHP {globalset:productVitals:custom_cloudMinPhpVersion}. Your `composer.lock` file determines what version of Craft gets installed; your PHP version must be defined in your project’s [`craft-cloud.yaml` configuration file](/knowledge-base/cloud-config). +Craft Cloud requires Craft CMS {globalset:productVitals:vitalsCloudMinCraftVersion} and PHP {globalset:productVitals:custom_cloudMinPhpVersion}. Your `composer.lock` file determines what version of Craft gets installed; your PHP version must be defined in your project’s [`craft-cloud.yaml` configuration file](config.md). ### Is there are a trial for Craft Cloud? -Yes, all Craft Cloud projects start with a free 7-day trial. Read more about trials in our [Billing](/knowledge-base/cloud-billing) article. +Yes, all Craft Cloud projects start with a free 7-day trial. Read more about trials in our [Billing](billing.md) article. ### Which specific regions do you cover? We currently have presence in North America (Oregon, USA), Canada (Quebec), Europe (Frankfurt, Germany), and Asia-Pacific (Sydney, Australia). -Read more about [region support](/knowledge-base/cloud-regions). +Read more about [region support](regions.md). ### Is data encrypted at-rest? -Yes—your [assets](/knowledge-base/cloud-assets) and database are both encrypted at-rest. More information is available in our dedicated [databases](/knowledge-base/cloud-databases) article. +Yes—your [assets](assets.md) and database are both encrypted at-rest. More information is available in our dedicated [databases](databases.md) article. ### What kind of firewall do you have in place for Cloud? All Craft Cloud projects are protected by our Cloudflare WAF, with a “reasonable” setup of default rules. We make specific changes to the firewall as needs arise. -Some customers have their own Cloudflare accounts in front of ours, allowing them to manage specific WAF rules before requests make it to Craft Cloud. Cloudflare refers to this as the “[Orange-to-Orange](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/)” scenario; more information about this setup is available in the [Craft Cloud for Cloudflare](/knowledge-base/cloud-for-cloudflare-users) article. +Some customers have their own Cloudflare accounts in front of ours, allowing them to manage specific WAF rules before requests make it to Craft Cloud. Cloudflare refers to this as the “[Orange-to-Orange](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/)” scenario; more information about this setup is available in the [Craft Cloud for Cloudflare](users.md) article. ### Can I edit my .htaccess or nginx config file? @@ -76,13 +76,13 @@ Nope, sorry! Craft Cloud is serverless, and doesn’t use a traditional HTTP ser ### Can I SSH into my server? -Craft Cloud’s serverless architecture means there is nothing to SSH into! Images are built during each deployment, and spun up and destroyed based on traffic—even though the [ephemeral filesystem](/knowledge-base/cloud-migrating-projects) takes some getting used to, its inherent stability and security are an essential part of what makes Cloud such a great place to host your Craft project. +Craft Cloud’s serverless architecture means there is nothing to SSH into! Images are built during each deployment, and spun up and destroyed based on traffic—even though the [ephemeral filesystem](projects.md) takes some getting used to, its inherent stability and security are an essential part of what makes Cloud such a great place to host your Craft project. ### Can I run Craft console commands? Yes! From any environment in Craft Console, select **Commands**, then type in the Craft command you want to run. Arbitrary shell commands are not allowed. -Read more about [running](/knowledge-base/cloud-commands) and [scheduling](/knowledge-base/cloud-cron) commands on Cloud. +Read more about [running](commands.md) and [scheduling](cron.md) commands on Cloud. ### Does Craft Cloud support MariaDB? @@ -94,15 +94,15 @@ Currently, there is no automatic way to do this. As a result of each environment being connected to a git repository, you can revert problematic commits and re-deploy. If changes were made to the database that need to be rolled back (say, via a migration), the database will need to be restored to an appropriate point. Migrations are only run once Cloud has finished building your application image. Failed builds are never deployed! -Read more about [deployments](/knowledge-base/cloud-deployment) and our [build pipeline](/knowledge-base/cloud-builds). +Read more about [deployments](deployment.md) and our [build pipeline](builds.md). ### Can I sync code/databases/assets between environments? You can populate environments’ storage from whatever source(s) you want, but there is not currently an automated tool for this. - **Code:** Select the same branch as another environment, and start a deployment. -- **Database:** [Capture and download a backup](/knowledge-base/cloud-backups), then [restore it](/knowledge-base/cloud-backups#restoring-backups) to the secondary environment. -- **Assets:** Manually copy files from one bucket to another. Read more about [synchronizing assets](/knowledge-base/cloud-assets#synchronizing-assets). +- **Database:** [Capture and download a backup](backups.md), then [restore it](backups.md#restoring-backups) to the secondary environment. +- **Assets:** Manually copy files from one bucket to another. Read more about [synchronizing assets](assets.md#synchronizing-assets). Database and asset access credentials can be retrieved from your Craft Cloud console on a per-environment basis via the **Access** menu. @@ -122,19 +122,19 @@ We cover [customizing Craft’s mailer](/docs/5.x/system/mail.html) in the docum ### Does Craft Cloud provide a deployment pipeline? -Yes! Read all about [deployments](/knowledge-base/cloud-deployment) and the [build pipeline](/knowledge-base/cloud-builds). +Yes! Read all about [deployments](deployment.md) and the [build pipeline](builds.md). ### How can I statically cache the front end of my site? -Craft Cloud has a built-in [static caching](/knowledge-base/cloud-static-cache) system that is designed to work seamlessly with Craft CMS. On-disk and rewrite-based caches will not work, as the Cloud filesystem is ephemeral—and files in the “web root” aren’t directly exposed to the web. +Craft Cloud has a built-in [static caching](cache.md) system that is designed to work seamlessly with Craft CMS. On-disk and rewrite-based caches will not work, as the Cloud filesystem is ephemeral—and files in the “web root” aren’t directly exposed to the web. ### How do I work with assets locally and remotely? -The [Cloud filesystem](/knowledge-base/cloud-assets) has a special “fallback” feature for working locally. +The [Cloud filesystem](assets.md) has a special “fallback” feature for working locally. ### How do I move an existing project to Craft Cloud? -Check out our [migration guide](/knowledge-base/cloud-migrating-projects)! As long as you are using Craft CMS {globalset:productVitals:vitalsCloudMinCraftVersion} or later, your project is apt to work on Craft Cloud with very few changes. +Check out our [migration guide](projects.md)! As long as you are using Craft CMS {globalset:productVitals:vitalsCloudMinCraftVersion} or later, your project is apt to work on Craft Cloud with very few changes. ## Billing + Legal @@ -143,7 +143,7 @@ Check out our [migration guide](/knowledge-base/cloud-migrating-projects)! As lo Craft Cloud plans require a valid payment method on file in your Craft Console account or [organization](/knowledge-base/craft-console-organizations#managing-payment-information). Monthly and yearly plans are available. -Read more about [billing on Craft Cloud](/knowledge-base/cloud-billing). +Read more about [billing on Craft Cloud](billing.md). ### Do I need to purchase a Craft license for my site on Craft Cloud? @@ -153,15 +153,15 @@ You _do_ need to purchase licenses for any plugins you use, via the in-app Plugi ### Are there any resource limits on Craft Cloud? -Metered resources are listed on our [Cloud Quotas](/knowledge-base/cloud-quotas) page. Technical limitations are covered in [Cloud Services + Compatability](/knowledge-base/cloud-compatibility). +Metered resources are listed on our [Cloud Quotas](quotas.md) page. Technical limitations are covered in [Cloud Services + Compatability](compatibility.md). Use of Craft Cloud is also subject to our [Acceptable Use Policy](/acceptable-use-policy) and [Terms of Service](/terms-of-service). ### What kinds of usage trigger additional charges? -We have taken great care to make pricing stable for Cloud customers. As such, we do not use metered billing on any services—instead, we offer two [plans](/cloud#pricing), with add-ons for [asset storage](/knowledge-base/cloud-assets) and [domains](/knowledge-base/cloud-domains). +We have taken great care to make pricing stable for Cloud customers. As such, we do not use metered billing on any services—instead, we offer two [plans](/cloud#pricing), with add-ons for [asset storage](assets.md) and [domains](domains.md). -Refer to the [resource limitations](/knowledge-base/cloud-quotas) page for a list of other metrics. +Refer to the [resource limitations](quotas.md) page for a list of other metrics. {{ cloud.supportEmail }} diff --git a/docs/cloud/getting-started.md b/docs/cloud/getting-started.md index e66fbefff..6d187bdd5 100644 --- a/docs/cloud/getting-started.md +++ b/docs/cloud/getting-started.md @@ -24,7 +24,7 @@ You will be able to follow along using the seven-day free trial included with ev ## Preparing your Codebase -Any Craft CMS site running version {globalset:productVitals:vitalsCloudMinCraftVersion} or later can be configured to run on Cloud. Plugins and custom modules must be compatible with at least PHP {globalset:productVitals:custom_cloudMinPhpVersion}, and the project must `require` version {globalset:productVitals:vitalsCloudMinExtensionVersion} of the [Cloud extension](/knowledge-base/cloud-extension). +Any Craft CMS site running version {globalset:productVitals:vitalsCloudMinCraftVersion} or later can be configured to run on Cloud. Plugins and custom modules must be compatible with at least PHP {globalset:productVitals:custom_cloudMinPhpVersion}, and the project must `require` version {globalset:productVitals:vitalsCloudMinExtensionVersion} of the [Cloud extension](extension.md). ### New Sites @@ -34,13 +34,13 @@ Cloud projects begin the same way as any other. Follow the standard [installatio ddev craft setup/cloud ``` -Craft will install the [`craftcms/cloud` extension](/knowledge-base/cloud-extension), which handles all the necessary configuration, automatically. Your project will continue to work normally, in local development. +Craft will install the [`craftcms/cloud` extension](extension.md), which handles all the necessary configuration, automatically. Your project will continue to work normally, in local development. Commit and push the project files to a fresh Git repository. ### Existing Sites -Update your project to at least Craft {globalset:productVitals:vitalsCloudMinCraftVersion}, then run the command above. Most projects will run on Cloud without modification—but we recommend reviewing the [compatibility guide](/knowledge-base/cloud-compatibility) if you’ve made any customizations via [application config](/docs/5.x/reference/config/app.html), custom modules, or private plugins. We also have a dedicated guide on [moving projects to Craft Cloud](/knowledge-base/cloud-migrating-projects) from other hosts. +Update your project to at least Craft {globalset:productVitals:vitalsCloudMinCraftVersion}, then run the command above. Most projects will run on Cloud without modification—but we recommend reviewing the [compatibility guide](compatibility.md) if you’ve made any customizations via [application config](/docs/5.x/reference/config/app.html), custom modules, or private plugins. We also have a dedicated guide on [moving projects to Craft Cloud](projects.md) from other hosts. ::: tip Does your project use the `tablePrefix` setting or `CRAFT_DB_TABLE_PREFIX` config variable? Run `ddev craft db/drop-table-prefix` before continuing. @@ -52,7 +52,7 @@ Commit and push the changes to your Git provider. You’re ready! With your project running locally, it’s the perfect time to collect a few things we’ll need later: -1. Capture a [database backup](/knowledge-base/cloud-databases) and take note of the driver (Postgres or MySQL) and version; +1. Capture a [database backup](databases.md) and take note of the driver (Postgres or MySQL) and version; 1. Download a copy of all your assets (if feasible); 1. Document all your project-specific environment variables; @@ -64,25 +64,25 @@ If you haven’t already, create a [Craft Console](/knowledge-base/what-is-craft Cloud projects can be created from your personal Console account, or within an [organization](/knowledge-base/craft-console-organizations), but we strongly recommend using organizations whenever possible—especially for businesses and agencies that can benefit from delegated access. ::: -From the **Cloud** tab, click **New Project**. Select from the available git providers (or connect a new one), then choose the repository your Craft project was pushed to, in the previous step. Don’t see your repo? Try [one of these troubleshooting tips](/knowledge-base/cloud-troubleshooting#repo-not-visible). +From the **Cloud** tab, click **New Project**. Select from the available git providers (or connect a new one), then choose the repository your Craft project was pushed to, in the previous step. Don’t see your repo? Try [one of these troubleshooting tips](troubleshooting.md#repo-not-visible). ### Project Settings -When creating a project, you will be asked for a **Project Name** and **Handle**, what [**Region**](/knowledge-base/cloud-regions) it should be hosted in, and the [**Database Engine**](/knowledge-base/cloud-databases) you’d like to use. The database engine should match whatever you are using locally—if you just started a new project with DDEV, that would be MySQL 8. +When creating a project, you will be asked for a **Project Name** and **Handle**, what [**Region**](regions.md) it should be hosted in, and the [**Database Engine**](databases.md) you’d like to use. The database engine should match whatever you are using locally—if you just started a new project with DDEV, that would be MySQL 8. ### Billing + Terms -You can pay for Cloud projects monthly or annually. Discounts are provided on annual plans, and to verified [Partners](/become-a-partner). Learn more about how [billing](/knowledge-base/cloud-billing) works. +You can pay for Cloud projects monthly or annually. Discounts are provided on annual plans, and to verified [Partners](/become-a-partner). Learn more about how [billing](billing.md) works. All Cloud plans come with a free seven-day trial! ## Deployment -With your Cloud project connected to a Git repository, it’s time to set up an **Environment**. [Environments](/knowledge-base/cloud-environments) allow you to configure and deploy multiple versions of your project, independently—like a live site and a staging site. +With your Cloud project connected to a Git repository, it’s time to set up an **Environment**. [Environments](environments.md) allow you to configure and deploy multiple versions of your project, independently—like a live site and a staging site. ### Create an Environment -Each environment is associated with a Git branch, and gets its own database, asset storage, environment variables, logs, [preview domain](/knowledge-base/cloud-domains#preview-domains), and deployment strategy. +Each environment is associated with a Git branch, and gets its own database, asset storage, environment variables, logs, [preview domain](domains.md#preview-domains), and deployment strategy. From your project’s dashboard, click **Environments**, then **New environment**. Give it a **Name**, and select your desired **Deploy Trigger** and **Branch**. Below the settings pane, you’ll have an opportunity to pre-populate the environment with project-specific variables that you would normally store in a `.env` file. You do _not_ need to copy database connection details, URLs, or variables you would only set in a development environment—most configuration will be handled for you, automatically! @@ -94,25 +94,25 @@ If you selected “On Push” for your **Deployment Trigger**, Cloud will deploy ### Importing a Database -See our article on [working with Cloud databases](/knowledge-base/cloud-databases) to learn about the process of making and importing a database backup. The process will differ slightly for Postgres and MySQL users. +See our article on [working with Cloud databases](databases.md) to learn about the process of making and importing a database backup. The process will differ slightly for Postgres and MySQL users. ### Importing Assets ::: tip -If you just started a new project, you can skip this section, and review our [Assets on Craft Cloud](/knowledge-base/cloud-assets) article when you’re ready to set up your first asset volume. +If you just started a new project, you can skip this section, and review our [Assets on Craft Cloud](assets.md) article when you’re ready to set up your first asset volume. ::: -Existing projects that use a **Local** asset filesystem will require an update to work on Cloud. See our article about [migrating to Cloud asset storage](/knowledge-base/cloud-assets#synchronizing-assets) for more information. While we do not impose limitations on the third-party services your app communicates with, their plugins may require updates to be fully compatible with Cloud. +Existing projects that use a **Local** asset filesystem will require an update to work on Cloud. See our article about [migrating to Cloud asset storage](assets.md#synchronizing-assets) for more information. While we do not impose limitations on the third-party services your app communicates with, their plugins may require updates to be fully compatible with Cloud. ### Triggering a Deploy In your environment’s **Deployments** screen, click the **Deploy** button in the upper-right corner. -Cloud will begin a new [build](/knowledge-base/cloud-builds), and your changes will be available at your [preview domain](/knowledge-base/cloud-domains#preview-domains) in a minute or two! +Cloud will begin a new [build](builds.md), and your changes will be available at your [preview domain](domains.md#preview-domains) in a minute or two! ## Preview Domains -Every environment gets a [preview domain](/knowledge-base/cloud-domains#preview-domains) so you can make sure everything is working as expected *before* pointing your real domain at it. +Every environment gets a [preview domain](domains.md#preview-domains) so you can make sure everything is working as expected *before* pointing your real domain at it. ::: tip Not seeing your changes? Deployment status is reflected on the **Deployments** overview page, and more information is available when clicking the commit message of a single deploy. @@ -120,4 +120,4 @@ Not seeing your changes? Deployment status is reflected on the **Deployments** o ### Custom Domains -When you’re ready to cut over, check out our guide on [using custom domains](/knowledge-base/cloud-domains). Your first custom domain (and any number subdomains thereof) are free with a Cloud project. +When you’re ready to cut over, check out our guide on [using custom domains](domains.md). Your first custom domain (and any number subdomains thereof) are free with a Cloud project. diff --git a/docs/cloud/launch-checklist.md b/docs/cloud/launch-checklist.md index a510ad583..1d3bda880 100644 --- a/docs/cloud/launch-checklist.md +++ b/docs/cloud/launch-checklist.md @@ -4,15 +4,15 @@ Craft Cloud’s infrastructure is always ready for an influx of traffic—but th ## Preparation -Make sure you have access to your domain’s DNS management tool well in advance of launch. We recommend using a DNS provider that supports [CNAME flattening](/knowledge-base/cloud-domains#cname-flattening)—but it’s not a requirement to connect a domain at Cloud. +Make sure you have access to your domain’s DNS management tool well in advance of launch. We recommend using a DNS provider that supports [CNAME flattening](domains.md#cname-flattening)—but it’s not a requirement to connect a domain at Cloud. ### Domain Validation -This is typically the most volatile part of connecting a domain to Cloud—so make sure you’ve started the process by [adding the validation records](/knowledge-base/cloud-domains#adding-a-domain) to your DNS provider as soon as you know where the site will live. Don’t worry—validating a domain won't automatically send traffic to Cloud! +This is typically the most volatile part of connecting a domain to Cloud—so make sure you’ve started the process by [adding the validation records](domains.md#adding-a-domain) to your DNS provider as soon as you know where the site will live. Don’t worry—validating a domain won't automatically send traffic to Cloud! ### TTL -A few days before going live, consider lowering the TTL on key DNS records to ~300 seconds (five minutes). In most cases, that would be your root domain’s `A` records—but it could also be a subdomain’s `CNAME` record. Check out our [domains article](/knowledge-base/cloud-domains) for more information about what you’ll be asked to update. +A few days before going live, consider lowering the TTL on key DNS records to ~300 seconds (five minutes). In most cases, that would be your root domain’s `A` records—but it could also be a subdomain’s `CNAME` record. Check out our [domains article](domains.md) for more information about what you’ll be asked to update. This gives downstream providers’ caches time to expire, at which point they will re-fetch those records with the new (shorter) TTL—meaning subsequent updates will take less time to be picked up. @@ -20,12 +20,12 @@ This gives downstream providers’ caches time to expire, at which point they wi When it’s time to flip the switch, you’ll need to do two things: -1. Promote your [environment](/knowledge-base/cloud-environments) to [production](/knowledge-base/cloud-environments#production-environment) by selecting it in the project’s **Settings** screen. This signals to Cloud that the function should be kept warm by the platform so there’s no delay when the first request comes in. -2. [Update your domains’ DNS records](/knowledge-base/cloud-domains). Any domains (or subdomains) that should point to your production environment will require changes. Existing Cloudflare users may need to [disable proxying](/knowledge-base/cloud-for-cloudflare-users) on the apex domain. +1. Promote your [environment](environments.md) to [production](environments.md#production-environment) by selecting it in the project’s **Settings** screen. This signals to Cloud that the function should be kept warm by the platform so there’s no delay when the first request comes in. +2. [Update your domains’ DNS records](domains.md). Any domains (or subdomains) that should point to your production environment will require changes. Existing Cloudflare users may need to [disable proxying](users.md) on the apex domain. ## Deployments -Chances are, you’ve been iterating and deploying changes frequently over the course of development. Now that the site is publicly accessible, make sure the [deployment trigger](/knowledge-base/cloud-deployment#deployment-triggers) in your environment’s **Settings** screen agrees with your team’s desired workflow. +Chances are, you’ve been iterating and deploying changes frequently over the course of development. Now that the site is publicly accessible, make sure the [deployment trigger](deployment.md#deployment-triggers) in your environment’s **Settings** screen agrees with your team’s desired workflow. ### Staging Environment diff --git a/docs/cloud/local-dev.md b/docs/cloud/local-dev.md index 8ec496cfd..96d056a10 100644 --- a/docs/cloud/local-dev.md +++ b/docs/cloud/local-dev.md @@ -2,7 +2,7 @@ Craft Cloud has very little impact on your local development stack. Any changes required to make your project infrastructure-agnostic are apt to be in code or configuration—not tooling! -Our [Moving to Craft Cloud](/knowledge-base/cloud-migrating-projects) article covers these changes in detail, but the bits and pieces relevant to local development are collected here. +Our [Moving to Craft Cloud](projects.md) article covers these changes in detail, but the bits and pieces relevant to local development are collected here. ::: tip DDEV remains our recommended development environment, as it supports all the PHP and database versions that Cloud does. @@ -10,9 +10,9 @@ DDEV remains our recommended development environment, as it supports all the PHP ## The Cloud Extension -The [Cloud extension](/knowledge-base/cloud-extension) allows us to dynamically override some of your Craft application’s configuration to take advantage of platform features, like connecting to the managed database and asset storage. +The [Cloud extension](extension.md) allows us to dynamically override some of your Craft application’s configuration to take advantage of platform features, like connecting to the managed database and asset storage. -Your configuration is *not* modified when your project is running outside of Cloud. It’s important to be aware when [moving to Cloud](/knowledge-base/cloud-migrating-projects), though, which components’ configuration *will* be overridden—especially if your local development environment is designed to reflect your production infrastructure, and you expect certain features (Redis, for instance) to be available at all times. +Your configuration is *not* modified when your project is running outside of Cloud. It’s important to be aware when [moving to Cloud](projects.md), though, which components’ configuration *will* be overridden—especially if your local development environment is designed to reflect your production infrastructure, and you expect certain features (Redis, for instance) to be available at all times. When your local environment *does* need special configuration (say, to work with your team’s Docker Compose setup), that configuration should be handled with [environment variables](/docs/5.x/configure.html#environment-overrides) or [scoped to a specific environment](/docs/5.x/configure.html#multi-environment-configs). @@ -26,19 +26,19 @@ Make note of which variables you need for local development in a `.env.example` ## Assets and Filesystems -The [Cloud filesystem](/knowledge-base/cloud-assets) has special settings for local development, under its **Local Filesystem** section. Ensure these settings make sense for your project’s structure: +The [Cloud filesystem](assets.md) has special settings for local development, under its **Local Filesystem** section. Ensure these settings make sense for your project’s structure: - The **Base Path** should be below your web root (if the assets you’ll be storing there have public URLs), typically beginning with the `@webroot` alias; - The **Base URL** should agree, usually starting with the `@web` alias; -To learn more about filesystem settings and synchronizing files, see our article on [working with assets](/knowledge-base/cloud-assets). +To learn more about filesystem settings and synchronizing files, see our article on [working with assets](assets.md). ### Static Assets -References to files in your web root (like scripts and stylesheets) should use the `artifactUrl()` helper provided by the Cloud extension. Read more about [generating artifact URLs](/knowledge-base/cloud-builds#artifact-uRLs), especially if you use a development server for front-end assets like Vite or webpack! +References to files in your web root (like scripts and stylesheets) should use the `artifactUrl()` helper provided by the Cloud extension. Read more about [generating artifact URLs](builds.md#artifact-uRLs), especially if you use a development server for front-end assets like Vite or webpack! ## Database Backups -The [Databases on Craft Cloud](/knowledge-base/cloud-databases) article has instructions for capturing and restoring Cloud-compatible database backups. +The [Databases on Craft Cloud](databases.md) article has instructions for capturing and restoring Cloud-compatible database backups. MySQL databases can be restored from a manual or automated Cloud backup with Craft itself (using the `php craft db/restore` command), but Postgres backups require direct use of `pg_restore`. diff --git a/docs/cloud/migrating.md b/docs/cloud/migrating.md index 9f72803c9..24ecaa05c 100644 --- a/docs/cloud/migrating.md +++ b/docs/cloud/migrating.md @@ -1,7 +1,7 @@ Moving a Project to Cloud ::: tip -Be sure and review our [Getting Started with Craft Cloud](/knowledge-base/cloud-getting-started) guide! +Be sure and review our [Getting Started with Craft Cloud](started.md) guide! ::: This guide collects information from multiple other articles about making an existing project compatible with Craft Cloud. @@ -16,26 +16,26 @@ The first thing we’ll tackle is updates to your code and configuration. ### Key Requirements -Your Craft project must already be running Craft {globalset:productVitals:vitalsCloudMinCraftVersion} or later to be compatible with Cloud. In addition, you will need to install the first-party [Cloud extension](/knowledge-base/cloud-extension). +Your Craft project must already be running Craft {globalset:productVitals:vitalsCloudMinCraftVersion} or later to be compatible with Cloud. In addition, you will need to install the first-party [Cloud extension](extension.md). ### Cloud Config Cloud expects a `craft-cloud.yaml` file at the root of your repository. At a minimum, this file must contain a `php-version` key to tell Cloud what PHP runtime to use. It’s also where you’ll communicate to the builder where your Composer and Node “roots” are—if you have customized your project’s directory structure, you may need to provide additional keys in this config file. -Read more about using the [Cloud config file](/knowledge-base/cloud-config). +Read more about using the [Cloud config file](config.md). ### Filesystems Craft Cloud does not have a persistent filesystem (it is [ephemeral](/docs/5.x/reference/config/bootstrap.html#craft-ephemeral) in nature), so **Local** filesystems must be migrated to use the **Cloud** filesystem provided by the Cloud extension. -We have a dedicated article about [working with assets on Cloud](/knowledge-base/cloud-assets), and a section that [specifically addresses this migration](/knowledge-base/cloud-assets#synchronizing-assets). +We have a dedicated article about [working with assets on Cloud](assets.md), and a section that [specifically addresses this migration](assets.md#synchronizing-assets). ### Artifacts, Templates, and URLs -When you deploy your site to Craft Cloud, an [automated build process](/knowledge-base/cloud-builds) takes care of generating artifacts via NPM and uploading them to our CDN. This means that they are not directly accessible in the webroot of your site—via the filesystem *or* over HTTP. See our recommendations for [handling references to those artifacts](/knowledge-base/cloud-builds#artifact-urls) in your templates. +When you deploy your site to Craft Cloud, an [automated build process](builds.md) takes care of generating artifacts via NPM and uploading them to our CDN. This means that they are not directly accessible in the webroot of your site—via the filesystem *or* over HTTP. See our recommendations for [handling references to those artifacts](builds.md#artifact-urls) in your templates. ::: tip -You have control over the build process via [the `craft-cloud.yaml` config file](/knowledge-base/cloud-config). +You have control over the build process via [the `craft-cloud.yaml` config file](config.md). ::: You do _not_ need to set a `@web` [alias](https://craftcms.com/docs/5.x/configure.html#aliases) on Cloud, as all traffic to your site will arrive via our gateway, which sets and validates headers to prevent common security issues. @@ -56,25 +56,25 @@ This section is primarily concerned with importing your existing content to Craf ### Assets -Once you’ve [converted your asset filesystems](/knowledge-base/cloud-assets#converting-a-filesystem) in a local environment, you must [upload the assets](/knowledge-base/cloud-assets#synchronizing-assets) within them. +Once you’ve [converted your asset filesystems](assets.md#converting-a-filesystem) in a local environment, you must [upload the assets](assets.md#synchronizing-assets) within them. ### Database -Unlike assets, your database does not require any configuration changes—simply choose the database driver and version matching your current infrastructure when [setting up your Cloud project](/knowledge-base/cloud-getting-started). Keep in mind (per the above [application config](#application-config) section) that changes to your database connection component may be overridden when running on Cloud. A `db.php` file is not required for Craft Cloud; we recommend setting all connection information for local development (or other non-Cloud environments) via environment variables. +Unlike assets, your database does not require any configuration changes—simply choose the database driver and version matching your current infrastructure when [setting up your Cloud project](started.md). Keep in mind (per the above [application config](#application-config) section) that changes to your database connection component may be overridden when running on Cloud. A `db.php` file is not required for Craft Cloud; we recommend setting all connection information for local development (or other non-Cloud environments) via environment variables. -Our [Craft Cloud Databases](/knowledge-base/cloud-databases) article contains sections on importing and exporting data. +Our [Craft Cloud Databases](databases.md) article contains sections on importing and exporting data. ::: warning -Craft Cloud does not support the `tablePrefix` setting. See [this section](/knowledge-base/cloud-databases#table-prefixes) for information about renaming the tables in your project. +Craft Cloud does not support the `tablePrefix` setting. See [this section](databases.md#table-prefixes) for information about renaming the tables in your project. ::: ## Deployment -Once you’ve made the required code changes and imported your content, run a [deployment](/knowledge-base/cloud-deployment). While it’s a good idea to test the updates locally, you do *not* need to deploy the updates to your legacy infrastructure—Cloud will apply any pending [Project Config](/docs/5.x/system/project-config.html) updates (say, from changing your filesystems’ configuration) at the end of the deployment. +Once you’ve made the required code changes and imported your content, run a [deployment](deployment.md). While it’s a good idea to test the updates locally, you do *not* need to deploy the updates to your legacy infrastructure—Cloud will apply any pending [Project Config](/docs/5.x/system/project-config.html) updates (say, from changing your filesystems’ configuration) at the end of the deployment. ### Preview Domains -Your project automatically gets a [preview domain](/knowledge-base/cloud-domains#preview-domains) to validate your configuration and content before going live. +Your project automatically gets a [preview domain](domains.md#preview-domains) to validate your configuration and content before going live. ## Launch @@ -84,14 +84,14 @@ When it comes time to launch, there are likely three steps you’ll need to take 2. Import new content; 3. Reapply migrations and project config; -Read about [using custom domains with Craft Cloud](/knowledge-base/cloud-domains) to prepare for the required DNS changes, or review a more complete [launch checklist](/knowledge-base/cloud-launch-checklist). +Read about [using custom domains with Craft Cloud](domains.md) to prepare for the required DNS changes, or review a more complete [launch checklist](checklist.md). The exact process will differ based on your project’s tolerance of downtime—but generally, it’s a good idea to put your existing site into [maintenance mode](/5.x/reference/cli.html#off), export and re-import the database (and upload new assets), then run a final deployment. ::: tip -The AWS S3 CLI’s `sync` command is extremely useful for [uploading](/knowledge-base/cloud-assets) only new and modified assets. Consider running it periodically in your local environment to keep your content up-to-date—it also works when _uploading_ large asset libraries to your Cloud environment! +The AWS S3 CLI’s `sync` command is extremely useful for [uploading](assets.md) only new and modified assets. Consider running it periodically in your local environment to keep your content up-to-date—it also works when _uploading_ large asset libraries to your Cloud environment! ::: -With your latest code and content on Cloud, [disable maintenance mode](/docs/5.x/reference/cli.html#on) and [update your DNS](/knowledge-base/cloud-domains) to point your live domain at our infrastructure! +With your latest code and content on Cloud, [disable maintenance mode](/docs/5.x/reference/cli.html#on) and [update your DNS](domains.md) to point your live domain at our infrastructure! -More information about launching projects on Cloud is available in the [Going Live](/knowledge-base/cloud-launch-checklist) article. +More information about launching projects on Cloud is available in the [Going Live](checklist.md) article. diff --git a/docs/cloud/plugin-development.md b/docs/cloud/plugin-development.md index 748611b9f..7114161f0 100644 --- a/docs/cloud/plugin-development.md +++ b/docs/cloud/plugin-development.md @@ -42,7 +42,7 @@ If you do need to customize the delivery of binary data, Cloud’s web runtime i ### Asset Filesystems -While we recommend that projects on Cloud use our first-party [Cloud filesystem](/knowledge-base/cloud-assets), it is not a requirement. Plugins that provide filesystem types may need to implement a custom uploader to send binary files directly to the storage provider (rather than POST them to the Craft application itself). +While we recommend that projects on Cloud use our first-party [Cloud filesystem](assets.md), it is not a requirement. Plugins that provide filesystem types may need to implement a custom uploader to send binary files directly to the storage provider (rather than POST them to the Craft application itself). The Cloud filesystem’s [client-side](https://github.com/craftcms/cloud-extension-yii2/blob/2.x/src/web/assets/uploader/UploaderAsset.php) and [server-side](https://github.com/craftcms/cloud-extension-yii2/blob/2.x/src/controllers/AssetsController.php) code is available for reference. @@ -64,7 +64,7 @@ Doing so will take advantage of the existing volumes and filesystems, while stil ### Asset Bundles -Craft Cloud pre-publishes all known asset bundles to our CDN at [build-time](/knowledge-base/cloud-builds) to conserve compute resources. +Craft Cloud pre-publishes all known asset bundles to our CDN at [build-time](builds.md) to conserve compute resources. Any static assets your plugin provides to the control panel or front-end must be encapsulated in an [Asset Bundle](/docs/5.x/extend/asset-bundles.html), and its `sourcePath` must begin with your plugin’s predefined alias. To register an asset bundle, call `Craft::$app->getView()->registerAssetBundle($myBundle)` from a controller or template. Publishing one-off or ad-hoc assets at runtime is **not** supported on Cloud. @@ -75,7 +75,7 @@ Asset bundles have some additional requirements: ### Sessions + CSRF -To help support Cloud’s [static caching](/knowledge-base/cloud-static-caching) system, avoid interacting with the session unnecessarily, during _site_ requests. +To help support Cloud’s [static caching](caching.md) system, avoid interacting with the session unnecessarily, during _site_ requests. Always use the [`csrfInput()` Twig function](/docs/5.x/reference/twig/functions.html#csrfinput) when rendering front-end forms to maintain compatibility with Craft’s [`asyncCsrfInputs` config setting](/docs/5.x/reference/config/general.html#asynccsrfinputs) (4.9.0+). _Building an input manually (or using `craft\web\Request::getCsrfToken()` directly) can leak one user’s CSRF tokens to another!_ @@ -85,9 +85,9 @@ Plugins that already embrace our existing [coding guidelines and best practices] In addition, these tips can help avoid hiccups when your plugins are deployed to Craft Cloud: -- Implement batched jobs if your workload is [apt to exceed 15 minutes](/knowledge-base/cloud-quotas). It is often better to spawn many small jobs than a single long-running one. +- Implement batched jobs if your workload is [apt to exceed 15 minutes](quotas.md). It is often better to spawn many small jobs than a single long-running one. - Don’t set cookies unless absolutely necessary—like in response to a user action. - - If possible, register JavaScript to fetch CSRF tokens *asynchronously*. Using `{{ csrfInput() }}` in a template outside the control panel will immediately set a cookie and prevent [static caching](/knowledge-base/cloud-static-caching). + - If possible, register JavaScript to fetch CSRF tokens *asynchronously*. Using `{{ csrfInput() }}` in a template outside the control panel will immediately set a cookie and prevent [static caching](caching.md). ## Publishing Your Plugin diff --git a/docs/cloud/project-management.md b/docs/cloud/project-management.md index a97bb2e0e..296e9bbaf 100644 --- a/docs/cloud/project-management.md +++ b/docs/cloud/project-management.md @@ -36,4 +36,4 @@ This connection is established for your *personal* account, even if the project Whoever sets up a project must have the correct permissions at the provider (and grant access to any additional scopes) when establishing the connection. -Follow [this guide](/knowledge-base/cloud-troubleshooting) if you need to reauthorize a provider. +Follow [this guide](troubleshooting.md) if you need to reauthorize a provider. diff --git a/docs/cloud/quotas.md b/docs/cloud/quotas.md index 9483e365f..ef135c0ec 100644 --- a/docs/cloud/quotas.md +++ b/docs/cloud/quotas.md @@ -4,7 +4,7 @@ Every Craft Cloud project comes with generous resource quotas and simple, predic ## Environments -Projects are given three [environments](/knowledge-base/cloud-environments), one of which may be selected as the [production environment](/knowledge-base/cloud-environments#production-environment). You cannot currently purchase additional environments, but you may delete and recreate them whenever you need. +Projects are given three [environments](environments.md), one of which may be selected as the [production environment](environments.md#production-environment). You cannot currently purchase additional environments, but you may delete and recreate them whenever you need. ## Storage @@ -19,12 +19,12 @@ There are no limits on page views, database size, inbound transfer, or the numbe Outbound transfer from your application and asset storage bucket are metered. -If a response can be served from our edge (like a [statically-cached](/knowledge-base/cloud-static-caching) HTML document, an [image transform](https://craftcms.com/knowledge-base/cloud-assets#transforms), or any previously-requested asset or [build artifact](/knowledge-base/cloud-builds)), it does _not_ count toward your monthly bandwidth: +If a response can be served from our edge (like a [statically-cached](caching.md) HTML document, an [image transform](https://craftcms.comassets.md#transforms), or any previously-requested asset or [build artifact](builds.md)), it does _not_ count toward your monthly bandwidth: - **Team** projects get 250GB of transfer per month, shared between environments. - **Pro** projects get 500GB of transfer per month, shared between environments. -All transfer from our edge and CDN to your clients is free. Most projects will not need to do anything to take advantage of our edge cache, but you can optimize your cache-hit ratio by following our [static caching guide](/knowledge-base/cloud-static-caching), and limit asset egress by creating thoughtful [named asset transforms](/docs/5.x/development/image-transforms.html). +All transfer from our edge and CDN to your clients is free. Most projects will not need to do anything to take advantage of our edge cache, but you can optimize your cache-hit ratio by following our [static caching guide](caching.md), and limit asset egress by creating thoughtful [named asset transforms](/docs/5.x/development/image-transforms.html). The following table shows some common resource sizes, and an approximation of the number of uncached requests that fit within the **Team** plan’s bandwidth quota: @@ -42,7 +42,7 @@ Keep in mind that each image will only be loaded from the origin _once_ unless t ## Domains -One [custom domain](/knowledge-base/cloud-domains) is included with every project. You may add as many subdomains as you need, but additional domains are billed at $20 per month. Adding a domain part way through a billing period immediately bills a prorated amount to the payment method on file. +One [custom domain](domains.md) is included with every project. You may add as many subdomains as you need, but additional domains are billed at $20 per month. Adding a domain part way through a billing period immediately bills a prorated amount to the payment method on file. ## Requests + Responses @@ -56,7 +56,7 @@ Build artifacts are also _not_ subject to this limit, as they are served from ou ## Builds and Commands -You can [deploy](/knowledge-base/cloud-deployment) as often as you like. There are no limits on the total number of “build minutes” per billing period, but each [build](/knowledge-base/cloud-builds) must complete within **15 minutes**. +You can [deploy](deployment.md) as often as you like. There are no limits on the total number of “build minutes” per billing period, but each [build](builds.md) must complete within **15 minutes**. A brand new [starter project](/knowledge-base/using-the-starter-project) will typically deploy in about 90 seconds. Projects that use many plugins or have complex Node build steps will naturally take more time—long-running processes like automated tests may need to be offloaded to a different CI pipeline. diff --git a/docs/cloud/regions.md b/docs/cloud/regions.md index 85c6a2a75..31901733a 100644 --- a/docs/cloud/regions.md +++ b/docs/cloud/regions.md @@ -2,7 +2,7 @@ Craft Cloud is currently available in **North America**, **Canada**, **Europe**, and **Asia/Pacific**. You select a region when creating a new project. -A project’s region determines where your [database](/knowledge-base/cloud-databases) and compute resources are located, but *not* your assets. +A project’s region determines where your [database](databases.md) and compute resources are located, but *not* your assets. ## Choosing a Region diff --git a/docs/cloud/troubleshooting.md b/docs/cloud/troubleshooting.md index 8bb3d61da..4cb09afc1 100644 --- a/docs/cloud/troubleshooting.md +++ b/docs/cloud/troubleshooting.md @@ -21,19 +21,19 @@ Return to the **Integrations** screen in your personal Craft Console account, th ### Why did my build/deployment fail? -Build failures always display an error in that [deployment](/knowledge-base/cloud-deployment)’s details page. If you believe you've encountered a temporary failure, you can try redeploying the latest commit by clicking **Deploy**—even if the environment is set to deploy **On Push**. +Build failures always display an error in that [deployment](deployment.md)’s details page. If you believe you've encountered a temporary failure, you can try redeploying the latest commit by clicking **Deploy**—even if the environment is set to deploy **On Push**. The most common problems are: - **Issues cloning the repository.** Was it made private, renamed, or otherwise disconnected? -- **No PHP version was declared.** Make sure you have a `php-version` key in your [`craft-cloud.yaml` config file](/knowledge-base/cloud-config). +- **No PHP version was declared.** Make sure you have a `php-version` key in your [`craft-cloud.yaml` config file](config.md). - **Unsupported software or package versions.** - Your Cloud config file must include a `php-version`, set to a public release of PHP, version {globalset:productVitals:custom_cloudMinPhpVersion} or later. Patch versions are not supported. - If you are using Node, `node-version` must be set to {globalset:productVitals:custom_cloudMinNodeVersion} or higher. Only major version numbers are supported. - Craft CMS version {globalset:productVitals:vitalsCloudMinCraftVersion} or later is required. - `craftcms/cloud` version {globalset:productVitals:vitalsCloudMinExtensionVersion} or later is required. - **Errors when installing Composer packages.** Do you have a valid `composer.json` and `composer.lock` file in the connected repository? (It's technically possible—but exceedingly rare—for there to be connectivity issues when downloading packages. Check your logs, try again, or reach out to support if you continue to have problems at this stage in the build.) -- **Failures in the Node/NPM build script.** Something went wrong when installing your Node modules or while running the `build` script. Read more about the [build process](/knowledge-base/cloud-builds) and how we determine [what build script is run](/knowledge-base/cloud-config). +- **Failures in the Node/NPM build script.** Something went wrong when installing your Node modules or while running the `build` script. Read more about the [build process](builds.md) and how we determine [what build script is run](config.md). Cloud will report specific errors that fall into one of these categories. Some errors may require that you investigate the build logs, which are also available in the deployment screen; the step that failed will display a red X. From f319ba5e79ffe0a87e2df943da1a564e23af4d02 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 08:40:39 -0700 Subject: [PATCH 03/13] Replace other KB links with prefix --- docs/cloud/billing.md | 4 ++-- docs/cloud/clients.md | 2 +- docs/cloud/compatibility.md | 2 +- docs/cloud/config.md | 2 +- docs/cloud/faq.md | 6 +++--- docs/cloud/getting-started.md | 4 ++-- docs/cloud/migrating.md | 2 +- docs/cloud/project-management.md | 6 +++--- docs/cloud/quotas.md | 2 +- 9 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/cloud/billing.md b/docs/cloud/billing.md index 61ee26a79..2c2f7ae41 100644 --- a/docs/cloud/billing.md +++ b/docs/cloud/billing.md @@ -16,7 +16,7 @@ Payment methods for personal accounts and organizations are separate. You will o **All Cloud projects are billed to the primary payment method on the account or organization it was created in.** -Read more about [managing payment methods](/knowledge-base/craft-console-organizations#managing-payment-information) on Craft Console. +Read more about [managing payment methods](kb:craft-console-organizations#managing-payment-information) on Craft Console. ## Billing History @@ -51,7 +51,7 @@ Please email or use our [contact form](https://craftcms.c We will notify you as soon as we detect problems with the payment method on file, and prior to any automated changes in your project’s status or availability. Set up a new payment method as soon as possible to avoid service disruptions! ::: tip -All billing-related communication will be sent from notifications@craft.cloud. If your project is managed within a Craft Console [organization](/knowledge-base/craft-console-organizations), all its owners will be notified of billing issues. +All billing-related communication will be sent from notifications@craft.cloud. If your project is managed within a Craft Console [organization](kb:craft-console-organizations), all its owners will be notified of billing issues. ::: **Keep a valid payment method on file and monitor the inbox associated with your Craft Console account to avoid billing issues.** We strongly recommend using [organizations](kb:craft-console-organizations) for Craft Cloud projects—adding a second owner ensures that critical billing notifications are sent to users that can act on them. diff --git a/docs/cloud/clients.md b/docs/cloud/clients.md index 358906999..6f237fb7d 100644 --- a/docs/cloud/clients.md +++ b/docs/cloud/clients.md @@ -1,6 +1,6 @@ # Working with Clients -Craft Cloud is part of Craft Console, so features that support teams like multi-user [organizations](/knowledge-base/craft-console-organizations) and access control are built in: +Craft Cloud is part of Craft Console, so features that support teams like multi-user [organizations](kb:craft-console-organizations) and access control are built in: - As a *developer* or agency, you can create organizations and projects on behalf of clients; - As a *client*, you can invite your development partner to an organization and let them configure a project; diff --git a/docs/cloud/compatibility.md b/docs/cloud/compatibility.md index d9d089c0b..9b57cb607 100644 --- a/docs/cloud/compatibility.md +++ b/docs/cloud/compatibility.md @@ -56,7 +56,7 @@ In addition, we automatically set properties on the `db` component via [environm ### Project Structure -If your project has a different directory structure than our official [starter project](/knowledge-base/using-the-starter-project), you may need to set some additional keys in your [Cloud config file](config.md). This includes the `webroot` and other `*-path` settings. +If your project has a different directory structure than our official [starter project](kb:using-the-starter-project), you may need to set some additional keys in your [Cloud config file](config.md). This includes the `webroot` and other `*-path` settings. ## Workflow diff --git a/docs/cloud/config.md b/docs/cloud/config.md index 73dfa0ed3..ce3756d77 100644 --- a/docs/cloud/config.md +++ b/docs/cloud/config.md @@ -64,7 +64,7 @@ In addition to the above runtime and build settings, you can configure any numbe Multiple settings influence how Cloud locates key files in your project. The defaults agree with our official [starter project](https://github.com/craftcms/craft). -If you have moved your `composer.json` or `package.json` into subdirectories, you will need to specify an `app-path` or `node-path`, respectively. Similarly, [changing your web root](/knowledge-base/moving-craft-files) will require setting a `webroot` value, unless it remains below `app-path`, in a directory named `web`. +If you have moved your `composer.json` or `package.json` into subdirectories, you will need to specify an `app-path` or `node-path`, respectively. Similarly, [changing your web root](kb:moving-craft-files) will require setting a `webroot` value, unless it remains below `app-path`, in a directory named `web`. ## Changing Settings diff --git a/docs/cloud/faq.md b/docs/cloud/faq.md index ee9001c8d..d8bf0cc9e 100644 --- a/docs/cloud/faq.md +++ b/docs/cloud/faq.md @@ -12,13 +12,13 @@ A link to the status page is available in the footer of every page on . +Your Craft Cloud subscription entitles you to complementary [developer support](/support-services)! Start a new conversation from our [contact page](/contact?whatCanWeHelpYouWith=Support) using the email associated with your [Craft Console](kb:what-is-craft-console) account, or email us directly at <{globalset:productVitals:custom_cloudSupportEmail}>. ### How fast are support response times? @@ -141,7 +141,7 @@ Check out our [migration guide](projects.md)! As long as you are using Craft CMS ### How does billing work in Craft Cloud? -Craft Cloud plans require a valid payment method on file in your Craft Console account or [organization](/knowledge-base/craft-console-organizations#managing-payment-information). Monthly and yearly plans are available. +Craft Cloud plans require a valid payment method on file in your Craft Console account or [organization](kb:craft-console-organizations#managing-payment-information). Monthly and yearly plans are available. Read more about [billing on Craft Cloud](billing.md). diff --git a/docs/cloud/getting-started.md b/docs/cloud/getting-started.md index 6d187bdd5..1f3ce3582 100644 --- a/docs/cloud/getting-started.md +++ b/docs/cloud/getting-started.md @@ -58,10 +58,10 @@ With your project running locally, it’s the perfect time to collect a few thin ## Your First Cloud Project -If you haven’t already, create a [Craft Console](/knowledge-base/what-is-craft-console) account and add a [payment method](/knowledge-base/craft-console-organizations#managing-payment-information). +If you haven’t already, create a [Craft Console](kb:what-is-craft-console) account and add a [payment method](kb:craft-console-organizations#managing-payment-information). ::: tip -Cloud projects can be created from your personal Console account, or within an [organization](/knowledge-base/craft-console-organizations), but we strongly recommend using organizations whenever possible—especially for businesses and agencies that can benefit from delegated access. +Cloud projects can be created from your personal Console account, or within an [organization](kb:craft-console-organizations), but we strongly recommend using organizations whenever possible—especially for businesses and agencies that can benefit from delegated access. ::: From the **Cloud** tab, click **New Project**. Select from the available git providers (or connect a new one), then choose the repository your Craft project was pushed to, in the previous step. Don’t see your repo? Try [one of these troubleshooting tips](troubleshooting.md#repo-not-visible). diff --git a/docs/cloud/migrating.md b/docs/cloud/migrating.md index 24ecaa05c..5e945fb9c 100644 --- a/docs/cloud/migrating.md +++ b/docs/cloud/migrating.md @@ -8,7 +8,7 @@ This guide collects information from multiple other articles about making an exi Most projects will *not* need any special treatment, and will work with minimal configuration—just like a new project. Heavily-customized projects (including those with a non-standard [directory structure](/docs/5.x/system/directory-structure.html)) may require additional auditing or configuration. -Projects based on our official Composer [starter project](/knowledge-base/using-the-starter-project) tend to enjoy a minimally disruptive migration process, but it’s still a good idea to fully review this document and the resources it links to. +Projects based on our official Composer [starter project](kb:using-the-starter-project) tend to enjoy a minimally disruptive migration process, but it’s still a good idea to fully review this document and the resources it links to. ## Code + Configuration diff --git a/docs/cloud/project-management.md b/docs/cloud/project-management.md index 296e9bbaf..08499ca2d 100644 --- a/docs/cloud/project-management.md +++ b/docs/cloud/project-management.md @@ -1,6 +1,6 @@ # Managing Projects -Craft Cloud projects are always created via [Craft Console](/knowledge-base/what-is-craft-console). You can start projects with your [personal account](/knowledge-base/craft-console-organizations#individual-private-accounts), or within an [organization](/knowledge-base/craft-console-organizations#organizations). +Craft Cloud projects are always created via [Craft Console](kb:what-is-craft-console). You can start projects with your [personal account](kb:craft-console-organizations#individual-private-accounts), or within an [organization](kb:craft-console-organizations#organizations). We generally recommend organizations for Cloud projects, as they support delegated access and other features that underpin safe collaboration. @@ -8,7 +8,7 @@ We generally recommend organizations for Cloud projects, as they support delegat Log in to your Craft Console account, then click **Cloud** in the main navigation. If this is your first project, you’ll see a welcome screen and a **New project** button; existing Cloud users will see a list of current projects. -Use the menu in the upper-right corner to switch between your personal account and the organizations you are a member of. You must have a [payment method](/knowledge-base/craft-console-organizations#managing-payment-information) on file (in the current account context) to start a Cloud trial. +Use the menu in the upper-right corner to switch between your personal account and the organizations you are a member of. You must have a [payment method](kb:craft-console-organizations#managing-payment-information) on file (in the current account context) to start a Cloud trial. Within an organization, only owners and administrators can create projects. If you don’t have adequate permissions, get in touch with the person who created the organization. @@ -26,7 +26,7 @@ Projects are billed to the primary payment method on file for the personal accou ### Inviting a User -Read about [inviting users](/knowledge-base/craft-console-organizations#inviting-members-to-an-organization) in our Using Organizations article. +Read about [inviting users](kb:craft-console-organizations#inviting-members-to-an-organization) in our Using Organizations article. ## Connecting a Repository diff --git a/docs/cloud/quotas.md b/docs/cloud/quotas.md index ef135c0ec..a5a840787 100644 --- a/docs/cloud/quotas.md +++ b/docs/cloud/quotas.md @@ -58,7 +58,7 @@ Build artifacts are also _not_ subject to this limit, as they are served from ou You can [deploy](deployment.md) as often as you like. There are no limits on the total number of “build minutes” per billing period, but each [build](builds.md) must complete within **15 minutes**. -A brand new [starter project](/knowledge-base/using-the-starter-project) will typically deploy in about 90 seconds. Projects that use many plugins or have complex Node build steps will naturally take more time—long-running processes like automated tests may need to be offloaded to a different CI pipeline. +A brand new [starter project](kb:using-the-starter-project) will typically deploy in about 90 seconds. Projects that use many plugins or have complex Node build steps will naturally take more time—long-running processes like automated tests may need to be offloaded to a different CI pipeline. The final [migration](/docs/5.x/deploy.html#migrate) phase of each deployment does *not* count toward the build time limit, but _are_ governed by the discrete command duration limit. From 789155b0b6d5ca96d0288fdccfda071fe22d8017 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 08:41:38 -0700 Subject: [PATCH 04/13] Replace regular docs links --- docs/cloud/assets.md | 8 ++++---- docs/cloud/builds.md | 4 ++-- docs/cloud/compatibility.md | 16 ++++++++-------- docs/cloud/databases.md | 10 +++++----- docs/cloud/deployment.md | 2 +- docs/cloud/domains.md | 2 +- docs/cloud/extension.md | 10 +++++----- docs/cloud/faq.md | 4 ++-- docs/cloud/getting-started.md | 4 ++-- docs/cloud/local-dev.md | 4 ++-- docs/cloud/migrating.md | 14 +++++++------- docs/cloud/plugin-development.md | 8 ++++---- docs/cloud/quotas.md | 6 +++--- docs/cloud/static-caching.md | 14 +++++++------- 14 files changed, 53 insertions(+), 53 deletions(-) diff --git a/docs/cloud/assets.md b/docs/cloud/assets.md index 0bf51cf97..3a7549a54 100644 --- a/docs/cloud/assets.md +++ b/docs/cloud/assets.md @@ -6,7 +6,7 @@ To take advantage of that storage (and other features, like the built-in CDN and ## New Filesystems -New projects can start using it right away—new filesystems don’t require any special handling. You can [create a new filesystem and volume](/docs/5.x/reference/element-types/assets.html) the same way you would with any other filesystem type. Cloud filesystems do not require any credentials—they’re provided automatically by Cloud’s runtime. +New projects can start using it right away—new filesystems don’t require any special handling. You can [create a new filesystem and volume](/5.x/reference/element-types/assets.html) the same way you would with any other filesystem type. Cloud filesystems do not require any credentials—they’re provided automatically by Cloud’s runtime. When you are ready to stage or launch the project, you can [upload your local asset library](#uploading-to-a-bucket) to the equivalent subpath in the target Cloud environment’s storage bucket. Live assets can be referenced from a [local development environment](#local-development), in read-only mode. @@ -18,7 +18,7 @@ Existing projects may require some additional work to ensure their filesystems a Filesystems’ base paths cannot overlap! Even if you only need a single filesystem on Cloud, we recommend using the Cloud filesystem’s **Subpath** option to make room at the root of your volume for other filesystems, later. ::: -Changes to your filesystems + volumes will be applied via [Project Config](/docs/5.x/system/project-config.html), the next time you deploy your environment. +Changes to your filesystems + volumes will be applied via [Project Config](/5.x/system/project-config.html), the next time you deploy your environment. ### Local @@ -100,7 +100,7 @@ Automated environment duplication/synchronization is a planned feature of Cloud. ## Transforms -The [Cloud extension](extension.md) transparently enhances Craft’s [asset transform](/docs/5.x/development/image-transforms.html) APIs by generating and caching images at the edge, using special pre-signed URLs. Existing transforms will work seamlessly on Cloud, whether predefined via [named transforms](/docs/5.x/development/image-transforms.html#applying-named-transforms-to-images) and as [ad-hoc transforms](/docs/5.x/development/image-transforms.html#defining-transforms-in-your-templates) (except for one [limitation](#limitations), noted below). +The [Cloud extension](extension.md) transparently enhances Craft’s [asset transform](/5.x/development/image-transforms.html) APIs by generating and caching images at the edge, using special pre-signed URLs. Existing transforms will work seamlessly on Cloud, whether predefined via [named transforms](/5.x/development/image-transforms.html#applying-named-transforms-to-images) and as [ad-hoc transforms](/5.x/development/image-transforms.html#defining-transforms-in-your-templates) (except for one [limitation](#limitations), noted below). These images don’t contribute to your [storage quota](quotas.md), and there are no limits on the number of transforms or compute time. @@ -110,7 +110,7 @@ When no format is explicitly defined for a transform (or the transform uses the ### Limitations -Our workers treat the [`stretch` mode](/docs/5.x/development/image-transforms.html#stretch) similarly to how the CSS `object-fit: cover` property works—instead of independently scaling an image’s width and height to the specified dimensions, it enlarges the image proportionately to fill the space. This difference will only manifest if you are using the `stretch` mode, and setting _both_ the `height` and `width` properties in such a way that the transformed image’s aspect ratio would be different from the source. +Our workers treat the [`stretch` mode](/5.x/development/image-transforms.html#stretch) similarly to how the CSS `object-fit: cover` property works—instead of independently scaling an image’s width and height to the specified dimensions, it enlarges the image proportionately to fill the space. This difference will only manifest if you are using the `stretch` mode, and setting _both_ the `height` and `width` properties in such a way that the transformed image’s aspect ratio would be different from the source. Additional technical limitations include: diff --git a/docs/cloud/builds.md b/docs/cloud/builds.md index 7b982cc34..41c9994e8 100644 --- a/docs/cloud/builds.md +++ b/docs/cloud/builds.md @@ -58,7 +58,7 @@ There is no need for filename-based cache-busting, as all artifact URLs will cha The [Cloud extension](extension.md) also provides the `cloud.artifactUrl()` helper function for generating URLs to files published during your build. If you have historically used the `siteUrl()` or `url()` functions to link a stylesheet or JavaScript file (or any other static asset) in your web root, use this function instead. -Outside of Cloud, `cloud.artifactUrl()` falls back to the automatically-determined `@web` alias—and anything in your web root will resolve normally. The special `@artifactBaseUrl` alias mirrors this behavior, and can be used in Project Config—or [anywhere else that evaluates aliases](/docs/5.x/configure.html#control-panel-settings): +Outside of Cloud, `cloud.artifactUrl()` falls back to the automatically-determined `@web` alias—and anything in your web root will resolve normally. The special `@artifactBaseUrl` alias mirrors this behavior, and can be used in Project Config—or [anywhere else that evaluates aliases](/5.x/configure.html#control-panel-settings): ```twig {# Register a `script` tag to a static asset: #} @@ -108,7 +108,7 @@ rewrites: destination: '{artifactBaseUrl}{request.uri}' ``` -A rule like this means that your Craft application is responsible for generating the appropriate URLs; the Cloud extension will continue use the canonical CDN URLs for `@artifactBaseUrl` and `cloud.artifactUrl(...)`. As a result, you are apt to need your own [alias](/docs/5.x/configure.html#aliases) in all of the same situations as you would have used the built-in helpers. +A rule like this means that your Craft application is responsible for generating the appropriate URLs; the Cloud extension will continue use the canonical CDN URLs for `@artifactBaseUrl` and `cloud.artifactUrl(...)`. As a result, you are apt to need your own [alias](/5.x/configure.html#aliases) in all of the same situations as you would have used the built-in helpers. ### Reading Files diff --git a/docs/cloud/compatibility.md b/docs/cloud/compatibility.md index 9b57cb607..fb3b955a2 100644 --- a/docs/cloud/compatibility.md +++ b/docs/cloud/compatibility.md @@ -26,7 +26,7 @@ See our article on [working with databases](databases.md) for up-to-date informa ## Mailers -Craft Cloud does not have a built-in mail service. You must [configure your own adapter](/docs/5.x/system/mail.html) in Craft, as the default `sendmail` adapter will not work. +Craft Cloud does not have a built-in mail service. You must [configure your own adapter](/5.x/system/mail.html) in Craft, as the default `sendmail` adapter will not work. ## Filesystems @@ -34,13 +34,13 @@ Craft Cloud does not have a built-in mail service. You must [configure your own ## Configuration -Some [Craft settings](/docs/5.x/configure.html) behave differently when running on Cloud. +Some [Craft settings](/5.x/configure.html) behave differently when running on Cloud. ### General Config -The [`resourceBasePath`](/docs/5.x/reference/config/general.html#resourcesbasepath) and [`resourceBaseUrl`](/docs/5.x/reference/config/general.html#resourcebaseurl) have no effect when running on Cloud. Asset bundles and anything that ends up in your [web root](#project-structure) are published to our CDN. +The [`resourceBasePath`](/5.x/reference/config/general.html#resourcesbasepath) and [`resourceBaseUrl`](/5.x/reference/config/general.html#resourcebaseurl) have no effect when running on Cloud. Asset bundles and anything that ends up in your [web root](#project-structure) are published to our CDN. -We automatically enable Craft’s [`asyncCsrfInputs`](/docs/5.x/reference/config/general.html#asynccsrfinputs) setting to support [static caching](caching.md). +We automatically enable Craft’s [`asyncCsrfInputs`](/5.x/reference/config/general.html#asynccsrfinputs) setting to support [static caching](caching.md). ### Application Config @@ -52,7 +52,7 @@ Changes made via `app.php` may not be honored when deployed to Cloud. Specifical - `queue` - `session` -In addition, we automatically set properties on the `db` component via [environment overrides](/docs/5.x/configure.html#environment-overrides) to ensure Craft can connect to the current environment’s database. You may have connectivity issues if you use a `db.php` file, or add any other `CRAFT_DB_*` variables to an environment. +In addition, we automatically set properties on the `db` component via [environment overrides](/5.x/configure.html#environment-overrides) to ensure Craft can connect to the current environment’s database. You may have connectivity issues if you use a `db.php` file, or add any other `CRAFT_DB_*` variables to an environment. ### Project Structure @@ -60,11 +60,11 @@ If your project has a different directory structure than our official [starter p ## Workflow -Cloud was built with teams in mind, so it reflects our recommendations for maintaining a healthy [development and deployment workflow](/docs/5.x/deploy.html). This means that… +Cloud was built with teams in mind, so it reflects our recommendations for maintaining a healthy [development and deployment workflow](/5.x/deploy.html). This means that… - …we require your code to be pushed to a Git provider; - …direct access to the server/function filesystem is not allowed; -- …[Project Config](/docs/5.x/system/project-config.html) and changes that would alter `composer.json` (like running system updates) are discouraged; +- …[Project Config](/5.x/system/project-config.html) and changes that would alter `composer.json` (like running system updates) are discouraged; We believe these limitations will not affect most developers, but understand that they may involve some adjustment to processes. @@ -76,4 +76,4 @@ Whenever possible, we recommend adopting one-way flows for code and content: cod ### Headers -Our infrastructure flattens duplicate HTTP response headers into a single, comma-separated one. If you are using the [`{% header … %}` tag](/docs/5.x/reference/twig/tags.html#header) in your templates or manipulating the response object’s `HeaderCollection` directly, you may see *slightly* different output from a Cloud response than you would in other environments. Rest assured, they are functionally equivalent in the HTTP spec! +Our infrastructure flattens duplicate HTTP response headers into a single, comma-separated one. If you are using the [`{% header … %}` tag](/5.x/reference/twig/tags.html#header) in your templates or manipulating the response object’s `HeaderCollection` directly, you may see *slightly* different output from a Cloud response than you would in other environments. Rest assured, they are functionally equivalent in the HTTP spec! diff --git a/docs/cloud/databases.md b/docs/cloud/databases.md index bf717a3fb..1206de113 100644 --- a/docs/cloud/databases.md +++ b/docs/cloud/databases.md @@ -35,12 +35,12 @@ In addition to automated nightly backups of your database, you can trigger a man → Read more about [database backups](backups.md). ::: warning -The **Database Backup** [utility](/docs/5.x/system/control-panel.html#utilities) is not currently supported on Cloud. Use the **Backups** screen in Craft Console to capture a backup. +The **Database Backup** [utility](/5.x/system/control-panel.html#utilities) is not currently supported on Cloud. Use the **Backups** screen in Craft Console to capture a backup. ::: ## Importing Data -From an existing Craft installation, run the [`db/backup` command](/docs/5.x/reference/cli.html#db-backup) to generate a Cloud-compatible database dump. To restore data from another Craft Cloud environment, instead capture and download a backup from the **Backups** screen of the source environment. +From an existing Craft installation, run the [`db/backup` command](/5.x/reference/cli.html#db-backup) to generate a Cloud-compatible database dump. To restore data from another Craft Cloud environment, instead capture and download a backup from the **Backups** screen of the source environment. The specific commands for importing a backup to Cloud depend on your driver, but they will always be run from your local machine (or from wherever your current Craft installation lives). Substitute the parameters in `{brackets}` with corresponding values from the [**Access** screen](#connecting-to-your-database) of the target Cloud environment. @@ -97,7 +97,7 @@ pg_restore \ < path/to/backup.sql ``` -As of Craft 4.10, you can choose the format Craft uses to back up a Postgres database with the [`backupCommandFormat` setting](/docs/5.x/reference/config/general.html#backupcommandformat). +As of Craft 4.10, you can choose the format Craft uses to back up a Postgres database with the [`backupCommandFormat` setting](/5.x/reference/config/general.html#backupcommandformat). Make sure the version of `pg_restore` matches the version of `pg_dump` that was used to create the backup. Some GUI tools (like Table Plus) make it possible to choose the version when using binary backups. @@ -105,7 +105,7 @@ When dumping and restoring, the `--password` flag forces a password prompt—you ## Table Prefixes -The [`tablePrefix` setting](/docs/5.x/reference/config/db.html#tableprefix) (and the corresponding `CRAFT_DB_TABLE_PREFIX` environment variable) are not supported on Cloud. +The [`tablePrefix` setting](/5.x/reference/config/db.html#tableprefix) (and the corresponding `CRAFT_DB_TABLE_PREFIX` environment variable) are not supported on Cloud. Run `php craft db/drop-table-prefix` in a local environment before importing your data into Cloud to rename the tables. After doing so, you should unset `tablePrefix` in `db.php` and remove `CRAFT_DB_TABLE_PREFIX` from your `.env`. @@ -115,7 +115,7 @@ Here are some common sources of issues when backing up or restoring databases. ### Craft’s `backupCommand` -Using a custom [`backupCommand` config setting](/docs/5.x/reference/config/general.html#backupcommand) can lead to unreliable backups. Be sure to check `general.php` _and_ your `.env` file for a `CRAFT_BACKUP_COMMAND` environment override! Try the default command and [reach out to support](/contact) if you still get malformed backups. +Using a custom [`backupCommand` config setting](/5.x/reference/config/general.html#backupcommand) can lead to unreliable backups. Be sure to check `general.php` _and_ your `.env` file for a `CRAFT_BACKUP_COMMAND` environment override! Try the default command and [reach out to support](/contact) if you still get malformed backups. ### Backing up without Craft diff --git a/docs/cloud/deployment.md b/docs/cloud/deployment.md index 1034a8b2b..99c115db4 100644 --- a/docs/cloud/deployment.md +++ b/docs/cloud/deployment.md @@ -6,7 +6,7 @@ When you [trigger a deployment](#deployment-triggers) (by pushing code or manual 2. [Migrate](#2-migrations) 3. [Release/Deploy](#3-deployment) -This process reflects our general [deployment and workflow recommendations](/docs/5.x/deploy.html) laid out in the documentation—but it’s all handled for you! +This process reflects our general [deployment and workflow recommendations](/5.x/deploy.html) laid out in the documentation—but it’s all handled for you! You can review an [environment](environments.md)’s deployment history (and the status of any active deployments) by navigating to its **Deployments** screen. diff --git a/docs/cloud/domains.md b/docs/cloud/domains.md index 883525e87..7118480c3 100644 --- a/docs/cloud/domains.md +++ b/docs/cloud/domains.md @@ -97,7 +97,7 @@ You may also directly add and verify a non-apex domain if your project will neve Every domain that sends traffic to Craft Cloud is automatically protected with SSL by [Cloudflare](https://cloudflare.com). You do not need to manage certificates, redirection, or any other configuration—Cloud takes care of this for you, at the edge. -Cloud also sets the `@web` alias to ensure all URLs are generated with the secure `https://` protocol. The only place we *don’t* know what `@web` should be is on the CLI—if you need to generate URLs from a command (or queue job), you may need to define this alias in your [application config](/docs/5.x/configure.html#aliases). +Cloud also sets the `@web` alias to ensure all URLs are generated with the secure `https://` protocol. The only place we *don’t* know what `@web` should be is on the CLI—if you need to generate URLs from a command (or queue job), you may need to define this alias in your [application config](/5.x/configure.html#aliases). ## Nameservers diff --git a/docs/cloud/extension.md b/docs/cloud/extension.md index c42f6788b..86821401b 100644 --- a/docs/cloud/extension.md +++ b/docs/cloud/extension.md @@ -6,12 +6,12 @@ In technical terms, the Cloud extension is a self-bootstrapping Yii module. Prac - …a special [filesystem type](assets.md) that interfaces seamlessly with Cloud’s storage solution; - …automatic and reliable configuration of your project’s database connection, cache, queue, and other application components; -- …[Twig helpers](/docs/5.x/reference/twig/functions.html) for generating [special URLs](#resource-uRLs); +- …[Twig helpers](/5.x/reference/twig/functions.html) for generating [special URLs](#resource-uRLs); For most projects—and in local development—the extension will be largely undetectable. It only initializes functionality in environments that suggest (through the presence of special variables) it is necessary. ::: tip -Note that Cloud applies additional configuration directly to Craft via special, non-optional [environment overrides](/docs/5.x/configure.html#environment-overrides). +Note that Cloud applies additional configuration directly to Craft via special, non-optional [environment overrides](/5.x/configure.html#environment-overrides). ::: ## Installation @@ -30,15 +30,15 @@ You will be prompted for some information about your project, and the wizard wil ### Cloud Filesystem -We recommend that new projects use the [Craft Cloud filesystem type](assets.md) for all [asset volumes](/docs/5.x/reference/element-types/assets.html). Other remote filesystem types may be compatible with Cloud, but will *not* support automatic fallback to your local disk, in development environments. +We recommend that new projects use the [Craft Cloud filesystem type](assets.md) for all [asset volumes](/5.x/reference/element-types/assets.html). Other remote filesystem types may be compatible with Cloud, but will *not* support automatic fallback to your local disk, in development environments. ### Application Components -The extension replaces configuration for Craft’s cache, database, mutex, queue, and session [application components](/docs/5.x/reference/config/app.html) to ensure that they are configured in a way that is compatible with Cloud infrastructure. +The extension replaces configuration for Craft’s cache, database, mutex, queue, and session [application components](/5.x/reference/config/app.html) to ensure that they are configured in a way that is compatible with Cloud infrastructure. ### Resource URLs -By default, Craft publishes asset bundles to the public web root and generates URLs according to [`resourceBasePath`](/docs/5.x/reference/config/general.html#resourcebasepath) and [`resourceBaseUrl`](/docs/5.x/reference/config/general.html#resourcebaseurl). _These settings have no effect, when running on Cloud._ +By default, Craft publishes asset bundles to the public web root and generates URLs according to [`resourceBasePath`](/5.x/reference/config/general.html#resourcebasepath) and [`resourceBaseUrl`](/5.x/reference/config/general.html#resourcebaseurl). _These settings have no effect, when running on Cloud._ To conserve resources, Cloud’s compute layer doesn’t serve *any* static asset requests. Instead, these files are pre-generated and pushed to our CDN when your project is deployed. diff --git a/docs/cloud/faq.md b/docs/cloud/faq.md index d8bf0cc9e..23d910f49 100644 --- a/docs/cloud/faq.md +++ b/docs/cloud/faq.md @@ -14,7 +14,7 @@ A link to the status page is available in the footer of every page on getView()->registerAssetBundle($myBundle)` from a controller or template. Publishing one-off or ad-hoc assets at runtime is **not** supported on Cloud. +Any static assets your plugin provides to the control panel or front-end must be encapsulated in an [Asset Bundle](/5.x/extend/asset-bundles.html), and its `sourcePath` must begin with your plugin’s predefined alias. To register an asset bundle, call `Craft::$app->getView()->registerAssetBundle($myBundle)` from a controller or template. Publishing one-off or ad-hoc assets at runtime is **not** supported on Cloud. Asset bundles have some additional requirements: @@ -77,11 +77,11 @@ Asset bundles have some additional requirements: To help support Cloud’s [static caching](caching.md) system, avoid interacting with the session unnecessarily, during _site_ requests. -Always use the [`csrfInput()` Twig function](/docs/5.x/reference/twig/functions.html#csrfinput) when rendering front-end forms to maintain compatibility with Craft’s [`asyncCsrfInputs` config setting](/docs/5.x/reference/config/general.html#asynccsrfinputs) (4.9.0+). _Building an input manually (or using `craft\web\Request::getCsrfToken()` directly) can leak one user’s CSRF tokens to another!_ +Always use the [`csrfInput()` Twig function](/5.x/reference/twig/functions.html#csrfinput) when rendering front-end forms to maintain compatibility with Craft’s [`asyncCsrfInputs` config setting](/5.x/reference/config/general.html#asynccsrfinputs) (4.9.0+). _Building an input manually (or using `craft\web\Request::getCsrfToken()` directly) can leak one user’s CSRF tokens to another!_ ## Other Best Practices -Plugins that already embrace our existing [coding guidelines and best practices](/docs/5.x/extend/coding-guidelines.html) should be Cloud-ready—or take significantly less time to make compatible. +Plugins that already embrace our existing [coding guidelines and best practices](/5.x/extend/coding-guidelines.html) should be Cloud-ready—or take significantly less time to make compatible. In addition, these tips can help avoid hiccups when your plugins are deployed to Craft Cloud: diff --git a/docs/cloud/quotas.md b/docs/cloud/quotas.md index a5a840787..5bb5989e2 100644 --- a/docs/cloud/quotas.md +++ b/docs/cloud/quotas.md @@ -24,7 +24,7 @@ If a response can be served from our edge (like a [statically-cached](caching.md - **Team** projects get 250GB of transfer per month, shared between environments. - **Pro** projects get 500GB of transfer per month, shared between environments. -All transfer from our edge and CDN to your clients is free. Most projects will not need to do anything to take advantage of our edge cache, but you can optimize your cache-hit ratio by following our [static caching guide](caching.md), and limit asset egress by creating thoughtful [named asset transforms](/docs/5.x/development/image-transforms.html). +All transfer from our edge and CDN to your clients is free. Most projects will not need to do anything to take advantage of our edge cache, but you can optimize your cache-hit ratio by following our [static caching guide](caching.md), and limit asset egress by creating thoughtful [named asset transforms](/5.x/development/image-transforms.html). The following table shows some common resource sizes, and an approximation of the number of uncached requests that fit within the **Team** plan’s bandwidth quota: @@ -60,7 +60,7 @@ You can [deploy](deployment.md) as often as you like. There are no limits on the A brand new [starter project](kb:using-the-starter-project) will typically deploy in about 90 seconds. Projects that use many plugins or have complex Node build steps will naturally take more time—long-running processes like automated tests may need to be offloaded to a different CI pipeline. -The final [migration](/docs/5.x/deploy.html#migrate) phase of each deployment does *not* count toward the build time limit, but _are_ governed by the discrete command duration limit. +The final [migration](/5.x/deploy.html#migrate) phase of each deployment does *not* count toward the build time limit, but _are_ governed by the discrete command duration limit. Commands must complete within **15 minutes**, as well. This applies to automatically-triggered commands (like migrations) as well as those run manually from an environment’s **Commands** screen. @@ -72,7 +72,7 @@ Migrations for major Craft or plugin version upgrades can sometimes exceed this ## Queue -There are no limits to the number of concurrent or monthly queue jobs, but—like builds and commands—each job must be completed within **15 minutes**. For long-running tasks, plugin developers should implement `craft\queue\BaseBatchedJob` so that jobs can be [gracefully batched](/docs/5.x/extend/queue-jobs.html#batched-jobs) as that timeout approaches. +There are no limits to the number of concurrent or monthly queue jobs, but—like builds and commands—each job must be completed within **15 minutes**. For long-running tasks, plugin developers should implement `craft\queue\BaseBatchedJob` so that jobs can be [gracefully batched](/5.x/extend/queue-jobs.html#batched-jobs) as that timeout approaches. ## Craft License diff --git a/docs/cloud/static-caching.md b/docs/cloud/static-caching.md index 64e94e900..c7181862a 100644 --- a/docs/cloud/static-caching.md +++ b/docs/cloud/static-caching.md @@ -18,7 +18,7 @@ Most Craft features that rely on dynamic rendering are already set up to bypass The request’s entire URL (including query parameters) is used when determining whether to serve a page from the cache. -In Craft versions 4.10 and 5.2, the [`expires` Twig tag](/docs/5.x/reference/twig/tags.html#expires) was introduced to simplify setting cache headers. Examples are provided below for this method as well as precise control of individual headers via the [`header` tag](/docs/5.x/reference/twig/tags.html#header). +In Craft versions 4.10 and 5.2, the [`expires` Twig tag](/5.x/reference/twig/tags.html#expires) was introduced to simplify setting cache headers. Examples are provided below for this method as well as precise control of individual headers via the [`header` tag](/5.x/reference/twig/tags.html#header). ### Force Caching @@ -48,7 +48,7 @@ You can explicitly flag a template or response as being _ineligible_ for full-pa {% expires %} ``` -In PHP, use the `Response` component available from any [controller](/docs/5.x/extend/controllers.html): +In PHP, use the `Response` component available from any [controller](/5.x/extend/controllers.html): ```php public function actionSaveWidget(): Response @@ -67,7 +67,7 @@ This method also sets `Expires` and `Pragma` headers. When using the `expires` t ## Duration -The Cloud extension uses the same source of information as Craft when determining how long to statically cache a page (if it is cachable at all). This means that pages using elements with an **Expiry Date** sooner than the default [`cacheDuration` setting](/docs/5.x/reference/config/general.html#cacheduration) will only be cached as long as all the underlying content ought to be visible. As with Craft’s template caches system, there is not currently a mechanism in place to invalidate caches that _would_ contain elements with a future **Post Date**. +The Cloud extension uses the same source of information as Craft when determining how long to statically cache a page (if it is cachable at all). This means that pages using elements with an **Expiry Date** sooner than the default [`cacheDuration` setting](/5.x/reference/config/general.html#cacheduration) will only be cached as long as all the underlying content ought to be visible. As with Craft’s template caches system, there is not currently a mechanism in place to invalidate caches that _would_ contain elements with a future **Post Date**. If you have [manually set cache headers](#force-caching) at some point in the request, Craft will not overwrite those headers. @@ -99,13 +99,13 @@ If you suspect a page is not being cached, look for a `Set-Cookie` header in the ### Users -The `{% requireLogin %}`, `{% requireGuest %}`, `{% requireAdmin %}`, and `{% requirePermission %}` [Twig tags](/docs/5.x/reference/twig/tags.html) all use session data to dynamically redirect users. +The `{% requireLogin %}`, `{% requireGuest %}`, `{% requireAdmin %}`, and `{% requirePermission %}` [Twig tags](/5.x/reference/twig/tags.html) all use session data to dynamically redirect users. -Reading the [`currentUser` variable](/docs/5.x/reference/twig/global-variables.html) does not implicitly start a session, and may result in the logged-out state of a page being cached. Any pages you anticipate including personalized content (like user dashboards) should include the [`{% expires %}` tag](#opting-out) so that they are excluded from the cache, or lazily fetch session-dependent regions [via Ajax](#including-via-ajax). +Reading the [`currentUser` variable](/5.x/reference/twig/global-variables.html) does not implicitly start a session, and may result in the logged-out state of a page being cached. Any pages you anticipate including personalized content (like user dashboards) should include the [`{% expires %}` tag](#opting-out) so that they are excluded from the cache, or lazily fetch session-dependent regions [via Ajax](#including-via-ajax). ### CSRF -Use Craft’s [`asyncCsrfInputs` setting](/docs/5.x/reference/config/general.html#asynccsrfinputs) to make CSRF inputs generated with the [`csrfInput()` Twig function](/docs/5.x/reference/twig/functions.html#csrfinput) compatible with the static cache. Instead of outputting the `input` element and token directly (therefore opening a session), a placeholder is rendered and replaced after the browser/client loads the page and fetches a CSRF token via Ajax. +Use Craft’s [`asyncCsrfInputs` setting](/5.x/reference/config/general.html#asynccsrfinputs) to make CSRF inputs generated with the [`csrfInput()` Twig function](/5.x/reference/twig/functions.html#csrfinput) compatible with the static cache. Instead of outputting the `input` element and token directly (therefore opening a session), a placeholder is rendered and replaced after the browser/client loads the page and fetches a CSRF token via Ajax. You can also opt in to asynchronous CSRF inputs on a case-by-case basis: @@ -121,7 +121,7 @@ Avoid calling `craft.app.request.getCsrfToken()` directly, or manually building ### Flashes -Any time you access session-dependent information like [flashes](/docs/5.x/development/forms.html#flashes), Craft sends no-cache headers. Form submissions via POST are never cached and will therefore re-render the page with any contextual [validation errors](/docs/5.x/development/forms.html#models-and-validation) as you would expect—but when the form itself is otherwise cachable (including using [asynchronous CSRF tokens](#csrf)), you can guard flash messages with a check for a flag: +Any time you access session-dependent information like [flashes](/5.x/development/forms.html#flashes), Craft sends no-cache headers. Form submissions via POST are never cached and will therefore re-render the page with any contextual [validation errors](/5.x/development/forms.html#models-and-validation) as you would expect—but when the form itself is otherwise cachable (including using [asynchronous CSRF tokens](#csrf)), you can guard flash messages with a check for a flag: ```twig {# Access session data only when the `success` query param is set: #} From 98a21243da7a6c6de60b8b3affa08300c14549e8 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 15:21:06 -0700 Subject: [PATCH 05/13] Email/mailto component --- .../theme/global-components/Email.vue | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/.vuepress/theme/global-components/Email.vue diff --git a/docs/.vuepress/theme/global-components/Email.vue b/docs/.vuepress/theme/global-components/Email.vue new file mode 100644 index 000000000..51af251b4 --- /dev/null +++ b/docs/.vuepress/theme/global-components/Email.vue @@ -0,0 +1,20 @@ + From ad9ddc314c1e3927eb1e98310a5d7c06c5ee37c3 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 17:20:59 -0700 Subject: [PATCH 06/13] Website anchor prefix --- docs/.vuepress/anchor-prefixes.js | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.vuepress/anchor-prefixes.js b/docs/.vuepress/anchor-prefixes.js index c0e19460f..c3c356e96 100644 --- a/docs/.vuepress/anchor-prefixes.js +++ b/docs/.vuepress/anchor-prefixes.js @@ -29,6 +29,7 @@ module.exports = { 'kb': { base: 'https://craftcms.com/knowledge-base/', format: 'generic' }, 'repo': { base: 'https://github.com/', format: 'generic' }, 'plugin': { base: 'https://plugins.craftcms.com/', format: 'generic', }, + 'craftcom' : { base: 'https://craftcms.com/', format: 'generic' }, // This doesn't do anything, but I'd hoped we could implement a context-aware format: '@': { base: '/', format: 'set-local' }, }; From e4714d99e6aa820abbfc810afc17013193cba8be Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 17:21:23 -0700 Subject: [PATCH 07/13] $activeSetVars global --- docs/.vuepress/sets/craft-cloud.js | 12 ++++++++++++ docs/.vuepress/theme/enhanceApp.js | 12 ++++++++++-- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/.vuepress/sets/craft-cloud.js b/docs/.vuepress/sets/craft-cloud.js index 1a3d4b625..18dd092ee 100644 --- a/docs/.vuepress/sets/craft-cloud.js +++ b/docs/.vuepress/sets/craft-cloud.js @@ -6,6 +6,18 @@ module.exports = { abandoned: false, searchPlaceholder: "Search Cloud docs (Press “/” to focus)", primarySet: true, + globalVars: { + supportEmail: 'support@craft.cloud', + minCraftVersion: '4.6.0', + minCloudExtensionVersion: '1.16.5', + minPhpVersion: '8.1', + dbSupportMySql: '8.0', + dbSupportPostgres: '15', + trialDays: 7, + minNodeVersion: '18', + regionSupport: 'North America, Canada, Europe, and Asia/Pacific', + scheduledCommandsMax: 'five', + }, sidebar: { "/": [ { diff --git a/docs/.vuepress/theme/enhanceApp.js b/docs/.vuepress/theme/enhanceApp.js index a0c771200..e28a10d0b 100644 --- a/docs/.vuepress/theme/enhanceApp.js +++ b/docs/.vuepress/theme/enhanceApp.js @@ -20,7 +20,7 @@ export default ({ Vue, options, router, siteData }) => { Vue.mixin({ data() { return { - version: null + version: null, }; }, computed: { @@ -112,6 +112,14 @@ export default ({ Vue, options, router, siteData }) => { } } }, + $activeSetVars() { + return Object.assign( + { + // Default/global variables can go here! + }, + this.$activeSet.globalVars || {}, + ); + }, /** * Every doc set base path, including set base, version, and/or language. Example: * - `/2.x/` @@ -164,7 +172,7 @@ export default ({ Vue, options, router, siteData }) => { : this.$localePath; return (this.$allLocales || {})[localePath] || {}; - } + }, }); Object.assign(options, { From e25f2e46b3b58819a14301dabd9b85fc700dacc3 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 17:22:00 -0700 Subject: [PATCH 08/13] Replace ref tags with Vue interpolation --- docs/cloud/README.md | 12 +++++ docs/cloud/compatibility.md | 4 +- docs/cloud/databases.md | 4 +- docs/cloud/domains.md | 2 +- docs/cloud/extension.md | 4 +- docs/cloud/faq.md | 90 ++++++++++++++++++++++++++------ docs/cloud/getting-started.md | 8 +-- docs/cloud/migrating.md | 2 +- docs/cloud/plugin-development.md | 8 +-- docs/cloud/quotas.md | 4 +- docs/cloud/regions.md | 2 +- docs/cloud/static-caching.md | 2 +- docs/cloud/troubleshooting.md | 8 +-- 13 files changed, 111 insertions(+), 39 deletions(-) diff --git a/docs/cloud/README.md b/docs/cloud/README.md index bd042ce61..6f1eb5295 100644 --- a/docs/cloud/README.md +++ b/docs/cloud/README.md @@ -1 +1,13 @@ # Welcome to Craft Cloud + +Craft Cloud is our very own serverless hosting platform. We designed it from the ground-up to be the best way to launch and scale your Craft project. + + + +You can [get started](getting-started.md) on Cloud by deploying a new or existing project with a free seven-day trial. + +This section covers everything from [initial configuration](config.md) to [launch-day preparation](launch-checklist.md), as well as Craft features that let you make the most of the platform. + +::: tip +Psst! Were you redirected here from the [Knowledge Base](https://craftcms.com/knowledge-base)? We recently merged all Cloud resources into the main docs site so you can learn about all our products in the same space. +::: diff --git a/docs/cloud/compatibility.md b/docs/cloud/compatibility.md index fb3b955a2..952b0bbe2 100644 --- a/docs/cloud/compatibility.md +++ b/docs/cloud/compatibility.md @@ -8,11 +8,11 @@ If you maintain a plugin or module, review our [Cloud for Plugin Developers](dev ## Craft -Your project must be updated to at least {globalset:productVitals:vitalsCloudMinCraftVersion} to be able to install the [Cloud extension](extension.md), which provides essential functionality like automatic [configuration](config.md) and the [Cloud filesystem](assets.md). Version {globalset:productVitals:vitalsCloudMinExtensionVersion} of the extension is required to deploy your project. +Your project must be updated to at least {{ $activeSetVars.minCraftVersion }} to be able to install the [Cloud extension](extension.md), which provides essential functionality like automatic [configuration](config.md) and the [Cloud filesystem](assets.md). Version {{ $activeSetVars.minCloudExtensionVersion }} of the extension is required to deploy your project. ## PHP -PHP {globalset:productVitals:custom_cloudMinPhpVersion} and newer are supported on Cloud. Pick a major and minor version via your project’s [`craft-cloud.yaml` config file](config.md). +PHP {{ $activeSet.minPhpVersion }} and newer are supported on Cloud. Pick a major and minor version via your project’s [`craft-cloud.yaml` config file](config.md). ## Node diff --git a/docs/cloud/databases.md b/docs/cloud/databases.md index 1206de113..f566bfea5 100644 --- a/docs/cloud/databases.md +++ b/docs/cloud/databases.md @@ -20,7 +20,7 @@ Using a `tablePrefix` from an earlier version of Craft? Follow [these instructio ## Database Engines -Craft Cloud currently supports MySQL {globalset:productVitals:custom_cloudDbSupportMysql} and Postgres {globalset:productVitals:custom_cloudDbSupportPostgres} in [all regions](regions.md). +Craft Cloud currently supports MySQL {{ $activeSetVars.dbSupportMySql }} and Postgres {{ $activeSetVars.dbSupportPostgres }} in [all regions](regions.md). ## Connecting to your Database @@ -115,7 +115,7 @@ Here are some common sources of issues when backing up or restoring databases. ### Craft’s `backupCommand` -Using a custom [`backupCommand` config setting](/5.x/reference/config/general.html#backupcommand) can lead to unreliable backups. Be sure to check `general.php` _and_ your `.env` file for a `CRAFT_BACKUP_COMMAND` environment override! Try the default command and [reach out to support](/contact) if you still get malformed backups. +Using a custom [`backupCommand` config setting](/5.x/reference/config/general.html#backupcommand) can lead to unreliable backups. Be sure to check `general.php` _and_ your `.env` file for a `CRAFT_BACKUP_COMMAND` environment override! Try the default command and [reach out to support](craftcom:contact) if you still get malformed backups. ### Backing up without Craft diff --git a/docs/cloud/domains.md b/docs/cloud/domains.md index 7118480c3..5f6636953 100644 --- a/docs/cloud/domains.md +++ b/docs/cloud/domains.md @@ -105,7 +105,7 @@ Craft Cloud *does not* include domain registration or DNS management tools. You ## Pricing -Every Cloud project includes one root domain, and as many subdomains as you need. You can purchase additional root domains at any time. Read more at [Cloud pricing](/cloud). +Every Cloud project includes one root domain, and as many subdomains as you need. You can purchase additional root domains at any time. Read more at [Cloud pricing](craftcom:cloud). ## Redirection diff --git a/docs/cloud/extension.md b/docs/cloud/extension.md index 86821401b..f135c87a1 100644 --- a/docs/cloud/extension.md +++ b/docs/cloud/extension.md @@ -16,7 +16,7 @@ Note that Cloud applies additional configuration directly to Craft via special, ## Installation -You can install the extension with one command, in any project running Craft CMS 4.5.10 or later (but only projects on {globalset:productVitals:vitalsCloudMinCraftVersion} or later can be deployed to Cloud): +You can install the extension with one command, in any project running Craft CMS 4.5.10 or later (but only projects on {{ $activeSetVars.minCraftVersion }} or later can be deployed to Cloud): ```bash php craft setup/cloud @@ -54,4 +54,4 @@ The Cloud extension includes some [additional settings](https://github.com/craft Additional technical details and the extension’s source are available in the [readme on GitHub](https://github.com/craftcms/cloud-extension-yii2). -If you encounter a bug or compatibility issues with another plugin (public or private), please [file an issue](https://github.com/craftcms/cloud-extension-yii2/issues/new/choose) or [contact support](/contact?whatCanWeHelpYouWith=Support)! +If you encounter a bug or compatibility issues with another plugin (public or private), please [file an issue](https://github.com/craftcms/cloud-extension-yii2/issues/new/choose) or [contact support](craftcom:contact?whatCanWeHelpYouWith=Support)! diff --git a/docs/cloud/faq.md b/docs/cloud/faq.md index 23d910f49..58027f310 100644 --- a/docs/cloud/faq.md +++ b/docs/cloud/faq.md @@ -4,89 +4,125 @@ Here are the top questions we get asked about [Craft Cloud](https://craftcms.com ## Status + Help + + ### Can I monitor Craft Cloud’s health? Our [status page](https://status.craftcms.com) inclues information about Craft Cloud and all our other web services. More information about health checks is available in the [Cloud Status](status.md) article. -A link to the status page is available in the footer of every page on . +A link to the status page is available in the footer of every page on . + + ### Where can I find more information on Craft Cloud? -The [Knowledge Base](kb:cloud) is the best place to find answers to your Cloud questions—in particular, our [Getting Started](started.md) guide and the [Troubleshooting Common Problems on Craft Cloud](troubleshooting.md) are pathways into many platform concepts. + [Knowledge Base](kb:cloud) is the best place to find answers to your Cloud questions—in particular, our [Getting Started](getting-started.md) guide and the [Troubleshooting](troubleshooting.md) pages are pathways into many platform concepts. -If you have questions about our software products, check out the [Craft CMS](/5.x) or [Craft Commerce](/docs/commerce/5.x) documentation. +If you have questions about our software products, check out the [Craft CMS](/5.x) or [Craft Commerce](/commerce/5.x) documentation. + + ### How do I get support for my Craft Cloud project? -Your Craft Cloud subscription entitles you to complementary [developer support](/support-services)! Start a new conversation from our [contact page](/contact?whatCanWeHelpYouWith=Support) using the email associated with your [Craft Console](kb:what-is-craft-console) account, or email us directly at <{globalset:productVitals:custom_cloudSupportEmail}>. +Your Craft Cloud subscription entitles you to complementary [developer support](craftcom:support-services)! Start a new conversation from our [contact page](craftcom:contact?whatCanWeHelpYouWith=Support) using the email associated with your [Craft Console](kb:what-is-craft-console) account, or email us directly at . + + ### How fast are support response times? Response times will be similar to normal Craft CMS developer support—we assign priority to incoming issues and address them in an equitable way. We have support personnel in each of Craft Cloud’s [regions](regions.md) (US, Canada, EU, APAC). -Information about our support tiers is available on the [Developer Support](/support-services) page. +Information about our support tiers is available on the [Developer Support](craftcom:support-services) page. + + ### Is there a roadmap for Craft Cloud? Yes! Check out the [Roadmaps](https://craftcms.com/roadmap) page. Our plans for Craft Cloud appear [at the bottom of the page](https://craftcms.com/roadmap#cloud). + + ### How do I request a feature for Craft Cloud? -We welcome feature requests via the [public discussion board](https://github.com/craftcms/cloud/discussions), or via <{globalset:productVitals:custom_cloudSupportEmail}>. +We welcome feature requests via the [public discussion board](https://github.com/craftcms/cloud/discussions), or via . ## Service + Features + + ### Can I point multiple domains to a single Craft Cloud environment? Yes! This is a perfect way to manage multi-site installations. -Each project gets one free domain, and unlimited subdomains; additional domains can be added [for a fee](/cloud#cloud-infrastructure). +Each project gets one free domain, and unlimited subdomains; additional domains can be added [for a fee](craftcom:cloud#cloud-infrastructure). + + ### Which Git providers do you support? We currently support connecting GitHub, Gitlab, and BitBucket repositories. + + ### What’s the minimum version of Craft and PHP that Craft Cloud supports? -Craft Cloud requires Craft CMS {globalset:productVitals:vitalsCloudMinCraftVersion} and PHP {globalset:productVitals:custom_cloudMinPhpVersion}. Your `composer.lock` file determines what version of Craft gets installed; your PHP version must be defined in your project’s [`craft-cloud.yaml` configuration file](config.md). +Craft Cloud requires Craft CMS {{ $activeSetVars.minCraftVersion }} and PHP {{ $activeSetVars.minPhpVersion }}. Your `composer.lock` file determines what version of Craft gets installed; your PHP version must be defined in your project’s [`craft-cloud.yaml` configuration file](config.md). + + ### Is there are a trial for Craft Cloud? Yes, all Craft Cloud projects start with a free 7-day trial. Read more about trials in our [Billing](billing.md) article. + + ### Which specific regions do you cover? We currently have presence in North America (Oregon, USA), Canada (Quebec), Europe (Frankfurt, Germany), and Asia-Pacific (Sydney, Australia). Read more about [region support](regions.md). + + ### Is data encrypted at-rest? Yes—your [assets](assets.md) and database are both encrypted at-rest. More information is available in our dedicated [databases](databases.md) article. + + ### What kind of firewall do you have in place for Cloud? All Craft Cloud projects are protected by our Cloudflare WAF, with a “reasonable” setup of default rules. We make specific changes to the firewall as needs arise. Some customers have their own Cloudflare accounts in front of ours, allowing them to manage specific WAF rules before requests make it to Craft Cloud. Cloudflare refers to this as the “[Orange-to-Orange](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/)” scenario; more information about this setup is available in the [Craft Cloud for Cloudflare](users.md) article. + + ### Can I edit my .htaccess or nginx config file? Nope, sorry! Craft Cloud is serverless, and doesn’t use a traditional HTTP server like nginx or Apache. + + ### Can I SSH into my server? Craft Cloud’s serverless architecture means there is nothing to SSH into! Images are built during each deployment, and spun up and destroyed based on traffic—even though the [ephemeral filesystem](projects.md) takes some getting used to, its inherent stability and security are an essential part of what makes Cloud such a great place to host your Craft project. + + ### Can I run Craft console commands? Yes! From any environment in Craft Console, select **Commands**, then type in the Craft command you want to run. Arbitrary shell commands are not allowed. Read more about [running](commands.md) and [scheduling](cron.md) commands on Cloud. + + ### Does Craft Cloud support MariaDB? -No, Craft Cloud only supports MySQL {globalset:productVitals:custom_cloudDbSupportMysql} and Postgres {globalset:productVitals:custom_cloudDbSupportPostgres}. If you are migrating a site to Cloud, make sure its database can be neatly imported into MySQL 8, first. +No, Craft Cloud only supports MySQL {{ $activeSetVars.dbSupportMySql }}and Postgres {{ $activeSetVars.dbSupportPostgres }}. If you are migrating a site to Cloud, make sure its database can be neatly imported into MySQL 8, first. + + ### How do I roll back a deployment? @@ -96,6 +132,8 @@ As a result of each environment being connected to a git repository, you can rev Read more about [deployments](deployment.md) and our [build pipeline](builds.md). + + ### Can I sync code/databases/assets between environments? You can populate environments’ storage from whatever source(s) you want, but there is not currently an automated tool for this. @@ -106,13 +144,19 @@ You can populate environments’ storage from whatever source(s) you want, but t Database and asset access credentials can be retrieved from your Craft Cloud console on a per-environment basis via the **Access** menu. + + ### Do I have to supply my own SSL certificate for my site? Nope! SSL is included with every domain connected to your Craft Cloud project, and requests are automatically redirected to HTTPs. + + ### Can I supply my own custom SSL certificate for my site? -Yes! Please send us an email at <{globalset:productVitals:custom_cloudSupportEmail}> to get started. +Yes! Please send us an email at to get started. + + ### Does Craft Cloud provide email services for my Craft project? @@ -120,51 +164,67 @@ We currently do not have a dedicated transactional email service. You are free t We cover [customizing Craft’s mailer](/5.x/system/mail.html) in the documentation. + + ### Does Craft Cloud provide a deployment pipeline? Yes! Read all about [deployments](deployment.md) and the [build pipeline](builds.md). + + ### How can I statically cache the front end of my site? Craft Cloud has a built-in [static caching](cache.md) system that is designed to work seamlessly with Craft CMS. On-disk and rewrite-based caches will not work, as the Cloud filesystem is ephemeral—and files in the “web root” aren’t directly exposed to the web. + + ### How do I work with assets locally and remotely? The [Cloud filesystem](assets.md) has a special “fallback” feature for working locally. + + ### How do I move an existing project to Craft Cloud? -Check out our [migration guide](projects.md)! As long as you are using Craft CMS {globalset:productVitals:vitalsCloudMinCraftVersion} or later, your project is apt to work on Craft Cloud with very few changes. +Check out our [migration guide](projects.md)! As long as you are using Craft CMS {{ $activeSetVars.minCraftVersion }} or later, your project is apt to work on Craft Cloud with very few changes. ## Billing + Legal + + ### How does billing work in Craft Cloud? Craft Cloud plans require a valid payment method on file in your Craft Console account or [organization](kb:craft-console-organizations#managing-payment-information). Monthly and yearly plans are available. Read more about [billing on Craft Cloud](billing.md). + + ### Do I need to purchase a Craft license for my site on Craft Cloud? Nope! A Craft license is included with your Craft Cloud plan. It is valid for as long as your plan is in good standing. You _do_ need to purchase licenses for any plugins you use, via the in-app Plugin Store. + + ### Are there any resource limits on Craft Cloud? Metered resources are listed on our [Cloud Quotas](quotas.md) page. Technical limitations are covered in [Cloud Services + Compatability](compatibility.md). -Use of Craft Cloud is also subject to our [Acceptable Use Policy](/acceptable-use-policy) and [Terms of Service](/terms-of-service). +Use of Craft Cloud is also subject to our [Acceptable Use Policy](craftcom:acceptable-use-policy) and [Terms of Service](craftcom:terms-of-service). + + ### What kinds of usage trigger additional charges? -We have taken great care to make pricing stable for Cloud customers. As such, we do not use metered billing on any services—instead, we offer two [plans](/cloud#pricing), with add-ons for [asset storage](assets.md) and [domains](domains.md). +We have taken great care to make pricing stable for Cloud customers. As such, we do not use metered billing on any services—instead, we offer two [plans](craftcom:cloud#pricing), with add-ons for [asset storage](assets.md) and [domains](domains.md). Refer to the [resource limitations](quotas.md) page for a list of other metrics. -{{ cloud.supportEmail }} + ### Do you offer SLAs? -We only offer SLAs with enterprise agreements in place. Send an email to <{globalset:productVitals:custom_cloudSupportEmail}> to get started. +We only offer SLAs with enterprise agreements in place. Send an email to to get started. diff --git a/docs/cloud/getting-started.md b/docs/cloud/getting-started.md index 9c23c7f6e..ed25cb8f3 100644 --- a/docs/cloud/getting-started.md +++ b/docs/cloud/getting-started.md @@ -1,6 +1,6 @@ # Getting Started -Welcome to [Craft Cloud](/cloud), our new hosting platform tailor-made for Craft CMS! +Welcome to [Craft Cloud](craftcom:cloud), our new hosting platform tailor-made for Craft CMS! This article covers the critical path to deploying your first project to Cloud. For [new projects](#new-sites), we still recommend starting with a local development environment; most [existing projects](#existing-sites) can be moved to Cloud after a quick system update. @@ -24,7 +24,7 @@ You will be able to follow along using the seven-day free trial included with ev ## Preparing your Codebase -Any Craft CMS site running version {globalset:productVitals:vitalsCloudMinCraftVersion} or later can be configured to run on Cloud. Plugins and custom modules must be compatible with at least PHP {globalset:productVitals:custom_cloudMinPhpVersion}, and the project must `require` version {globalset:productVitals:vitalsCloudMinExtensionVersion} of the [Cloud extension](extension.md). +Any Craft CMS site running version {{ $activeSetVars.minCraftVersion }} or later can be configured to run on Cloud. Plugins and custom modules must be compatible with at least PHP {{ $activeSetVars.minPhpVersion }}, and the project must `require` version {{ $activeSetVars.minCloudExtensionVersion }} of the [Cloud extension](extension.md). ### New Sites @@ -40,7 +40,7 @@ Commit and push the project files to a fresh Git repository. ### Existing Sites -Update your project to at least Craft {globalset:productVitals:vitalsCloudMinCraftVersion}, then run the command above. Most projects will run on Cloud without modification—but we recommend reviewing the [compatibility guide](compatibility.md) if you’ve made any customizations via [application config](/5.x/reference/config/app.html), custom modules, or private plugins. We also have a dedicated guide on [moving projects to Craft Cloud](projects.md) from other hosts. +Update your project to at least Craft {{ $activeSetVars.minCraftVersion }}, then run the command above. Most projects will run on Cloud without modification—but we recommend reviewing the [compatibility guide](compatibility.md) if you’ve made any customizations via [application config](/5.x/reference/config/app.html), custom modules, or private plugins. We also have a dedicated guide on [moving projects to Craft Cloud](projects.md) from other hosts. ::: tip Does your project use the `tablePrefix` setting or `CRAFT_DB_TABLE_PREFIX` config variable? Run `ddev craft db/drop-table-prefix` before continuing. @@ -72,7 +72,7 @@ When creating a project, you will be asked for a **Project Name** and **Handle** ### Billing + Terms -You can pay for Cloud projects monthly or annually. Discounts are provided on annual plans, and to verified [Partners](/become-a-partner). Learn more about how [billing](billing.md) works. +You can pay for Cloud projects monthly or annually. Discounts are provided on annual plans, and to verified [Partners](craftcom:become-a-partner). Learn more about how [billing](billing.md) works. All Cloud plans come with a free seven-day trial! diff --git a/docs/cloud/migrating.md b/docs/cloud/migrating.md index bdb4820dd..2cead5281 100644 --- a/docs/cloud/migrating.md +++ b/docs/cloud/migrating.md @@ -16,7 +16,7 @@ The first thing we’ll tackle is updates to your code and configuration. ### Key Requirements -Your Craft project must already be running Craft {globalset:productVitals:vitalsCloudMinCraftVersion} or later to be compatible with Cloud. In addition, you will need to install the first-party [Cloud extension](extension.md). +Your Craft project must already be running Craft {{ $activeSetVars.minCraftVersion }} or later to be compatible with Cloud. In addition, you will need to install the first-party [Cloud extension](extension.md). ### Cloud Config diff --git a/docs/cloud/plugin-development.md b/docs/cloud/plugin-development.md index 5c6643e00..30fec46bc 100644 --- a/docs/cloud/plugin-development.md +++ b/docs/cloud/plugin-development.md @@ -5,7 +5,7 @@ As long as your plugin’s design and implementation follows our established [be Plugins must be compatible with at least Craft 4.6 (the minimum version of Craft required to run on Cloud), but they may support earlier versions. ::: tip -Want to test your plugin on Cloud? [Get in touch](/contact) for a free sandbox environment! +Want to test your plugin on Cloud? [Get in touch](craftcom:contact) for a free sandbox environment! ::: ## Special Considerations @@ -16,7 +16,7 @@ There are still a few things about Craft Cloud that may require reevaluation of Craft Cloud sets the `CRAFT_EPHEMERAL` config override, which tells Craft to treat file writes as unreliable (or downright impossible). Plugins should honor this setting by checking `craft\helpers\App::isEphemeral()` before trying to perform any writes to the disk. -If you must write files to disk, use the temporary directory determined by the system. **Do not hard-code this path or construct it dynamically.** Instead, use Craft’s [`Path` service](https://docs.craftcms.com/api/v5/craft-services-path.html) to get information about system directories’ locations: +If you must write files to disk, use the temporary directory determined by the system. **Do not hard-code this path or construct it dynamically.** Instead, use Craft’s [`Path` service](craft5:craft\services\Path) to get information about system directories’ locations: ```php $path = Craft::$app->getPath(); @@ -34,7 +34,7 @@ Avoid writing logs directly to a file, as its contents will disappear as soon as ### File Responses -The Cloud extension automatically handles binary responses (like when a controller action ends with [`sendContentAsFile()`](https://docs.craftcms.com/api/v5/craft-web-response.html#method-sendcontentasfile)) by uploading the data to S3 and redirecting to a pre-signed URL. +The Cloud extension automatically handles binary responses (like when a controller action ends with [`sendContentAsFile()`](craft5:craft\web\Response::sendContentAsFile())) by uploading the data to S3 and redirecting to a pre-signed URL. In general, we recommend _not_ sending binary responses that could otherwise be served as a static asset via [asset bundles](#asset-bundles)—the only situations in which Craft should be involved is when the data is based on some user input, like a dynamically-generated ZIP or PDF. Additionally, pre-signed URLs are unnecessary (and extremely inefficient) for files whose contents are static, predictable, or non-private. @@ -95,4 +95,4 @@ Cloud-compatible plugins go through the same [submission and approval process](h ## Getting Help -Please [reach out to us](/contact) if you have questions about your plugin’s compatibility. +Please [reach out to us](craftcom:contact) if you have questions about your plugin’s compatibility. diff --git a/docs/cloud/quotas.md b/docs/cloud/quotas.md index 5bb5989e2..010d89352 100644 --- a/docs/cloud/quotas.md +++ b/docs/cloud/quotas.md @@ -1,6 +1,6 @@ # Resource Limits -Every Craft Cloud project comes with generous resource quotas and simple, predictable [pricing](/cloud#pricing). +Every Craft Cloud project comes with generous resource quotas and simple, predictable [pricing](craftcom:cloud#pricing). ## Environments @@ -76,6 +76,6 @@ There are no limits to the number of concurrent or monthly queue jobs, but—lik ## Craft License -The included Craft Pro or Team license is valid as long as your project is active on Cloud, and is not transferrable to a self-hosted installation. Otherwise, its terms are identical to a normal Craft license—there are no additional restrictions on the variety or quantity of content you manage with the installation, nor the size of your audience. Cloud is subject to our [Acceptable Use Policy](/acceptable-use-policy). +The included Craft Pro or Team license is valid as long as your project is active on Cloud, and is not transferrable to a self-hosted installation. Otherwise, its terms are identical to a normal Craft license—there are no additional restrictions on the variety or quantity of content you manage with the installation, nor the size of your audience. Cloud is subject to our [Acceptable Use Policy](craftcom:acceptable-use-policy). Plugin licenses are *not* included with your Cloud subscription and will need to be purchased separately. diff --git a/docs/cloud/regions.md b/docs/cloud/regions.md index 31901733a..8256a6a8e 100644 --- a/docs/cloud/regions.md +++ b/docs/cloud/regions.md @@ -1,6 +1,6 @@ # Regions -Craft Cloud is currently available in **North America**, **Canada**, **Europe**, and **Asia/Pacific**. You select a region when creating a new project. +Craft Cloud is currently available in {{ $activeSetVars.regionSupport }}. You select a region when creating a new project. A project’s region determines where your [database](databases.md) and compute resources are located, but *not* your assets. diff --git a/docs/cloud/static-caching.md b/docs/cloud/static-caching.md index c7181862a..1eb6b6fd1 100644 --- a/docs/cloud/static-caching.md +++ b/docs/cloud/static-caching.md @@ -150,7 +150,7 @@ This allows Cloud to cache the form when it is initially requested, while always ### Commerce -Any time you access a customer’s cart via `craft.commerce.carts.cart`, Commerce either reads or writes a [cart number](/docs/commerce/5.x/system/orders-carts.html#order-numbers) to the session. This is not apt to be a problem on pages that only on-session users will access (like the cart, checkout, or account), but it can mean that common ecommerce patterns make your site more difficult to conform with the expectations of Cloud’s static cache. +Any time you access a customer’s cart via `craft.commerce.carts.cart`, Commerce either reads or writes a [cart number](/commerce/5.x/system/orders-carts.html#order-numbers) to the session. This is not apt to be a problem on pages that only on-session users will access (like the cart, checkout, or account), but it can mean that common ecommerce patterns make your site more difficult to conform with the expectations of Cloud’s static cache. In particular, displaying dynamic cart data on _every_ page (say, in the site’s header) means that Cloud will be unable to cache your site. See the [Including via Ajax](#including-via-ajax) section to learn about a technique that can help retain these dynamic sections of your site! diff --git a/docs/cloud/troubleshooting.md b/docs/cloud/troubleshooting.md index 4cb09afc1..64ed2b91a 100644 --- a/docs/cloud/troubleshooting.md +++ b/docs/cloud/troubleshooting.md @@ -28,10 +28,10 @@ The most common problems are: - **Issues cloning the repository.** Was it made private, renamed, or otherwise disconnected? - **No PHP version was declared.** Make sure you have a `php-version` key in your [`craft-cloud.yaml` config file](config.md). - **Unsupported software or package versions.** - - Your Cloud config file must include a `php-version`, set to a public release of PHP, version {globalset:productVitals:custom_cloudMinPhpVersion} or later. Patch versions are not supported. - - If you are using Node, `node-version` must be set to {globalset:productVitals:custom_cloudMinNodeVersion} or higher. Only major version numbers are supported. - - Craft CMS version {globalset:productVitals:vitalsCloudMinCraftVersion} or later is required. - - `craftcms/cloud` version {globalset:productVitals:vitalsCloudMinExtensionVersion} or later is required. + - Your Cloud config file must include a `php-version`, set to a public release of PHP, version {{ $activeSetVars.minPhpVersion }} or later. Patch versions are not supported. + - If you are using Node, `node-version` must be set to {{ $activeSetVars.minNodeVersion }} or higher. Only major version numbers are supported. + - Craft CMS version {{ $activeSetVars.minCraftVersion }} or later is required. + - `craftcms/cloud` version {{ $activeSetVars.minCloudExtensionVersion }} or later is required. - **Errors when installing Composer packages.** Do you have a valid `composer.json` and `composer.lock` file in the connected repository? (It's technically possible—but exceedingly rare—for there to be connectivity issues when downloading packages. Check your logs, try again, or reach out to support if you continue to have problems at this stage in the build.) - **Failures in the Node/NPM build script.** Something went wrong when installing your Node modules or while running the `build` script. Read more about the [build process](builds.md) and how we determine [what build script is run](config.md). From 9c315c52e0ca4430590f2fa5463084b395c6ddfc Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 17:22:19 -0700 Subject: [PATCH 09/13] Skipped heading violations --- docs/commerce/5.x/system/addresses.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/commerce/5.x/system/addresses.md b/docs/commerce/5.x/system/addresses.md index d3c112e10..d0dfe2723 100644 --- a/docs/commerce/5.x/system/addresses.md +++ b/docs/commerce/5.x/system/addresses.md @@ -14,7 +14,7 @@ In the control panel, you’ll encounter addresses within the context of [orders Customer’s addresses are managed from their user account, if you’ve [added the native Addresses field](/5.x/reference/element-types/addresses.md#setup) to Users’ field layout. Commerce also inserts a **Commerce Settings** field into the [address field layout](/5.x/reference/element-types/addresses.md#native-and-custom-fields)) with primary shipping and billing controls. -### How Addresses are Used +## How Addresses are Used Your customers will work with addresses [directly](#address-book), or [via the cart](#cart-addresses). @@ -29,7 +29,7 @@ Every order may have a shipping and billing address, and customers with accounts - Methods for working with geographic regions provided by Craft’s supporting [address repository](/5.x/reference/element-types/addresses.md#address-repository). - A separate endpoint that can be used to allow customers to [manage their saved addresses](#customer-addresses). -#### Store Addresses +### Store Addresses Each store’s primary address (set via **Commerce** → **System Settings** → **Stores**) is available via the global `currentStore` variable or the [`Stores` service](commerce5:craft\commerce\services\Stores): From 4fc92bd2d826055419dcf159401140ea32a0e0a9 Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 17:22:46 -0700 Subject: [PATCH 10/13] `storage/` dir minutiae --- docs/5.x/system/directory-structure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/5.x/system/directory-structure.md b/docs/5.x/system/directory-structure.md index 542b961d4..f6aa8a399 100644 --- a/docs/5.x/system/directory-structure.md +++ b/docs/5.x/system/directory-structure.md @@ -31,8 +31,8 @@ Purpose - `backups/` — Stores database backups that get created when you update Craft, or capture a backup via the control panel utility or [CLI](../reference/cli.md#db-backup). - `logs/` — Stores Craft’s [logs](logging.md) and PHP error logs. - - `rebrand/` — Stores the custom Login Page Logo and Site Icon files, if you’ve uploaded them. Pro - - `runtime/` — Pretty much everything in here is there for caching and logging purposes. Nothing that Craft couldn’t live without, if the folder happened to get deleted. + - `rebrand/` — Stores the custom **Login Page Logo** and **Site Icon** files, if you’ve uploaded them. Pro + - `runtime/` — Pretty much everything in here is there for caching and debugging. Nothing that Craft couldn’t live without, if the folder happened to get deleted. For the curious, here are the types of things you will find in `storage/runtime/` (though this is not a comprehensive list): From 4c955fb5caa34011970506f810123ca726e910ff Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 17:31:07 -0700 Subject: [PATCH 11/13] Lint --- docs/cloud/builds.md | 10 +++++----- docs/cloud/compatibility.md | 4 ++-- docs/cloud/config.md | 8 ++++---- docs/cloud/deployment.md | 14 ++++++++------ docs/cloud/domains.md | 4 ++-- docs/cloud/faq.md | 2 +- 6 files changed, 22 insertions(+), 20 deletions(-) diff --git a/docs/cloud/builds.md b/docs/cloud/builds.md index 41c9994e8..5a56a243a 100644 --- a/docs/cloud/builds.md +++ b/docs/cloud/builds.md @@ -10,17 +10,17 @@ Your project’s `composer.json` and `composer.lock` files determine what PHP pa Cloud installs packages by running `composer install`. -## Node +## Node.js Similarly, Cloud looks for `package.json` and `package-lock.json` files at the root of your repository (or at a path set in your [config file](config.md#config-schema)). Unlike the PHP build step, if `package-lock.json` is *missing*, this step is skipped and the deployment will continue. -To enable the Node build step, you must set a `node-version` in your [Cloud config file](config.md#config-schema). +To enable the Node.js build step, you must set a `node-version` in your [Cloud config file](config.md#config-schema). ### Build Command Cloud executes the `build` script via `npm run build` after installing the listed packages with `npm clean-install`. You can change which script is run with the `npm-script` setting in `craft-cloud.yaml`—or the directory the command is run in with `node-path`. -Special environment variables are exposed to your Node build process: +Special environment variables are exposed to your Node.js build process: - `CRAFT_CLOUD_PROJECT_ID`: UUID of the project the build is running in. - `CRAFT_CLOUD_ENVIRONMENT_ID`: UUID of the build’s target environment. @@ -42,7 +42,7 @@ You can specify a different `artifact-path` in `craft-cloud.yaml`, but when usin ### Artifact URLs -If you need to refer to the final, published URL of a build artifact from your build scripts, a file they generate, or from your Craft app, a special `CRAFT_CLOUD_ARTIFACT_BASE_URL` is provided to every environment. From Node, you can access this variable via `process.env.CRAFT_CLOUD_ARTIFACT_BASE_URL`—but be aware that it will _not_ be available (or useful) when your scripts are evaluated in a browser. +If you need to refer to the final, published URL of a build artifact from your build scripts, a file they generate, or from your Craft app, a special `CRAFT_CLOUD_ARTIFACT_BASE_URL` is provided to every environment. From Node.js, you can access this variable via `process.env.CRAFT_CLOUD_ARTIFACT_BASE_URL`—but be aware that it will _not_ be available (or useful) when your scripts are evaluated in a browser. On Cloud, that URL will always look something like this: @@ -56,7 +56,7 @@ Within that `artifacts/` directory, the file structure of your existing artifact There is no need for filename-based cache-busting, as all artifact URLs will change with every build! ::: -The [Cloud extension](extension.md) also provides the `cloud.artifactUrl()` helper function for generating URLs to files published during your build. If you have historically used the `siteUrl()` or `url()` functions to link a stylesheet or JavaScript file (or any other static asset) in your web root, use this function instead. +The [Cloud extension](extension.md) also provides the `cloud.artifactUrl()` helper function for generating URLs to files published during your build. If you have historically used the `siteUrl()` or `url()` functions to link a style sheet or JavaScript file (or any other static asset) in your web root, use this function instead. Outside of Cloud, `cloud.artifactUrl()` falls back to the automatically-determined `@web` alias—and anything in your web root will resolve normally. The special `@artifactBaseUrl` alias mirrors this behavior, and can be used in Project Config—or [anywhere else that evaluates aliases](/5.x/configure.html#control-panel-settings): diff --git a/docs/cloud/compatibility.md b/docs/cloud/compatibility.md index 952b0bbe2..31d2a2328 100644 --- a/docs/cloud/compatibility.md +++ b/docs/cloud/compatibility.md @@ -14,9 +14,9 @@ Your project must be updated to at least {{ $activeSetVars.minCraftVersion }} to PHP {{ $activeSet.minPhpVersion }} and newer are supported on Cloud. Pick a major and minor version via your project’s [`craft-cloud.yaml` config file](config.md). -## Node +## Node.js -Versions 16 and newer of Node are supported in our [builder](builds.md) via the `node-version` key in your [Cloud config file](config.md). We plan to add all [LTS releases](https://nodejs.org/en/about/previous-releases), moving forward. +Versions 16 and newer of Node.js are supported in our [builder](builds.md) via the `node-version` key in your [Cloud config file](config.md). We plan to add all [LTS releases](https://nodejs.org/en/about/previous-releases), moving forward. We recommend declaring only a major version (i.e. `20`) to receive security and stability updates, but minor releases (i.e. `18.6`) are supported. diff --git a/docs/cloud/config.md b/docs/cloud/config.md index ce3756d77..850de2e5c 100644 --- a/docs/cloud/config.md +++ b/docs/cloud/config.md @@ -5,7 +5,7 @@ Craft Cloud looks for a `craft-cloud.yaml` file in the root of the connected rep This file has a specific syntax (YAML) and [schema](#config-schema) that determines a few things about how your project is [built](builds.md), [deployed](deployment.md), and served. If there are problems with your config file, the deployment will fail with an error describing the issue. ::: tip -When you run `php craft setup/cloud` to install the [Cloud extension](extension.md), it will offer to generate a config file for you, then walk you through setting PHP and Node versions based on your project’s state. +When you run `php craft setup/cloud` to install the [Cloud extension](extension.md), it will offer to generate a config file for you, then walk you through setting PHP and Node.js versions based on your project’s state. ::: ## Config Schema @@ -24,7 +24,7 @@ php-version: '8.2' These settings are optional, and should only be used when your project is incompatible with the platform defaults. ```yaml -# Choose a major version of Node to use in your build step. +# Choose a major version of Node.js to use in your build step. node-version: '18' # Directory NPM commands will be run in. @@ -45,7 +45,7 @@ webroot: web Expanding on the above: -- `node-version` — When declared, Cloud will use this Node version in your build step. (Default: None. If you wish to run a Node build step, you must specify a version!) +- `node-version` — When declared, Cloud will use this Node.js version in your build step. (Default: None. If you wish to run a Node.js build step, you must specify a version!) - `node-path` — This directory must contain `package.json` and `package-lock.json`. Your NPM script will be run here. (Default: `''`) - `npm-script` — A single script name. Arbitrary Bash (including other `npx` commands) is not allowed. (Default: `build`) - `artifact-path` — Anything emitted from your build step must be in this directory, or it will not be uploaded to the CDN or available to your running app, in any way. (Default: Inherits the value of `webroot`) @@ -53,7 +53,7 @@ Expanding on the above: - `webroot` — If your project uses a different directory for the public web root, you should specify it here. This is relative to `app-path`. (Default: `web`) ::: tip -For the latest information on supported PHP and Node versions, see our [Cloud Services and Compatibility](compatibility.md) article. +For the latest information on supported PHP and Node.js versions, see our [Cloud Services and Compatibility](compatibility.md) article. ::: ### Redirects and Rewrites diff --git a/docs/cloud/deployment.md b/docs/cloud/deployment.md index 99c115db4..f2701725c 100644 --- a/docs/cloud/deployment.md +++ b/docs/cloud/deployment.md @@ -10,7 +10,7 @@ This process reflects our general [deployment and workflow recommendations](/5.x You can review an [environment](environments.md)’s deployment history (and the status of any active deployments) by navigating to its **Deployments** screen. -### Deployment Triggers +## Deployment Triggers Each environment in Cloud defines its own **Deploy Trigger**, which determines when it is deployed. You may select from: @@ -19,19 +19,21 @@ Each environment in Cloud defines its own **Deploy Trigger**, which determines w **On Push** is a great option for teams with a well-defined Git flow that ensures only production-ready changes are committed or merged into the selected branch. -## 1. Build Step +## Process -The first thing Cloud does is assemble PHP and Node dependencies, and package them into a new function. This process is described in greater detail in our [Build Process and Artifacts](builds.md) article. +### 1. Build Step -If your project uses Node (or has unique PHP requirements), we strongly recommend familiarizing yourself with this stage of the deployment! +The first thing Cloud does is assemble PHP and Node.js dependencies, and package them into a new function. This process is described in greater detail in our [Build Process and Artifacts](builds.md) article. -## 2. Migrations +If your project uses Node.js (or has unique PHP requirements), we strongly recommend familiarizing yourself with this stage of the deployment! + +### 2. Migrations On your new function, Cloud executes `php craft cloud/up` (a special version of `php craft up`), which applies project config changes and database migrations, and publishes all asset bundles. This must complete successfully for the deployment to continue—if a migration fails, the last-deployed version of your project will continue to serve requests. A record of this command (and its output) is added to the **Commands** section in that environment. -## 3. Deployment +### 3. Deployment When Cloud determines that the previous two steps have run without issue, it will begin serving requests from the newly-built functions. diff --git a/docs/cloud/domains.md b/docs/cloud/domains.md index 5f6636953..8514cba82 100644 --- a/docs/cloud/domains.md +++ b/docs/cloud/domains.md @@ -12,7 +12,7 @@ Every environment in your Cloud project gets a unique preview domain. Preview do project-my-handle-environment-b62dec18.preview.craft.cloud ``` -To find your preview domain, click the globe icon next to any environment in the project navigation menu. If you don't see this icon, it’s likely because it hasn’t been [deployed](deployments.md) yet! +To find your preview domain, click the globe icon next to any environment in the project navigation menu. If you don’t see this icon, it’s likely because it hasn’t been [deployed](deployments.md) yet! ::: tip Changing the handle of a project or environment may take a moment to update in our routing layer. If you have other services that rely on a consistent hostname (say, for the delivery of webhooks), consider temporarily pointing a [subdomain](#subdomains) at the environment. @@ -45,7 +45,7 @@ Cloud will provide a `CNAME` and two `TXT` records that together complete a veri Depending on your DNS provider (and the TTL or “time to live” of any existing records), it may take anywhere from a couple of minutes to 24 hours for traffic to be routed to Cloud. ::: warning -DNS records are cached for different amounts of time by different providers around the globe. You may see changes before or after your client and their customers—especially if you access the Internet from different regions. +DNS records are cached for different amounts of time by different providers around the globe. You may see changes before or after your client and their customers—especially if you access the internet from different regions. Heroku has a great [guide](https://devcenter.heroku.com/articles/custom-domains) that covers some of this technology, in the same context. If you are unfamiliar with DNS, consider starting with the [domain name glossary](https://devcenter.heroku.com/articles/custom-domains#domain-name-glossary) section, or flipping through Cloudflare’s [How DNS Works](https://www.cloudflare.com/learning/dns/what-is-dns/) series! ::: diff --git a/docs/cloud/faq.md b/docs/cloud/faq.md index 58027f310..0088ae936 100644 --- a/docs/cloud/faq.md +++ b/docs/cloud/faq.md @@ -148,7 +148,7 @@ Database and asset access credentials can be retrieved from your Craft Cloud con ### Do I have to supply my own SSL certificate for my site? -Nope! SSL is included with every domain connected to your Craft Cloud project, and requests are automatically redirected to HTTPs. +Nope! SSL is included with every domain connected to your Craft Cloud project, and requests are automatically redirected to HTTPS. From 30533297828c2f6345f2b4a09d9d14b31f099cdc Mon Sep 17 00:00:00 2001 From: August Miller Date: Thu, 28 Aug 2025 17:37:03 -0700 Subject: [PATCH 12/13] Lint (again) --- docs/cloud/config.md | 4 ++-- docs/cloud/launch-checklist.md | 2 +- docs/cloud/migrating.md | 4 ++-- docs/cloud/quotas.md | 2 +- docs/cloud/static-caching.md | 2 +- docs/cloud/troubleshooting.md | 16 ++++++++-------- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/cloud/config.md b/docs/cloud/config.md index 850de2e5c..6b62e05c1 100644 --- a/docs/cloud/config.md +++ b/docs/cloud/config.md @@ -27,7 +27,7 @@ These settings are optional, and should only be used when your project is incomp # Choose a major version of Node.js to use in your build step. node-version: '18' -# Directory NPM commands will be run in. +# Directory npm commands will be run in. node-path: buildchain # Key/name of the `script` in package.json run at build time. @@ -46,7 +46,7 @@ webroot: web Expanding on the above: - `node-version` — When declared, Cloud will use this Node.js version in your build step. (Default: None. If you wish to run a Node.js build step, you must specify a version!) -- `node-path` — This directory must contain `package.json` and `package-lock.json`. Your NPM script will be run here. (Default: `''`) +- `node-path` — This directory must contain `package.json` and `package-lock.json`. Your npm script will be run here. (Default: `''`) - `npm-script` — A single script name. Arbitrary Bash (including other `npx` commands) is not allowed. (Default: `build`) - `artifact-path` — Anything emitted from your build step must be in this directory, or it will not be uploaded to the CDN or available to your running app, in any way. (Default: Inherits the value of `webroot`) - `app-path` — `composer.json` and `composer.lock` must be located here. Cloud will run `composer install` in this directory. (Default: `''`) diff --git a/docs/cloud/launch-checklist.md b/docs/cloud/launch-checklist.md index 1d3bda880..5a2ef2152 100644 --- a/docs/cloud/launch-checklist.md +++ b/docs/cloud/launch-checklist.md @@ -8,7 +8,7 @@ Make sure you have access to your domain’s DNS management tool well in advance ### Domain Validation -This is typically the most volatile part of connecting a domain to Cloud—so make sure you’ve started the process by [adding the validation records](domains.md#adding-a-domain) to your DNS provider as soon as you know where the site will live. Don’t worry—validating a domain won't automatically send traffic to Cloud! +This is typically the most volatile part of connecting a domain to Cloud—so make sure you’ve started the process by [adding the validation records](domains.md#adding-a-domain) to your DNS provider as soon as you know where the site will live. Don’t worry—validating a domain won’t automatically send traffic to Cloud! ### TTL diff --git a/docs/cloud/migrating.md b/docs/cloud/migrating.md index 2cead5281..66d628ac1 100644 --- a/docs/cloud/migrating.md +++ b/docs/cloud/migrating.md @@ -20,7 +20,7 @@ Your Craft project must already be running Craft {{ $activeSetVars.minCraftVersi ### Cloud Config -Cloud expects a `craft-cloud.yaml` file at the root of your repository. At a minimum, this file must contain a `php-version` key to tell Cloud what PHP runtime to use. It’s also where you’ll communicate to the builder where your Composer and Node “roots” are—if you have customized your project’s directory structure, you may need to provide additional keys in this config file. +Cloud expects a `craft-cloud.yaml` file at the root of your repository. At a minimum, this file must contain a `php-version` key to tell Cloud what PHP runtime to use. It’s also where you’ll communicate to the builder where your Composer and Node.js “roots” are—if you have customized your project’s directory structure, you may need to provide additional keys in this config file. Read more about using the [Cloud config file](config.md). @@ -32,7 +32,7 @@ We have a dedicated article about [working with assets on Cloud](assets.md), and ### Artifacts, Templates, and URLs -When you deploy your site to Craft Cloud, an [automated build process](builds.md) takes care of generating artifacts via NPM and uploading them to our CDN. This means that they are not directly accessible in the webroot of your site—via the filesystem *or* over HTTP. See our recommendations for [handling references to those artifacts](builds.md#artifact-urls) in your templates. +When you deploy your site to Craft Cloud, an [automated build process](builds.md) takes care of generating artifacts via `npm` and uploading them to our CDN. This means that they are not directly accessible in the web root of your site—via the filesystem *or* over HTTP. See our recommendations for [handling references to those artifacts](builds.md#artifact-urls) in your templates. ::: tip You have control over the build process via [the `craft-cloud.yaml` config file](config.md). diff --git a/docs/cloud/quotas.md b/docs/cloud/quotas.md index 010d89352..12769ad4c 100644 --- a/docs/cloud/quotas.md +++ b/docs/cloud/quotas.md @@ -58,7 +58,7 @@ Build artifacts are also _not_ subject to this limit, as they are served from ou You can [deploy](deployment.md) as often as you like. There are no limits on the total number of “build minutes” per billing period, but each [build](builds.md) must complete within **15 minutes**. -A brand new [starter project](kb:using-the-starter-project) will typically deploy in about 90 seconds. Projects that use many plugins or have complex Node build steps will naturally take more time—long-running processes like automated tests may need to be offloaded to a different CI pipeline. +A brand new [starter project](kb:using-the-starter-project) will typically deploy in about 90 seconds. Projects that use many plugins or have complex .js build steps will naturally take more time—long-running processes like automated tests may need to be offloaded to a different CI pipeline. The final [migration](/5.x/deploy.html#migrate) phase of each deployment does *not* count toward the build time limit, but _are_ governed by the discrete command duration limit. diff --git a/docs/cloud/static-caching.md b/docs/cloud/static-caching.md index 1eb6b6fd1..c744b1e1f 100644 --- a/docs/cloud/static-caching.md +++ b/docs/cloud/static-caching.md @@ -243,4 +243,4 @@ A `MISS` value on the other hand can mean two things: Of course, every page must be requested from the origin at least once for it to be present in the cache—so a `MISS` is not always indicative of a problem! If you observe repeated misses, you may need to audit your templates for use [features that involve the session and cookies](#session-cookies)—the most common offenders will result in a `Set-Cookie` header being sent. -It's important to note that these conditions only apply to requests that would be served by Cloud’s compute layer. Requests for assets (including transforms) also go through our edge, but are governed by different rules and typically out of your control. +It’s important to note that these conditions only apply to requests that would be served by Cloud’s compute layer. Requests for assets (including transforms) also go through our edge, but are governed by different rules and typically out of your control. diff --git a/docs/cloud/troubleshooting.md b/docs/cloud/troubleshooting.md index 64ed2b91a..39845669e 100644 --- a/docs/cloud/troubleshooting.md +++ b/docs/cloud/troubleshooting.md @@ -1,8 +1,8 @@ # Troubleshooting Common Problems -### Why is my repository not showing up when starting a new project? +## Why is my repository not showing up when starting a new project? -When creating a project, we show you repositories you have access to through Git providers connected to your *personal* Craft Console account. If the repository is owned by someone else (even if they're a member of the same Craft Console organization), it may not be discoverable. Here are a few things to check: +When creating a project, we show you repositories you have access to through Git providers connected to your *personal* Craft Console account. If the repository is owned by someone else (even if they’re a member of the same Craft Console organization), it may not be discoverable. Here are a few things to check: - Was the repository forked from another repository? We can only deploy from “upstream” repositories (those that are _not_ forks). - Did you create or push code after reaching this screen? You may need to refresh the page, or wait a few minutes for the repository to be available in the API. @@ -17,11 +17,11 @@ If none of the above work, you may need to reconnect the platform to Craft Conso - On GitHub, Craft Cloud is registered as an “OAuth App,” and can be managed in your account’s **Settings** → **Applications** → **Authorized OAuth Apps** screen. Click the three dots in the **Craft Cloud** row, then select **Revoke**. - Instructions for other providers will be added as we roll out support! -Return to the **Integrations** screen in your personal Craft Console account, then click **Connect**. Carefully review the permissions, and ensure that the organization your repository lives in is properly authorized. On GitHub, this means that it will either either have a green check mark ✓ next to it, or that you've clicked **Grant** in that row. If the organization only displays a **Request** button, you may need to contact one of the administrators for access. +Return to the **Integrations** screen in your personal Craft Console account, then click **Connect**. Carefully review the permissions, and ensure that the organization your repository lives in is properly authorized. On GitHub, this means that it will either either have a green check mark ✓ next to it, or that you’ve clicked **Grant** in that row. If the organization only displays a **Request** button, you may need to contact one of the administrators for access. -### Why did my build/deployment fail? +## Why did my build/deployment fail? -Build failures always display an error in that [deployment](deployment.md)’s details page. If you believe you've encountered a temporary failure, you can try redeploying the latest commit by clicking **Deploy**—even if the environment is set to deploy **On Push**. +Build failures always display an error in that [deployment](deployment.md)’s details page. If you believe you’ve encountered a temporary failure, you can try redeploying the latest commit by clicking **Deploy**—even if the environment is set to deploy **On Push**. The most common problems are: @@ -29,11 +29,11 @@ The most common problems are: - **No PHP version was declared.** Make sure you have a `php-version` key in your [`craft-cloud.yaml` config file](config.md). - **Unsupported software or package versions.** - Your Cloud config file must include a `php-version`, set to a public release of PHP, version {{ $activeSetVars.minPhpVersion }} or later. Patch versions are not supported. - - If you are using Node, `node-version` must be set to {{ $activeSetVars.minNodeVersion }} or higher. Only major version numbers are supported. + - If you are using Node.js, `node-version` must be set to {{ $activeSetVars.minNodeVersion }} or higher. Only major version numbers are supported. - Craft CMS version {{ $activeSetVars.minCraftVersion }} or later is required. - `craftcms/cloud` version {{ $activeSetVars.minCloudExtensionVersion }} or later is required. -- **Errors when installing Composer packages.** Do you have a valid `composer.json` and `composer.lock` file in the connected repository? (It's technically possible—but exceedingly rare—for there to be connectivity issues when downloading packages. Check your logs, try again, or reach out to support if you continue to have problems at this stage in the build.) -- **Failures in the Node/NPM build script.** Something went wrong when installing your Node modules or while running the `build` script. Read more about the [build process](builds.md) and how we determine [what build script is run](config.md). +- **Errors when installing Composer packages.** Do you have a valid `composer.json` and `composer.lock` file in the connected repository? (It’s technically possible—but exceedingly rare—for there to be connectivity issues when downloading packages. Check your logs, try again, or reach out to support if you continue to have problems at this stage in the build.) +- **Failures in the Node.js/npm build script.** Something went wrong when installing your Node.js modules or while running the `build` script. Read more about the [build process](builds.md) and how we determine [what build script is run](config.md). Cloud will report specific errors that fall into one of these categories. Some errors may require that you investigate the build logs, which are also available in the deployment screen; the step that failed will display a red X. From 6c9ec57a203a75e349f7fed8b1c0e5f6a2dcb046 Mon Sep 17 00:00:00 2001 From: August Miller Date: Tue, 2 Sep 2025 14:33:45 -0700 Subject: [PATCH 13/13] No default list styles, please! --- docs/.vuepress/components/Journey.vue | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/.vuepress/components/Journey.vue b/docs/.vuepress/components/Journey.vue index 5ca80d82e..39038fd4e 100644 --- a/docs/.vuepress/components/Journey.vue +++ b/docs/.vuepress/components/Journey.vue @@ -1,5 +1,5 @@