Cloud Docset

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' },
 };

docs/.vuepress/components/Journey.vue

@@ -1,5 +1,5 @@
 <template>
-    <ol class="journey">
+    <ol class="journey theme-default-content-override">
         <li v-for="(segment, i) in segments" :key="i" class="step">
             {{ ' ' }}
             <span class="step-label">{{ segment }}</span><span v-if="i < (segments.length - 1)" class="step-arrow" aria-hidden="true">&rarr;</span>

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",

docs/.vuepress/sets/craft-cloud.js

@@ -0,0 +1,79 @@
+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,
+  globalVars: {
+    supportEmail: '[email protected]',
+    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: {
+    "/": [
+      {
+        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",
+        ],
+      },
+    ],
+  },
+};

docs/.vuepress/theme/components/DocSetPanel.vue

@@ -30,18 +30,6 @@
           <span>{{ set.setTitle ? set.setTitle : set.title }}</span>
         </RouterLink>
       </li>
-
-
-      <!-- Special handling for external Cloud docs! -->
-      <li v-if="$page.frontmatter.home" class="doc-set">
-        <a class="doc-set-link" href="https://craftcms.com/knowledge-base/cloud" target="_blank">
-          <span class="mr-2 inline-block relative set-icon">
-            <img src="/docs/icons/icon-cloud.svg" width="16" height="16" alt="">
-          </span>
-
-          <span>Craft Cloud</span>
-        </a>
-      </li>
     </ul>
     <div v-if="$activeSet" class="doc-set-current">
       <RouterLink :to="defaultUri($activeSet)" class="flex items-center">

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, {

docs/.vuepress/theme/global-components/Email.vue

@@ -0,0 +1,20 @@
+<script>
+export default {
+  functional: true,
+  props: {
+    address: String,
+  },
+  render(h, { props }) {
+    return h(
+      "a",
+      {
+        attrs: {
+          class: 'mailto',
+          href: `mailto:${props.address}`,
+        },
+      },
+      props.address,
+    );
+  },
+};
+</script>

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. <badge type="edition" vertical="middle" title="Craft Pro only">Pro</badge>
-  - `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. <badge type="edition" vertical="middle" title="Craft Pro only">Pro</badge>
+  - `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):
 

docs/cloud/README.md

@@ -0,0 +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.
+
+<See url="https://craftcms.com/cloud" label="Craft Cloud" description="Take a tour of Cloud’s main features." />
+
+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.
+:::

docs/cloud/assets.md

@@ -0,0 +1,142 @@
+# Assets
+
+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](extension.md)’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](/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](/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](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
+
+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](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.
+
+### 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](/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.