Skip to content

Commit 181823b

Browse files
neverinfamousneverinfamous
committed
Add Docker-optimized README with Docker-specific instructions and examples
1 parent c600138 commit 181823b

File tree

2 files changed

+269
-2
lines changed

2 files changed

+269
-2
lines changed

‎.github/workflows/docker-build-dockerhub.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -131,5 +131,5 @@ jobs:
131131
username: ${{ secrets.DOCKERHUB_USERNAME }}
132132
password: ${{ secrets.DOCKERHUB_TOKEN }}
133133
repository: writenotenow/postgres-mcp-enhanced
134-
readme-filepath: ./README.md
135-
short-description: "Enterprise PostgreSQL MCP Server - Enhanced fork with comprehensive security and AI-native operations"
134+
readme-filepath: ./DOCKER_README.md
135+
short-description: "Enterprise PostgreSQL MCP Server - 63 specialized tools with comprehensive security and AI-native operations"

‎DOCKER_README.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# PostgreSQL MCP Server - Enhanced
2+
3+
*Version 1.0.4 - Enterprise-grade PostgreSQL MCP server with comprehensive security and AI-native operations*
4+
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6+
[![Security](https://img.shields.io/badge/Security-Enhanced-green.svg)](https://github.com/neverinfamous/postgres-mcp/blob/main/SECURITY.md)
7+
[![Docker Pulls](https://img.shields.io/docker/pulls/writenotenow/postgres-mcp-enhanced)](https://hub.docker.com/r/writenotenow/postgres-mcp-enhanced)
8+
9+
---
10+
11+
## 🚀 Quick Start
12+
13+
Pull and run the latest version:
14+
15+
```bash
16+
docker pull writenotenow/postgres-mcp-enhanced:latest
17+
18+
docker run -i --rm \
19+
-e DATABASE_URI="postgresql://user:pass@host:5432/dbname" \
20+
writenotenow/postgres-mcp-enhanced:latest \
21+
--access-mode=restricted
22+
```
23+
24+
**That's it!** The server is now running and ready to connect via MCP.
25+
26+
---
27+
28+
## 📋 Prerequisites
29+
30+
1. **PostgreSQL Database** (version 13-17) - Running and accessible
31+
2. **Database Connection String** - In the format: `postgresql://user:pass@host:5432/dbname`
32+
3. **MCP Client** - Claude Desktop, Cursor, or any MCP-compatible client
33+
34+
---
35+
36+
## 🐳 Docker Tags
37+
38+
We provide multiple tags for different use cases:
39+
40+
| Tag | Description | Use Case |
41+
|-----|-------------|----------|
42+
| `latest` | Latest stable release | **Recommended for production** |
43+
| `v1.0.4` | Specific version | Pin to exact version |
44+
| `sha-abc1234` | Commit SHA | Development/testing |
45+
| `master-YYYYMMDD-HHMMSS-sha` | Timestamped | Audit trail |
46+
47+
**Pull a specific version:**
48+
```bash
49+
docker pull writenotenow/postgres-mcp-enhanced:v1.0.4
50+
```
51+
52+
---
53+
54+
## 🔧 Configuration
55+
56+
### Environment Variables
57+
58+
| Variable | Required | Description |
59+
|----------|----------|-------------|
60+
| `DATABASE_URI` | Yes | PostgreSQL connection string |
61+
| `--access-mode` | Recommended | `restricted` (read-only) or `unrestricted` (full access) |
62+
63+
### Example Configurations
64+
65+
**Production (Restricted Mode):**
66+
```bash
67+
docker run -i --rm \
68+
-e DATABASE_URI="postgresql://readonly_user:pass@db.example.com:5432/production" \
69+
writenotenow/postgres-mcp-enhanced:latest \
70+
--access-mode=restricted
71+
```
72+
73+
**Development (Unrestricted Mode):**
74+
```bash
75+
docker run -i --rm \
76+
-e DATABASE_URI="postgresql://admin:pass@localhost:5432/dev_db" \
77+
writenotenow/postgres-mcp-enhanced:latest \
78+
--access-mode=unrestricted
79+
```
80+
81+
**With Docker Compose:**
82+
```yaml
83+
version: '3.8'
84+
services:
85+
postgres-mcp:
86+
image: writenotenow/postgres-mcp-enhanced:latest
87+
environment:
88+
DATABASE_URI: postgresql://user:pass@postgres:5432/mydb
89+
command: --access-mode=restricted
90+
stdin_open: true
91+
tty: true
92+
```
93+
94+
---
95+
96+
## 🛡️ Security Features
97+
98+
This image is built with security as a priority:
99+
100+
- ✅ **Non-root user** - Runs as user `app` (UID 1000)
101+
- ✅ **Zero critical vulnerabilities** - All dependencies patched
102+
- ✅ **Supply chain attestation** - Full SBOM and provenance included
103+
- ✅ **Docker Scout verified** - Continuous security scanning
104+
- ✅ **SQL injection prevention** - All queries use parameter binding
105+
- ✅ **Minimal attack surface** - Alpine-based with only required dependencies
106+
107+
**View Security Details:**
108+
```bash
109+
docker scout cves writenotenow/postgres-mcp-enhanced:latest
110+
```
111+
112+
---
113+
114+
## 🏢 What's Included
115+
116+
**63 specialized MCP tools** for comprehensive PostgreSQL operations:
117+
118+
- **Core Database (9)** - Schema management, SQL execution, health monitoring
119+
- **JSON Operations (11)** - JSONB operations, validation, security scanning
120+
- **Text Processing (5)** - Full-text search, similarity matching
121+
- **Statistical Analysis (8)** - Descriptive stats, correlation, regression
122+
- **Performance Intelligence (6)** - Query optimization, index tuning
123+
- **Vector/Semantic Search (8)** - pgvector integration, embeddings
124+
- **Geospatial (7)** - PostGIS integration, spatial queries
125+
- **Backup & Recovery (4)** - Backup planning, restore validation
126+
- **Monitoring & Alerting (5)** - Real-time monitoring, capacity planning
127+
128+
---
129+
130+
## 🔌 MCP Client Configuration
131+
132+
### Claude Desktop
133+
```json
134+
{
135+
"mcpServers": {
136+
"postgres-mcp": {
137+
"command": "docker",
138+
"args": [
139+
"run", "-i", "--rm", "-e", "DATABASE_URI",
140+
"writenotenow/postgres-mcp-enhanced:latest",
141+
"--access-mode=restricted"
142+
],
143+
"env": {
144+
"DATABASE_URI": "postgresql://user:pass@localhost:5432/dbname"
145+
}
146+
}
147+
}
148+
}
149+
```
150+
151+
### Cursor IDE
152+
```json
153+
{
154+
"mcpServers": {
155+
"postgres-mcp": {
156+
"command": "docker",
157+
"args": [
158+
"run", "-i", "--rm", "-e", "DATABASE_URI",
159+
"writenotenow/postgres-mcp-enhanced:latest",
160+
"--access-mode=restricted"
161+
],
162+
"env": {
163+
"DATABASE_URI": "postgresql://user:pass@localhost:5432/dbname"
164+
}
165+
}
166+
}
167+
}
168+
```
169+
170+
---
171+
172+
## 📊 PostgreSQL Extensions
173+
174+
The server works with standard PostgreSQL installations. For enhanced functionality, install these extensions:
175+
176+
**Required for all features:**
177+
```sql
178+
CREATE EXTENSION IF NOT EXISTS pg_stat_statements; -- Query performance tracking
179+
CREATE EXTENSION IF NOT EXISTS pg_trgm; -- Text similarity
180+
CREATE EXTENSION IF NOT EXISTS fuzzystrmatch; -- Fuzzy matching
181+
```
182+
183+
**Optional but recommended:**
184+
```sql
185+
CREATE EXTENSION IF NOT EXISTS hypopg; -- Hypothetical index testing
186+
CREATE EXTENSION IF NOT EXISTS pgvector; -- Vector similarity search
187+
CREATE EXTENSION IF NOT EXISTS postgis; -- Geospatial operations
188+
```
189+
190+
The server gracefully handles missing extensions - features requiring them will provide helpful error messages.
191+
192+
---
193+
194+
## 🧪 Testing the Image
195+
196+
Verify the image works correctly:
197+
198+
```bash
199+
# Check server version
200+
docker run --rm writenotenow/postgres-mcp-enhanced:latest --version
201+
202+
# Test database connection (replace with your connection string)
203+
docker run -i --rm \
204+
-e DATABASE_URI="postgresql://user:pass@localhost:5432/dbname" \
205+
writenotenow/postgres-mcp-enhanced:latest \
206+
--access-mode=restricted
207+
```
208+
209+
---
210+
211+
## 📏 Image Details
212+
213+
- **Base Image**: Python 3.13-slim-bookworm
214+
- **Architecture**: AMD64, ARM64 (multi-arch)
215+
- **Size**: ~80MB compressed, ~240MB uncompressed
216+
- **User**: Non-root (`app:1000`)
217+
- **Entrypoint**: `/app/docker-entrypoint.sh`
218+
- **Working Directory**: `/app`
219+
220+
---
221+
222+
## 🔗 Links & Resources
223+
224+
- **[📚 Complete Documentation](https://github.com/neverinfamous/postgres-mcp/wiki)** - Comprehensive wiki
225+
- **[🚀 Quick Start Guide](https://github.com/neverinfamous/postgres-mcp/wiki/Quick-Start)** - Get started in 30 seconds
226+
- **[🛡️ Security Policy](https://github.com/neverinfamous/postgres-mcp/blob/main/SECURITY.md)** - Vulnerability reporting
227+
- **[💻 GitHub Repository](https://github.com/neverinfamous/postgres-mcp)** - Source code
228+
- **[📦 PyPI Package](https://pypi.org/project/postgres-mcp-enhanced/)** - Python installation option
229+
230+
---
231+
232+
## 🆕 Recent Updates
233+
234+
### v1.0.4 (October 3, 2025)
235+
- ✅ Improved Docker tagging strategy
236+
- ✅ Removed buildcache tag clutter
237+
- ✅ Automatic README sync to Docker Hub
238+
239+
### v1.0.3 (October 3, 2025)
240+
- ✅ Fixed all critical/high CVEs (h11, mcp, setuptools, bind9)
241+
- ✅ Updated dependencies to latest secure versions
242+
- ✅ Zero known vulnerabilities
243+
244+
### v1.0.2 (October 3, 2025)
245+
- ✅ Added non-root user (security hardening)
246+
- ✅ Supply chain attestation (SBOM + Provenance)
247+
- ✅ Docker Scout scanning integration
248+
249+
---
250+
251+
## 🙋 Support & Contributing
252+
253+
- **Issues**: [GitHub Issues](https://github.com/neverinfamous/postgres-mcp/issues)
254+
- **Discussions**: [GitHub Discussions](https://github.com/neverinfamous/postgres-mcp/discussions)
255+
- **Security**: Report vulnerabilities to admin@adamic.tech
256+
- **Contributing**: See [Contributing Guide](https://github.com/neverinfamous/postgres-mcp/blob/main/CONTRIBUTING.md)
257+
258+
---
259+
260+
## 📄 License
261+
262+
MIT License - See [LICENSE](https://github.com/neverinfamous/postgres-mcp/blob/main/LICENSE)
263+
264+
---
265+
266+
**Built with ❤️ by Chris LeRoux** | *Enterprise-grade PostgreSQL operations through MCP*
267+

0 commit comments

Comments
 (0)