diff --git a/README.md b/README.md
new file mode 100644
index 0000000..278dd97
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# package-cache
+
+[![status-badge](https://ci.worn.eu/api/badges/containers/package-cache/status.svg)](https://ci.worn.eu/containers/package-cache)
+
+This container image is meant to be used as a software package caching proxy.
+It employs the SSL bumping feature built into the Squid web proxy in order to
+allow caching of files fetched through a TLS connection.
+
+Two volumes can be mounted: one at `/var/cache/squid` to hold the cached
+content and one at `/certs` for generated site certs and CA certificate and
+key. Specifically, if not provided, the CA key will be automatically created at
+`/certs/ca/key.pem` and the CA cert will be `/certs/ca/cert.pem`.
+For convenience it is possible to fetch the CA certificate from any proxy
+client by requesting `http://proxy/ca.crt`.
+
+The generated site certs will be stored under `/certs/ssl_db`. Normally there
+is no need to anything with those files: they are just kept around in order to
+avoid regenerating certs for sites that have been already visited after
+restarting the container.
+
+
+## Example usage
+
+To run the container:
+
+```bash
+docker run -it \
+    -p 3128:3128 \
+    -v package-cache:/var/cache/squid \
+    -v proxy-certs:/certs \
+    --rm git.worn.eu/containers/package-cache
+```
+
+To use the package cache from another container:
+
+```bash
+docker run -it \
+    --env http_proxy=http://$PROXY_IP:3128 \
+    --env https_proxy=http://$PROXY_IP:3128 \
+    --rm alpine sh
+```
+
+For SSL bumping to work we need to trust the proxy's CA, so from within the new
+container we run:
+
+```bash
+mkdir -p /usr/local/share/ca-certificates
+wget -qO- http://proxy/ca.crt | \
+    tee -a /etc/ssl/certs/ca-certificates.crt \
+    > /usr/local/share/ca-certificates/proxy.crt
+apk add ca-certificates
+update-ca-certificates
+```