diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..7e32de1
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,20 @@
+.git
+.github
+*.md
+*.png
+*.jpg
+*.jpeg
+*.gif
+
+# Local Config
+config/
+
+# Local outputs
+data/
+dist/
+bin/
+
+# Editor/OS
+.DS_Store
+.idea/
+.vscode/
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..df4f0a5
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,31 @@
+FROM golang:1.22-alpine AS builder
+
+RUN apk add --no-cache ca-certificates git
+WORKDIR /src
+
+# Better layer caching
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+# Build a static-ish binary
+ENV CGO_ENABLED=0
+RUN go build -trimpath -ldflags="-s -w" -o /out/matcha .
+
+FROM alpine:3.20
+
+# HTTPS calls (RSS feeds, OpenAI/LocalAI, etc.) need CA certs
+RUN apk add --no-cache ca-certificates tzdata \
+  && addgroup -S matcha && adduser -S matcha -G matcha
+
+WORKDIR /app
+COPY --from=builder /out/matcha /usr/local/bin/matcha
+
+# Conventional mount points
+RUN mkdir -p /config /data && chown -R matcha:matcha /config /data
+USER matcha
+
+# Default: run once using a mounted config
+ENTRYPOINT ["matcha"]
+CMD ["-c", "/config/config.yaml"]
diff --git a/README.md b/README.md
index b546425..3d3d4f6 100644
--- a/README.md
+++ b/README.md
@@ -163,3 +163,62 @@ Run matcha with --help option to see current cli options:
 
 #### OPML Import
 To use OPML files (exported from other services), rename your file to `config.opml` and leave it in the directory where matcha is located. The other option is to run the command with -o option pointing to the opml filepath.
+
+
+### Docker
+
+Build
+
+```sh
+docker build -t matcha:local .
+```
+
+Prepare the folder for the config that holds your `config.yaml` file and data folder for the markdown output and persistence.
+
+Ensure your `config.yaml` sets `markdown_dir_path: /data/markdown` (and optionally `database_file_path: /data/matcha.db`).
+
+```sh
+mkdir -p config data/markdown
+```
+
+Run
+
+```sh
+docker run --rm \
+  -v "$PWD/config:/config:ro" \
+  -v "$PWD/data:/data" \
+  matcha:local \
+  -c /config/config.yaml
+```
+
+Run in terminal mode (-t)
+
+```sh
+docker run --rm \
+  -v "$PWD/config:/config:ro" \
+  -v "$PWD/data:/data" \
+  matcha:local \
+  -c /config/config.yaml -t
+```
+
+For more frequent runs and updates run the docker-compose file:
+
+Run once
+
+```sh
+docker compose run --rm matcha-once
+```
+
+Run once with -t
+
+```sh
+docker compose run --rm matcha-once -c /config/config.yaml -t
+```
+
+Run scheduled
+
+```sh
+docker compose up -d matcha-scheduled
+docker compose logs -f matcha-scheduled
+```
+
diff --git a/docker-compose.yaml b/docker-compose.yaml
new file mode 100644
index 0000000..78d751e
--- /dev/null
+++ b/docker-compose.yaml
@@ -0,0 +1,21 @@
+services:
+  matcha-once:
+    build: .
+    container_name: matcha-once
+    volumes:
+      - ./config:/config:ro
+      - ./data:/data
+    command: ["-c", "/config/config.yaml"]
+
+  matcha-scheduled:
+    build: .
+    container_name: matcha-scheduled
+    volumes:
+      - ./config:/config:ro
+      - ./data:/data
+    environment:
+      MATCHA_INTERVAL_SECONDS: "3600"
+    entrypoint: ["/bin/sh", "-lc"]
+    command:
+      - 'while true; do matcha -c /config/config.yaml || true; sleep "$${MATCHA_INTERVAL_SECONDS}"; done'
+    restart: unless-stopped