diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..956b2c7
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,19 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+# ffmpeg dependencies for vcsi
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    libjpeg-dev \
+    zlib1g-dev \
+    build-essential \
+    curl \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN uv tool install vcsi
+
+WORKDIR /work
+
+CMD ["vcsi"]
\ No newline at end of file
diff --git a/README.md b/README.md
index 7cf9c30..c29372d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,76 @@
-# vcsi-docker
+# VCSI Docker
 
-A simple Docker image for running vcsi to generate video contact sheets from local media files
\ No newline at end of file
+This repository builds a small Docker image for [vcsi](https://github.com/amietn/vcsi), a tool that creates video contact sheets.
+
+## Build
+
+Build the image from the repository root:
+
+```bash
+docker build -t vcsi-docker .
+```
+
+## Run
+
+Run `vcsi` against a video file by mounting the current directory into the container:
+
+```bash
+docker run --rm -v "$PWD:/work" vcsi-docker vcsi input.mp4 -o output.jpg
+```
+
+Run `vcsi` across every video in the current directory (without recursive mode):
+
+```bash
+docker run --rm -v "$PWD:/work" vcsi-docker vcsi . -o .
+```
+
+If you want an interactive shell entry point, you can also pass any `vcsi` arguments directly:
+
+```bash
+docker run --rm -v "$PWD:/work" vcsi-docker vcsi --help
+```
+
+If you want to open a shell in the container first, use `-it` and `/bin/bash`:
+
+```bash
+docker run --rm -it -v "$PWD:/work" vcsi-docker /bin/bash
+```
+
+## Useful Flags
+
+These are some of the most useful options from the upstream `vcsi` README:
+
+- `-o, --output` - output file path
+- `-w, --width` - width of the generated contact sheet
+- `-g, --grid` - grid size, for example `4x4`
+- `-t, --show-timestamp` - show timestamps on each frame
+- `-s, --num-samples` - number of samples to capture
+- `-a, --accurate` - slower but more accurate frame capture
+- `-A, --accurate-delay-seconds` - decode a short window before each capture when using accurate mode
+- `-r, --recursive` - process directories recursively
+- `--fast` - prioritize speed over output quality
+- `-S, --actual-size` - use full-size thumbnails
+- `-O, --thumbnail-output` - keep thumbnails in a directory instead of deleting them
+- `--interval` - capture frames at a fixed interval
+- `--frame-type` - capture only a given frame type such as `I`, `B`, `P`, or `key`
+- `--timestamp-format` - customize timestamp text
+- `--metadata-position` - place metadata at `top`, `bottom`, or `hidden`
+- `--background-color` - set the background color
+- `--metadata-font-color` - set metadata text color
+- `--timestamp-font-color` - set timestamp text color
+- `--timestamp-background-color` - set the timestamp background color
+- `--timestamp-border-mode` - draw timestamp text with a border instead of a rectangle
+- `--timestamp-border-size` - set timestamp border thickness
+- `--template` - use a custom metadata template
+
+For the full upstream flag list, run:
+
+```bash
+docker run --rm -v "$PWD:/work" vcsi-docker vcsi --help
+```
+
+## License
+
+This image installs the upstream [vcsi](https://github.com/amietn/vcsi) project,
+which is licensed under MIT. If you redistribute this repository or a built
+image, keep the upstream license notice and attribution with the distribution.