Shift the order of some of the Docker guide content (#6664)

docs/guides/integration/docker.md

@@ -63,11 +63,20 @@ WORKDIR /app
 RUN uv sync --frozen
 ```
 
+Then, to start your application by default:
+
+```dockerfile title="Dockerfile"
+# Presuming there is a `my_app` command provided by the project
+CMD ["uv", "run", "my_app"]
+```
+
 !!! tip
 
     It is best practice to use [intermediate layers](#intermediate-layers) separating installation
     of dependencies and the project itself to improve Docker image build times.
 
+## Activating the environment
+
 Once the project is installed, you can either _activate_ the virtual environment:
 
 ```dockerfile title="Dockerfile"
@@ -77,19 +86,12 @@ ENV VIRTUAL_ENV=/app/.venv
 ENV PATH="/app/.venv/bin:$PATH"
 ```
 
-Or, you can use `uv run` to run commands in the environment:
+Or, you can use `uv run` for any commands that require the environment:
 
 ```dockerfile title="Dockerfile"
 RUN uv run some_script.py
 ```
 
-And, to start your application by default:
-
-```dockerfile title="Dockerfile"
-# Presuming there is a `my_app` command provided by the project
-CMD ["uv", "run", "my_app"]
-```
-
 ## Using installed tools
 
 To use installed tools, ensure the [tool bin directory](../../concepts/tools.md#the-bin-directory)
@@ -116,72 +118,8 @@ $ docker run -it $(docker build -q .) /bin/bash -c "cowsay -t hello"
 
 To determine the tool bin directory, run `uv tool dir --bin` in the container.
 
-## Using the pip interface
-
-### Installing a package
-
-The system Python environment is safe to use this context, since a container is already isolated.
-The `--system` flag can be used to install in the system environment:
-
-```dockerfile title="Dockerfile"
-RUN uv pip install --system ruff
-```
-
-To use the system Python environment by default, set the `UV_SYSTEM_PYTHON` variable:
-
-```dockerfile title="Dockerfile"
-ENV UV_SYSTEM_PYTHON=1
-```
-
-Alternatively, a virtual environment can be created and activated:
-
-```dockerfile title="Dockerfile"
-RUN uv venv /opt/venv
-# Use the virtual environment automatically
-ENV VIRTUAL_ENV=/opt/venv
-# Place entry points in the environment at the front of the path
-ENV PATH="/opt/venv/bin:$PATH"
-```
-
-When using a virtual environment, the `--system` flag should be omitted from uv invocations:
-
-```dockerfile title="Dockerfile"
-RUN uv pip install ruff
-```
-
-### Installing requirements
-
-To install requirements files, copy them into the container:
-
-```dockerfile title="Dockerfile"
-COPY requirements.txt .
-RUN uv pip install -r requirements.txt
-```
-
-### Installing a project
-
-When installing a project alongside requirements, it is best practice to separate copying the
-requirements from the rest of the source code. This allows the dependencies of the project (which do
-not change often) to be cached separately from the project itself (which changes very frequently).
-
-```dockerfile title="Dockerfile"
-COPY pyproject.toml .
-RUN uv pip install -r pyproject.toml
-COPY . .
-RUN uv pip install -e .
-```
-
 ## Optimizations
 
-### Using uv temporarily
-
-If uv isn't needed in the final image, the binary can be mounted in each invocation:
-
-```dockerfile title="Dockerfile"
-RUN --mount=from=ghcr.io/astral-sh/uv,source=/uv,target=/bin/uv \
-    uv pip install --system ruff
-```
-
 ### Compiling bytecode
 
 Compiling Python source files to bytecode is typically desirable for production images as it tends
@@ -207,17 +145,21 @@ improve performance across builds:
 
 ```dockerfile title="Dockerfile"
 RUN --mount=type=cache,target=/root/.cache/uv \
- ./uv pip install -r requirements.txt -->
+    uv sync
 ```
 
-Note the cache directory's location can be determined with the `uv cache dir` command.
-Alternatively, the cache can be set to a constant location:
+If you're not mounting the cache, image size can be reduced by using the `--no-cache` flag or
+setting `UV_NO_CACHE`.
 
-```dockerfile title="Dockerfile"
-ENV UV_CACHE_DIR=/opt/uv-cache/
-```
+!!! note
+
+    The cache directory's location can be determined with the `uv cache dir` command.
 
-If not mounting the cache, image size can be reduced with `--no-cache` flag.
+    Alternatively, the cache can be set to a constant location:
+
+    ```dockerfile title="Dockerfile"
+    ENV UV_CACHE_DIR=/opt/uv-cache/
+    ```
 
 ### Intermediate layers
 
@@ -259,3 +201,67 @@ _contents_ are not copied into the image until the final `uv sync` command.
     `--no-install-workspace` flag which excludes the project _and_ any workspace members.
 
     If you want to remove specific packages from the sync, use `--no-install-package <name>`.
+
+### Using uv temporarily
+
+If uv isn't needed in the final image, the binary can be mounted in each invocation:
+
+```dockerfile title="Dockerfile"
+RUN --mount=from=ghcr.io/astral-sh/uv,source=/uv,target=/bin/uv \
+    uv sync
+```
+
+## Using the pip interface
+
+### Installing a package
+
+The system Python environment is safe to use this context, since a container is already isolated.
+The `--system` flag can be used to install in the system environment:
+
+```dockerfile title="Dockerfile"
+RUN uv pip install --system ruff
+```
+
+To use the system Python environment by default, set the `UV_SYSTEM_PYTHON` variable:
+
+```dockerfile title="Dockerfile"
+ENV UV_SYSTEM_PYTHON=1
+```
+
+Alternatively, a virtual environment can be created and activated:
+
+```dockerfile title="Dockerfile"
+RUN uv venv /opt/venv
+# Use the virtual environment automatically
+ENV VIRTUAL_ENV=/opt/venv
+# Place entry points in the environment at the front of the path
+ENV PATH="/opt/venv/bin:$PATH"
+```
+
+When using a virtual environment, the `--system` flag should be omitted from uv invocations:
+
+```dockerfile title="Dockerfile"
+RUN uv pip install ruff
+```
+
+### Installing requirements
+
+To install requirements files, copy them into the container:
+
+```dockerfile title="Dockerfile"
+COPY requirements.txt .
+RUN uv pip install -r requirements.txt
+```
+
+### Installing a project
+
+When installing a project alongside requirements, it is best practice to separate copying the
+requirements from the rest of the source code. This allows the dependencies of the project (which do
+not change often) to be cached separately from the project itself (which changes very frequently).
+
+```dockerfile title="Dockerfile"
+COPY pyproject.toml .
+RUN uv pip install -r pyproject.toml
+COPY . .
+RUN uv pip install -e .
+```