docs: add Docker deployment guide

.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

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"]

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: