Improvements to the README

README.md

@@ -1,13 +1,14 @@
 # uv-docker-example
 
-An example project for using uv in Dockerfiles.
+An example project for using uv in Docker images, with a focus on best practices for developing with
+the project mounted in the local image.
 
-See the [uv Docker integration guide](https://docs.astral.sh/uv/guides/integration/docker/) for more details.
+See the [uv Docker integration guide](https://docs.astral.sh/uv/guides/integration/docker/) for more
+background.
 
 ## Trying it out
 
 A [`run.sh`](./run.sh) utility is provided for quickly building the image and starting a container.
-
 This script demonstrates best practices for developing using the container, using bind mounts for
 the project and virtual environment directories.
 
@@ -19,37 +20,25 @@ $ ./run.sh
 
 Then, check out [`http://localhost:8000`](http://localhost:8000) to see the website.
 
+A Docker compose configuration is also provided to demonstrate best practices for developing using
+the container with Docker compose. Docker compose is more complex than using `docker run`, but has
+more robust support for various workflows.
+
 To build and run the web application using Docker compose:
 
 ```
 docker compose up --watch 
 ```
 
+By default, the image is set up to start the web application. However, a command-line interface is
+provided for demonstration purposes as well. 
+
 To run the command-line entrypoint in the container:
 
 ```console
 $ ./run.sh hello
 ```
 
-To check that the environment is up-to-date after image builds:
-
-```console
-$ ./run.sh uv sync --frozen
-Audited 2 packages ...
-```
-
-To enter a `bash` shell in the container:
-
-```console
-$ ./run.sh /bin/bash
-```
-
-To build the image without running anything:
-
-```console
-$ docker build .
-```
-
 ## Project overview
 
 ### Dockerfile
@@ -59,6 +48,7 @@ The [`Dockerfile`](./Dockerfile) defines the image and includes:
 - Installation of uv
 - Installing the project dependencies and the project separately for optimal image build caching
 - Placing environment executables on the `PATH`
+- Running the web application
 
 ### Dockerignore file
 
@@ -88,3 +78,24 @@ entrypoint and a basic FastAPI application — both of which just display "hello
 
 The project at [`pyproject.toml`](./pyproject.toml) includes Ruff as an example development
 dependency, includes FastAPI as a dependency, and defines a `hello` entrypoint for the application.
+
+## Useful commands
+
+To check that the environment is up-to-date after image builds:
+
+```console
+$ ./run.sh uv sync --frozen
+Audited 2 packages ...
+```
+
+To enter a `bash` shell in the container:
+
+```console
+$ ./run.sh /bin/bash
+```
+
+To build the image without running anything:
+
+```console
+$ docker build .
+```