Improve template caches invalidation

docs.json

@@ -19,6 +19,7 @@
             "pages": [
               "template/quickstart",
               "template/how-it-works",
+              "template/caching",
               {
                 "group": "Customization",
                 "icon": "wand-magic-sparkles",

template/caching.mdx

@@ -0,0 +1,98 @@
+---
+title: "Caching"
+description: "How the caching process works"
+icon: "layer-group"
+---
+
+The caching concept is similar to [Docker's layer caching](https://docs.docker.com/build/cache/). For each layer command (`.copy()`, `.runCmd()`, `.setEnvs()`, etc.), we create a new layer on top of the existing.
+Each layer is cached based on the command and its inputs (e.g., files copied, command executed, environment variables set).
+If a layer command is unchanged and its inputs are the same as in any previous build, we reuse the cached layer instead of rebuilding it.
+
+This significantly speeds up the build process, especially for large templates with many layers.
+The cache is scoped to the team, so even if you have multiple templates, they can share the same cache if they have identical layers.
+
+## Invalidation
+You can invalidate the caches only partially, or for the whole template.
+
+### Partial
+Force rebuild from the next instruction, use the method:
+
+<CodeGroup dropdown>
+
+```typescript highlight={3}
+const template = Template()
+  .fromBaseImage()
+  .skipCache()
+  .runCmd("echo 'Hello, World!'")
+```
+
+```python highlight={4}
+template = (
+    Template()
+    .from_base_image()
+    .skip_cache()
+    .run_cmd("echo 'Hello, World!'")
+)
+```
+
+</CodeGroup>
+
+This will force rebuild from the next instruction, invalidating the cache for all subsequent instructions in the template.
+
+### Whole Template
+To force rebuild the whole template, you can use also `skipCache`/`skip_cache` parameter in the `Template.build` method:
+
+<CodeGroup dropdown>
+
+```typescript wrap highlight={3}
+Template.build(template, {
+  alias: 'my-template',
+  skipCache: true, // Configure cache skip (except for files)
+})
+```
+
+```python wrap highlight={4}
+Template.build(
+    template,
+    alias="my-template",
+    skip_cache=True,  # Configure cache skip (except for files)
+)
+```
+
+</CodeGroup>
+
+This will skip the cache usage for the whole template build.
+
+## Files Caching
+When using the `.copy()` command, we cache the files based on their content. If the files haven't changed since the last build, we reuse them from the files cache.
+
+We differ from Docker here. Because we build the template on our infrastructure, we use improved caching on files level.
+Even if you invalidate the layer before `.copy()` (e.g., by changing ENV variables), we'll reuse the already uploaded files.
+The `copy()` command will still be re-executed, but the files for the layer will be reused from the files cache, no need to upload them from your computer again.
+
+To invalidate the cache for all subsequent instructions in the template **AND** the layer files cache, use the `forceUpload`/`force_upload` parameter.
+
+<CodeGroup dropdown>
+
+```typescript highlight={3}
+const template = Template()
+  .fromBaseImage()
+  .copy("config.json", "/app/config.json", { forceUpload: true })
+```
+
+```python highlight={4}
+template = (
+    Template()
+    .from_base_image()
+    .copy("config.json", "/app/config.json", force_upload=True)
+)
+```
+
+</CodeGroup>
+
+## Use Case for Caching
+You can leverage caching to create templates with multiple variants (e.g., different RAM or CPU) while reusing the common layers.
+When building the template, just change the template alias to a specific RAM/CPU configuration (e.g., `my-template-2cpu-2gb`, `my-template-1cpu-4gb`), keep the rest of the template definition the same, and the build process will reuse the cached layers.
+
+## Optimize Build Times
+To optimize build times, place frequently changing commands (e.g., copying source code) towards the end of your template definition. This way, earlier layers can be cached and reused more often.

template/customization/defining-template.mdx

@@ -74,9 +74,6 @@ template.copy([
   { src: "package.json", dest: "/app/package.json" },
 ]);
 
-// Force upload (bypass cache)
-template.copy("config.json", "/app/config.json", { forceUpload: true });
-
 // Copy with user and mode options
 template.copy("config.json", "/app/config.json", {
   user: "appuser",
@@ -94,8 +91,8 @@ template.copy([
     {"src": "package.json", "dest": "/app/package.json"},
 ])
 
-# Force upload (bypass cache)
-template.copy("config.json", "/app/config.json", force_upload=True)
+# Copy with user and mode options
+template.copy("config.json", "/app/config.json", user="appuser", mode=0o644)
 ```
 
 </CodeGroup>
@@ -239,24 +236,6 @@ template.set_envs({
 
 </CodeGroup>
 
-### Invalidating caches
-
-Force rebuild from the next instruction:
-
-<CodeGroup dropdown>
-
-```typescript
-template.skipCache()
-```
-
-```python
-template.skip_cache()
-```
-
-</CodeGroup>
-
-This will invalidate the cache for all subsequent instructions in the template.
-
 ### Running commands
 
 Execute shell commands during template build:

template/how-it-works.mdx

@@ -25,23 +25,4 @@ We call this sandbox snapshot a _sandbox template_.
 </Note>
 
 ## Caching
-The caching concept is similar to [Docker's layer caching](https://docs.docker.com/build/cache/). For each layer command (`.copy()`, `.runCmd()`, `.setEnvs()`, etc.), we create a new layer on top of the existing.
-Each layer is cached based on the command and its inputs (e.g., files copied, command executed, environment variables set).
-If a layer command is unchanged and its inputs are the same as in any previous build, we reuse the cached layer instead of rebuilding it.
-
-This significantly speeds up the build process, especially for large templates with many layers.
-The cache is scoped to the team, so even if you have multiple templates, they can share the same cache if they have identical layers.
-
-### Files Caching
-When using the `.copy()` command, we cache the files based on their content. If the files haven't changed since the last build, we reuse them from the files cache.
-
-We differ from Docker here. Because we build the template on our infrastructure, we use improved caching on files level.
-Even if you invalidate the layer before `.copy()` (e.g., by changing ENV variables), we'll reuse the already uploaded files.
-The `copy()` command will still be re-executed, but the files for the layer will be reused from the files cache, no need to upload them from your computer again.
-
-### Use Case for Caching
-You can leverage caching to create templates with multiple variants (e.g., different RAM or CPU) while reusing the common layers.
-When building the template, just change the template alias to a specific RAM/CPU configuration (e.g., `my-template-2cpu-2gb`, `my-template-1cpu-4gb`), keep the rest of the template definition the same, and the build process will reuse the cached layers.
-
-### Optimize Build Times
-To optimize build times, place frequently changing commands (e.g., copying source code) towards the end of your template definition. This way, earlier layers can be cached and reused more often.
+To learn more about caching, please refer to the [Caching](/template/caching) section.