From ec13d4a8159d21ca4d3ae9ad5385177141980cfd Mon Sep 17 00:00:00 2001
From: felixvippp-ai <felixvippp-ai@users.noreply.github.com>
Date: Tue, 23 Jun 2026 23:58:12 -0400
Subject: [PATCH] docs: add container deployment guide

---
 .dockerignore | 14 ++++++++++++++
 Dockerfile    | 26 ++++++++++++++++++++++++++
 README.md     | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+)
 create mode 100644 .dockerignore
 create mode 100644 Dockerfile

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..832b1be
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,14 @@
+.git
+.github
+node_modules
+dist
+coverage
+npm-debug.log*
+*.log
+.env
+.env.*
+!.env.example
+.DS_Store
+*.patch
+*.tgz
+src/**/*.test.ts
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..5535cbd
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,26 @@
+# syntax=docker/dockerfile:1
+
+FROM node:20-bookworm-slim AS deps
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+FROM deps AS build
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+RUN npm prune --omit=dev
+
+FROM node:20-bookworm-slim AS runtime
+ENV NODE_ENV=production
+ENV PORT=3001
+WORKDIR /app
+
+COPY --from=build --chown=node:node /app/package*.json ./
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/dist ./dist
+
+USER node
+EXPOSE 3001
+
+CMD ["node", "dist/index.js"]
diff --git a/README.md b/README.md
index fa721c7..961e534 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,38 @@ agentpay-backend/
 | `npm run dev`    | Run with ts-node                            |
 | `npm start`      | Run production build                        |
 
+## Running with Docker
+
+Build the production image from the repository root:
+
+```bash
+docker build -t agentpay-backend .
+```
+
+Run the container on the default port:
+
+```bash
+docker run --rm --name agentpay-backend -p 3001:3001 -e PORT=3001 agentpay-backend
+```
+
+Check the running service:
+
+```bash
+curl http://localhost:3001/health
+```
+
+Stop the container:
+
+```bash
+docker stop agentpay-backend
+```
+
+The image uses a multi-stage build, prunes development dependencies before the
+runtime stage, runs as the non-root `node` user, and starts with exec-form
+`CMD` so Docker forwards `SIGTERM` to the existing graceful shutdown handler.
+Do not bake secrets into the image; pass runtime configuration through
+environment variables.
+
 ## CI/CD
 
 On push/PR to `main`, GitHub Actions runs: