Modernise docs

docs/how-to-guides/install.md

@@ -1,9 +1,11 @@
 # Installation guide
 
-Provided you already have [Python3](https://www.python.org/downloads/){ target=_blank } (and pip) installed, simply execute:
+With [uv](https://docs.astral.sh/uv/getting-started/installation/){ target=_blank } installed, create and activate a Python environment, then install GreatAI:
 
 ```sh
-pip install great-ai
+uv venv --python 3.13
+source .venv/bin/activate
+uv pip install great-ai
 ```
 > Python 3.12 or later is required. Python 3.13 is supported.
 
@@ -11,10 +13,13 @@ This will work on all major operating systems.
 
 ## Google Colab
 
-To use GreatAI in [Google Colab](https://colab.research.google.com){ target=_blank }, select a runtime with Python 3.12 or later and install the package:
+To use GreatAI in [Google Colab](https://colab.research.google.com){ target=_blank }, select a runtime with Python 3.12 or later, then run this notebook cell to install uv and GreatAI into the runtime's Python environment:
 
-```sh
-pip install --upgrade great-ai
+```python
+import sys
+
+!curl -LsSf https://astral.sh/uv/install.sh | sh
+!~/.local/bin/uv pip install --system --python {sys.executable} --upgrade great-ai
 ```
 
 ## Command-line tools
@@ -26,20 +31,17 @@ After installation, `great-ai` and `large-file` are available as commands. The f
 
     To help with the confusion, a CLI executable called `great_ai` (and `large_file`) are also installed. Thus, if you prefer, you can always refer to GreatAI using its underscored name variant (`great_ai`).
 
-!!! warning "Windows"
-    On Windows, you might encounter a similar warning from `pip`:
-    >  `WARNING: The scripts great-ai.exe, great_ai.exe, large-file.exe and large_file.exe are installed in 'C:\Users\...\Scripts', which is not on PATH.`
-    
-    > `Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.`
+!!! note "Windows"
+    Activate the environment with `.venv\Scripts\activate` in Command Prompt or `.\.venv\Scripts\Activate.ps1` in PowerShell instead of `source .venv/bin/activate`.
 
-    This means that `great-ai.exe` and `large-file.exe` are not in your `PATH`. Either add their containing directory ('C:\Users\...\Scripts' in this case) to your `PATH` or use `python3 -m great_ai` and `python3 -m great_ai.large_file` instead of the exe-s.
+    If `great-ai` or `large-file` is unavailable, check that the environment is active, or use `python -m great_ai` and `python -m great_ai.large_file` instead.
 
 ## Update
 
-If you wish to update to the latest version, execute:
+With your virtual environment active, update to the latest version:
 
 ```sh
-pip install --upgrade great-ai
+uv pip install --upgrade great-ai
 ```
 
 ## Bleeding edge
@@ -47,6 +49,6 @@ pip install --upgrade great-ai
 You can also install the latest (usually unreleased) version from GitHub.
 
 ```sh
-pip install --upgrade git+https://github.com/schmelczer/great-ai.git
+uv pip install --upgrade git+https://github.com/schmelczer/great-ai.git
 ```
 > Python 3.12 or later is required.

docs/how-to-guides/use-service.md

@@ -86,16 +86,19 @@ Similar to the previous approach, your code will run in a container. However, in
 To this end, you can also create a custom Docker image. It is especially useful if you have third-party dependencies, such as [PyTorch](https://pytorch.org/){ target=_blank } or [TensorFlow](https://www.tensorflow.org/){ target=_blank }.
 
 ```Dockerfile
+# syntax=docker/dockerfile:1
 FROM schmelczera/great-ai:latest
 
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
 # Remove this block if you don't have a requirements.txt
 COPY requirements.txt ./   
-RUN pip install --no-cache-dir --requirement requirements.txt
+RUN uv pip install --system --no-cache --requirement requirements.txt
 
-# If you store your models in S3 or GridFS, it may be a 
-# good idea to cache them in the image so that you don't
-# have to download it each time a container starts
-RUN large-file --backend s3 --secrets s3.ini --cache my-domain-predictor
+# Cache an S3 model using credentials available only during this RUN.
+# Remove this step if your application does not use a remote model.
+RUN --mount=type=secret,id=s3,target=/run/secrets/s3.ini,required=true \
+    large-file --backend s3 --secrets /run/secrets/s3.ini --cache my-domain-predictor
 
 # Add your application code to the image
 COPY . .
@@ -104,6 +107,32 @@ COPY . .
 CMD ["deploy.ipynb"]
 ```
 
+Create an `s3.ini` with the S3 keys described in the [configuration guide](https://great-ai.scoutinscience.com/how-to-guides/configure-service/#s3-compatible). Use concrete values in this build configuration: `ENV:` references are resolved inside the build container, which does not inherit your shell's environment. Replace `my-domain-predictor` with the key used when saving your model.
+
+Keep credentials and any local model cache out of `COPY . .` by adding these entries to your project's `.dockerignore`:
+
+```dockerignore
+s3.ini
+mongo.ini
+.env
+.cache
+```
+
+Build with [Docker BuildKit secrets](https://docs.docker.com/build/building/secrets/). This example disables Docker's layer cache so that the `large-file --cache` step runs and downloads the model into the image:
+
+```sh
+DOCKER_BUILDKIT=1 docker build --no-cache --progress=plain \
+  --secret id=s3,src=s3.ini --tag my-great-ai-service .
+```
+
+The secret mount is removed after the `RUN` instruction; the downloaded model cache remains in the image. Supply any configuration needed by the application separately at runtime. For example, an application that auto-configures S3 from `s3.ini` can use a read-only bind mount:
+
+```sh
+docker run --rm -p 6060:6060 \
+  --mount type=bind,source="$(pwd)/s3.ini",target=/app/s3.ini,readonly \
+  my-great-ai-service
+```
+
 ## Batch prediction
 
 Processing larger amounts of data on a single machine is made easy by the [GreatAI][great_ai.GreatAI]'s [process_batch][great_ai.GreatAI.process_batch] method. This relies on multiprocessing ([parallel_map][great_ai.utilities.parallel_map.parallel_map.parallel_map]) to take full advantage of all available CPU-cores.