Merge pull request #105 from depot/docs-sync-updates

Update content from depot/app

content/cache/authentication.mdx

@@ -18,8 +18,8 @@ Depot Cache supports authenticating with user tokens and organization tokens. Ad
 
 For specific details on how to configure your build tools to authenticate with Depot Cache, refer to the following guides:
 
-- [Bazel](/docs/cache/bazel)
-- [Gradle](/docs/cache/gradle)
-- [Pants](/docs/cache/pants)
-- [sccache](/docs/cache/sccache)
-- [Turborepo](/docs/cache/turbo)
+- [Bazel](/docs/cache/reference/bazel)
+- [Gradle](/docs/cache/reference/gradle)
+- [Pants](/docs/cache/reference/pants)
+- [sccache](/docs/cache/reference/sccache)
+- [Turborepo](/docs/cache/reference/turbo)

content/cli/reference.mdx

@@ -101,7 +101,7 @@ If you want to build a specific target in the bake file, you can specify it in t
 depot bake -f docker-bake.hcl original
 ```
 
-You can also save all of the targets built in a bake or compose file to the [ephemeral registry](/docs/guides/ephemeral-registry) for later use with the `--save` flag:
+You can also save all of the targets built in a bake or compose file to the [ephemeral registry](/docs/container-builds/how-to-guides/ephemeral-registry) for later use with the `--save` flag:
 
 ```shell
 depot bake -f docker-bake.hcl --save

content/guides/arm-containers.mdx → content/container-builds/how-to-guides/arm-containers.mdx

@@ -12,7 +12,7 @@ Depot removes emulation altogether.
 
 Depot is a remote Docker container build service that orchestrates optimized BuildKit builders on native CPUs for Intel (x86) and Arm (arm64).
 
-When a Docker image build is routed to Depot either via [`depot build`](/docs/cli/reference#depot-build) or [`docker build`](/docs/guides/docker-build#how-to-use-depot-with-docker), we launch optimized builders for each architecture requested with a persistent layer cache attached to them. Each builder has 16 CPUs, 32GB of memory, and at least 50GB of fast NVMe cache SSDs.
+When a Docker image build is routed to Depot either via [`depot build`](/docs/cli/reference#depot-build) or [`docker build`](/docs/container-builds/how-to-guides/docker-build#how-to-use-depot-with-docker), we launch optimized builders for each architecture requested with a persistent layer cache attached to them. Each builder has 16 CPUs, 32GB of memory, and at least 50GB of fast NVMe cache SSDs.
 
 ## How to build Docker images for Arm CPUs like M1/M2 MacBooks or AWS Graviton
 
@@ -32,14 +32,14 @@ docker build --platform linux/arm64 .
 
 We have integration guides for most of the CI providers:
 
-- [Bitbucket Pipelines](../integrations/bitbucket-pipelines)
-- [Buildkite](../integrations/buildkite)
-- [CircleCI](../integrations/circleci)
-- [GitHub Actions](../integrations/github-actions)
-- [GitLab CI](../integrations/gitlab-ci)
-- [Google Cloud Build](../integrations/google-cloud-build)
-- [Jenkins](../integrations/jenkins)
-- [Travis CI](../integrations/travis-ci)
+- [Bitbucket Pipelines](/docs/container-builds/reference/bitbucket-pipelines)
+- [Buildkite](/docs/container-builds/reference/buildkite)
+- [CircleCI](/docs/container-builds/reference/circleci)
+- [GitHub Actions](/docs/container-builds/reference/github-actions)
+- [GitLab CI](/docs/container-builds/reference/gitlab-ci)
+- [Google Cloud Build](/docs/container-builds/reference/google-cloud-build)
+- [Jenkins](/docs/container-builds/reference/jenkins)
+- [Travis CI](/docs/container-builds/reference/travis-ci)
 
 ## How to build multi-platform Docker images
 

content/guides/continuous-integration.mdx → content/container-builds/how-to-guides/continuous-integration.mdx

@@ -10,18 +10,18 @@ Depot provides a remote Docker build service that makes the image build process
 
 By routing the image build step of your CI to Depot, you can complete the image build up to 40x faster than you could in your generic CI provider. Saving you build minutes in your existing CI provider and, more importantly, saving you developer time waiting for the build to finish.
 
-The `depot build` command is a drop-in replacement for `docker build` and `docker buildx build`. Alternatively, you can [configure your local Docker CLI to use Depot as the default builder](/docs/guides/docker-build). Depot launches remote builders for both native Intel & Arm CPUs with 16 CPUs, 32 GB of memory, and a 50 GB persistent NVMe cache SSD.
+The `depot build` command is a drop-in replacement for `docker build` and `docker buildx build`. Alternatively, you can [configure your local Docker CLI to use Depot as the default builder](/docs/container-builds/how-to-guides/docker-build). Depot launches remote builders for both native Intel & Arm CPUs with 16 CPUs, 32 GB of memory, and a 50 GB persistent NVMe cache SSD.
 
 Running `depot` in a continuous integration environment is a great way to get fast and consistent builds with any CI provider. See below for documentation on integrating Depot with your CI provider.
 
 ## Providers
 
-- [AWS CodeBuild](../integrations/aws-codebuild)
-- [Bitbucket Pipelines](../integrations/bitbucket-pipelines)
-- [Buildkite](../integrations/buildkite)
-- [CircleCI](../integrations/circleci)
-- [GitHub Actions](../integrations/github-actions)
-- [GitLab CI](../integrations/gitlab-ci)
-- [Google Cloud Build](../integrations/google-cloud-build)
-- [Jenkins](../integrations/jenkins)
-- [Travis CI](../integrations/travis-ci)
+- [AWS CodeBuild](/docs/container-builds/reference/aws-codebuild)
+- [Bitbucket Pipelines](/docs/container-builds/reference/bitbucket-pipelines)
+- [Buildkite](/docs/container-builds/reference/buildkite)
+- [CircleCI](/docs/container-builds/reference/circleci)
+- [GitHub Actions](/docs/container-builds/reference/github-actions)
+- [GitLab CI](/docs/container-builds/reference/gitlab-ci)
+- [Google Cloud Build](/docs/container-builds/reference/google-cloud-build)
+- [Jenkins](/docs/container-builds/reference/jenkins)
+- [Travis CI](/docs/container-builds/reference/travis-ci)

content/guides/docker-build.mdx → content/container-builds/how-to-guides/docker-build.mdx

@@ -42,4 +42,4 @@ Again, you can confirm that builds are going to your Depot project by looking fo
 
 ## Using Depot with Docker Compose
 
-You can efficiently build Compose service images in parallel with Depot, with either `depot bake --load -f ./docker-compose.yml` or `docker compose build`. See [the Docker Compose integration guide](/docs/guides/docker-compose) for more information.
+You can efficiently build Compose service images in parallel with Depot, with either `depot bake --load -f ./docker-compose.yml` or `docker compose build`. See [the Docker Compose integration guide](/docs/container-builds/how-to-guides/docker-compose) for more information.

content/guides/docker-compose.mdx → content/container-builds/how-to-guides/docker-compose.mdx

@@ -82,7 +82,7 @@ Once configured, you can use `docker compose build` as usual. The `build` comman
 $ docker compose build
 ```
 
-See the [Docker integration guide](/docs/guides/docker-build) for more information about `depot configure-docker`.
+See the [Docker integration guide](/docs/container-builds/how-to-guides/docker-build) for more information about `depot configure-docker`.
 
 ### Caveats
 

content/guides/local-development.mdx → content/container-builds/how-to-guides/local-development.mdx

@@ -51,4 +51,4 @@ depot configure-docker
 docker build -t my-image:latest .
 ```
 
-For a full guide on using Depot via your existing `docker build` of `docker compose` commands, see our [Docker integration guide](/docs/guides/docker-build#docker-compose-build).
+For a full guide on using Depot via your existing `docker build` of `docker compose` commands, see our [Docker integration guide](/docs/container-builds/how-to-guides/docker-build#docker-compose-build).

content/container-builds/how-to-guides/optimal-dockerfiles.mdx

@@ -0,0 +1,14 @@
+---
+title: Best practice Dockerfiles
+ogTitle: Best practice Dockerfiles
+description: A set of best practice Dockerfiles for building Docker images
+---
+
+We've assembled some best practice Dockerfiles for building Docker images for several different languages:
+
+## Guides
+
+- [Dockerfile for Node.js using `pnpm`](/docs/container-builds/how-to-guides/optimal-dockerfiles/node-pnpm-dockerfile)
+- [Dockerfile for Python using `uv`](/docs/container-builds/how-to-guides/optimal-dockerfiles/python-uv-dockerfile)
+- [Dockerfile for Python using `poetry`](/docs/container-builds/how-to-guides/optimal-dockerfiles/python-poetry-dockerfile)
+- [Dockerfile for Rust](/docs/container-builds/how-to-guides/optimal-dockerfiles/rust-dockerfile)

content/languages/node.mdx → content/container-builds/how-to-guides/optimal-dockerfiles/node.mdx

@@ -8,4 +8,4 @@ We've assembled some best practice Dockerfiles for building Docker images for No
 
 ## Guides
 
-- [Dockerfile for Node.js using `pnpm`](/docs/languages/node-pnpm-dockerfile)
+- [Dockerfile for Node.js using `pnpm`](/docs/container-builds/how-to-guides/optimal-dockerfiles/node-pnpm-dockerfile)

content/languages/python.mdx → content/container-builds/how-to-guides/optimal-dockerfiles/python.mdx

@@ -8,5 +8,5 @@ We've assembled some best practice Dockerfiles for building Docker images for Py
 
 ## Guides
 
-- [Dockerfile for Python using `uv`](/docs/languages/python-uv-dockerfile)
-- [Dockerfile for Python using `poetry`](/docs/languages/python-poetry-dockerfile)
+- [Dockerfile for Python using `uv`](/docs/container-builds/how-to-guides/optimal-dockerfiles/python-uv-dockerfile)
+- [Dockerfile for Python using `poetry`](/docs/container-builds/how-to-guides/optimal-dockerfiles/python-poetry-dockerfile)

content/container-builds/overview.mdx

@@ -42,15 +42,15 @@ Using Depot for your Docker image builds is as straightforward as replacing your
 
 We have extensive integrations with most major CI providers and developer tools to make it easy to use Depot remote container builds in your existing workflows. You can read more about how to leverage our remote container build service in your existing CI provider:
 
-- [AWS CodeBuild](../integrations/aws-codebuild)
-- [Bitbucket Pipelines](../integrations/bitbucket-pipelines)
-- [Buildkite](../integrations/buildkite)
-- [CircleCI](../integrations/circleci)
-- [GitHub Actions](../integrations/github-actions)
-- [GitLab CI](../integrations/gitlab-ci)
-- [Google Cloud Build](../integrations/google-cloud-build)
-- [Jenkins](../integrations/jenkins)
-- [Travis CI](../integrations/travis-ci)
+- [AWS CodeBuild](/docs/container-builds/reference/aws-codebuild)
+- [Bitbucket Pipelines](/docs/container-builds/reference/bitbucket-pipelines)
+- [Buildkite](/docs/container-builds/reference/buildkite)
+- [CircleCI](/docs/container-builds/reference/circleci)
+- [GitHub Actions](/docs/container-builds/reference/github-actions)
+- [GitLab CI](/docs/container-builds/reference/gitlab-ci)
+- [Google Cloud Build](/docs/container-builds/reference/google-cloud-build)
+- [Jenkins](/docs/container-builds/reference/jenkins)
+- [Travis CI](/docs/container-builds/reference/travis-ci)
 
 #### OIDC support
 
@@ -60,9 +60,9 @@ We support OIDC trust relationships with GitHub, CircleCI, Buildkite, and Mint s
 
 We can accelerate your image builds for other developer tools like Dev Containers & Docker Compose. You can either use our drop-in replacements for `docker build` and `docker bake`, or configure Docker to use Depot as the remote builder.
 
-- [How to use Depot in local development](/docs/guides/local-development)
-- [How to use Depot with Docker & Docker Compose](/docs/guides/docker-build)
-- [How to use Depot with Dev Containers](/docs/guides/devcontainers)
+- [How to use Depot in local development](/docs/container-builds/how-to-guides/local-development)
+- [How to use Depot with Docker & Docker Compose](/docs/container-builds/how-to-guides/docker-build)
+- [How to use Depot with Dev Containers](/docs/container-builds/how-to-guides/devcontainers)
 
 ### Build autoscaling
 
@@ -72,7 +72,7 @@ We offer autoscaling for our remote container builds. By default, all builds for
 
 We offer a built-in ephemeral registry that you can use to save the images from your `depot build` and `depot bake` commands to a temporary registry. You can then pull those images back down or push them to your final registry as you see fit.
 
-[Learn more about the ephemeral registry](/docs/guides/ephemeral-registry)
+[Learn more about the ephemeral registry](/docs/container-builds/how-to-guides/ephemeral-registry)
 
 ## How does it work?
 
@@ -82,7 +82,7 @@ Builder instances come with 16 CPUs, 32GB of memory, and an SSD disk for layer c
 
 We offer native Intel and Arm builder instances for all projects. Hence, both architectures build with zero emulation, and you don't have to run your own build runners to get native multi-platform images.
 
-Once built, the image can be left in the build cache (the default) or downloaded to the local Docker daemon with `--load` or pushed to a registry with `--push`. If `--push` is specified, the image is pushed to the registry directly from the remote builder via high-speed network links and does not use your local network connection. See our [private registry guide](/docs/guides/private-registries) for more details on pushing to private Docker registries like Amazon ECR or Docker Hub.
+Once built, the image can be left in the build cache (the default) or downloaded to the local Docker daemon with `--load` or pushed to a registry with `--push`. If `--push` is specified, the image is pushed to the registry directly from the remote builder via high-speed network links and does not use your local network connection. See our [private registry guide](/docs/container-builds/how-to-guides/private-registries) for more details on pushing to private Docker registries like Amazon ECR or Docker Hub.
 
 You can generally plug Depot into your existing Docker image build workflows with minimal changes, whether you're building locally or in CI.
 
@@ -126,15 +126,15 @@ We have built several integrations to make it easy to plug Depot into your exist
 
 You can read more about how to leverage our remote container build service in your existing CI provider of choice:
 
-- [AWS CodeBuild](../integrations/aws-codebuild)
-- [Bitbucket Pipelines](../integrations/bitbucket-pipelines)
-- [Buildkite](../integrations/buildkite)
-- [CircleCI](../integrations/circleci)
-- [GitHub Actions](../integrations/github-actions)
-- [GitLab CI](../integrations/gitlab-ci)
-- [Google Cloud Build](../integrations/google-cloud-build)
-- [Jenkins](../integrations/jenkins)
-- [Travis CI](../integrations/travis-ci)
+- [AWS CodeBuild](/docs/container-builds/reference/aws-codebuild)
+- [Bitbucket Pipelines](/docs/container-builds/reference/bitbucket-pipelines)
+- [Buildkite](/docs/container-builds/reference/buildkite)
+- [CircleCI](/docs/container-builds/reference/circleci)
+- [GitHub Actions](/docs/container-builds/reference/github-actions)
+- [GitLab CI](/docs/container-builds/reference/gitlab-ci)
+- [Google Cloud Build](/docs/container-builds/reference/google-cloud-build)
+- [Jenkins](/docs/container-builds/reference/jenkins)
+- [Travis CI](/docs/container-builds/reference/travis-ci)
 
 ## Common opportunities to use Depot remote container builds
 
@@ -144,11 +144,11 @@ Depot works best in the following scenarios:
 
 1. **Building the Docker image is slow in CI** — common CI providers often do not have native support for the Docker build cache. Instead, they require layer cache to be saved to and loaded from tarballs over slow networks. Often, CI providers offer limited resources as well, causing overall build time to be long.
 
-   Depot works within your existing CI workflow by swapping out the call to `docker build` with `depot build`. Or by configuring `docker` in your environment to leverage Depot. See [our continuous integration guides](/docs/guides/continuous-integration) for more information.
+   Depot works within your existing CI workflow by swapping out the call to `docker build` with `depot build`. Or by configuring `docker` in your environment to leverage Depot. See [our continuous integration guides](/docs/container-builds/how-to-guides/continuous-integration) for more information.
 
 2. **You need to build images for multiple platforms/multiple architectures (Intel and Arm)** — today, you're often stuck with managing your own build runner or relying on slow emulation in order to build multi-platform images. For example, CI providers usually run their workflows on Intel machines. So, to create a Docker image for Arm, you either have to launch your own BuildKit builder for Arm and connect to it from your CI provider. Or build your Arm image with slow QEMU emulation.
 
-   Depot can [build multi-platform and Arm images](/docs/guides/arm-containers) natively with zero-emulation and without running additional infrastructure.
+   Depot can [build multi-platform and Arm images](/docs/container-builds/how-to-guides/arm-containers) natively with zero-emulation and without running additional infrastructure.
 
 3. **Building the Docker image on your local machine is slow or expensive** — Docker can hog resources on developer machines, taking up valuable network, CPU, and memory resources. Depot executes builds on remote compute infrastructure; it offloads the CPU, memory, disk, and network resources required to that remote builder. If builds on your local machine are slow due to constrained compute, disk, or network, `depot build` eliminates the need to rely on your local environment.
 

content/container-builds/quickstart.mdx

@@ -66,15 +66,15 @@ There is the option to configure your existing `docker build` commmands to lever
 
 Integrating Depot into your CI workflow is a very similar process. Depot works with any CI provider. You can find guides for our most popular providers:
 
-- [AWS CodeBuild](../integrations/aws-codebuild)
-- [Bitbucket Pipelines](../integrations/bitbucket-pipelines)
-- [Buildkite](../integrations/buildkite)
-- [CircleCI](../integrations/circleci)
-- [GitHub Actions](../integrations/github-actions)
-- [GitLab CI](../integrations/gitlab-ci)
-- [Google Cloud Build](../integrations/google-cloud-build)
-- [Jenkins](../integrations/jenkins)
-- [Travis CI](../integrations/travis-ci)
+- [AWS CodeBuild](/docs/container-builds/reference/aws-codebuild)
+- [Bitbucket Pipelines](/docs/container-builds/reference/bitbucket-pipelines)
+- [Buildkite](/docs/container-builds/reference/buildkite)
+- [CircleCI](/docs/container-builds/reference/circleci)
+- [GitHub Actions](/docs/container-builds/reference/github-actions)
+- [GitLab CI](/docs/container-builds/reference/gitlab-ci)
+- [Google Cloud Build](/docs/container-builds/reference/google-cloud-build)
+- [Jenkins](/docs/container-builds/reference/jenkins)
+- [Travis CI](/docs/container-builds/reference/travis-ci)
 
 ## Adding a build minute usage cap
 

content/api/overview.mdx → content/container-builds/reference/api-overview.mdx

@@ -12,7 +12,7 @@ We currently support the following SDKs for interacting with Depot:
 
 ## Authentication
 
-Authentication to the API is handled via an `Authorization` header with the value being an Organization Token that you generate inside of your Organization Settings. See the [Authentication docs](/docs/api/authentication) for more details.
+Authentication to the API is handled via an `Authorization` header with the value being an Organization Token that you generate inside of your Organization Settings. See the [Authentication docs](/docs/container-builds/reference/api-authentication) for more details.
 
 ## Security