Skip to content

Commit cb5db7c

Browse files
GitTimeraiderGitTimeraider
authored
Healthcheck monitoring
1 parent 08cf2b0 commit cb5db7c

File tree

3 files changed

+222
-0
lines changed

3 files changed

+222
-0
lines changed

‎DATABASE_SETUP.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Database Setup and Health Monitoring Guide
2+
3+
This application supports multiple database backends with automatic driver detection, optimization, and comprehensive health monitoring.
4+
5+
## Supported Databases
6+
7+
### SQLite (Default)
8+
```bash
9+
# Default - no configuration needed
10+
DATABASE_URL=sqlite:///subscriptions.db
11+
```
12+
13+
### PostgreSQL (with psycopg3)
14+
```bash
15+
# Standard PostgreSQL URL - automatically converted to use psycopg3
16+
DATABASE_URL=postgresql://username:password@hostname:port/database_name
17+
DATABASE_URL=postgres://username:password@hostname:port/database_name
18+
19+
# Explicit psycopg3 driver (also supported)
20+
DATABASE_URL=postgresql+psycopg://username:password@hostname:port/database_name
21+
```
22+
23+
### MySQL/MariaDB
24+
```bash
25+
DATABASE_URL=mysql+pymysql://username:password@hostname:port/database_name
26+
DATABASE_URL=mariadb+pymysql://username:password@hostname:port/database_name
27+
```
28+
29+
## PostgreSQL with psycopg3 Features
30+
31+
The application automatically:
32+
- Converts `postgresql://` and `postgres://` URLs to use psycopg3 driver
33+
- Optimizes connection pooling for psycopg3
34+
- Sets appropriate timeouts and connection limits
35+
- Enables connection health checks (`pool_pre_ping`)
36+
37+
## Connection Pool Settings
38+
39+
### PostgreSQL (psycopg3)
40+
- **Pool Size**: 10 connections
41+
- **Max Overflow**: 20 additional connections
42+
- **Pool Timeout**: 30 seconds
43+
- **Connection Timeout**: 10 seconds
44+
- **Pool Recycle**: 1 hour (prevents stale connections)
45+
46+
### MySQL/MariaDB
47+
- **Pool Size**: 10 connections
48+
- **Max Overflow**: 20 additional connections
49+
- **Charset**: utf8mb4 (full Unicode support)
50+
51+
### SQLite
52+
- **Pool Timeout**: 10 seconds
53+
- **Connection Timeout**: 20 seconds
54+
- **Thread Safety**: Enabled (`check_same_thread=False`)
55+
56+
## Health Monitoring
57+
58+
### Docker Health Checks
59+
60+
The application includes comprehensive Docker health checks:
61+
62+
#### Built-in Health Endpoint
63+
- **URL**: `http://localhost:5000/health`
64+
- **Returns**: JSON with database connectivity and service status
65+
- **Timeout**: 10 seconds
66+
- **Retry**: 3 attempts
67+
68+
#### Docker Health Check Configuration
69+
```dockerfile
70+
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
71+
CMD curl -f http://localhost:5000/health || exit 1
72+
```
73+
74+
#### Docker Compose Health Checks
75+
```yaml
76+
services:
77+
web:
78+
healthcheck:
79+
test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
80+
interval: 30s
81+
timeout: 10s
82+
retries: 3
83+
start_period: 40s
84+
restart: unless-stopped
85+
86+
postgres: # If using PostgreSQL
87+
healthcheck:
88+
test: ["CMD-SHELL", "pg_isready -U user -d database"]
89+
interval: 10s
90+
timeout: 5s
91+
retries: 5
92+
start_period: 30s
93+
94+
mariadb: # If using MariaDB
95+
healthcheck:
96+
test: ["CMD", "/usr/local/bin/healthcheck.sh", "--connect", "--innodb_initialized"]
97+
interval: 10s
98+
timeout: 5s
99+
retries: 5
100+
start_period: 30s
101+
```
102+
103+
### Advanced Health Check Script
104+
105+
Use the included `health-check.sh` script for detailed monitoring:
106+
107+
```bash
108+
# Basic health check
109+
./health-check.sh
110+
111+
# Detailed health check with JSON output
112+
./health-check.sh --detailed --json
113+
114+
# Custom timeout and URL
115+
./health-check.sh --timeout=60 --url=http://your-domain.com
116+
117+
# Help
118+
./health-check.sh --help
119+
```
120+
121+
### Health Check Response Format
122+
123+
**Healthy Response** (200 OK):
124+
```json
125+
{
126+
"status": "healthy",
127+
"database": "ok",
128+
"currency_rates": "ok",
129+
"timestamp": "2025-10-06T10:30:00.000000"
130+
}
131+
```
132+
133+
**Unhealthy Response** (500 Internal Server Error):
134+
```json
135+
{
136+
"status": "unhealthy",
137+
"error": "Health check failed",
138+
"timestamp": "2025-10-06T10:30:00.000000"
139+
}
140+
```
141+
142+
### Monitoring Integration
143+
144+
The health checks work with:
145+
- **Docker Swarm**: Service health monitoring
146+
- **Kubernetes**: Liveness and readiness probes
147+
- **Load Balancers**: Health check endpoints
148+
- **Monitoring Tools**: Prometheus, Grafana, etc.
149+
150+
### Health Check Status Meanings
151+
152+
- **healthy**: All systems operational
153+
- **unhealthy**: Critical failure (database connectivity issues)
154+
- **degraded**: Some features may be limited (e.g., currency conversion)
155+
156+
## Troubleshooting
157+
158+
### "No module named 'psycopg2'" Error
159+
This application uses **psycopg3** (modern PostgreSQL driver), not psycopg2. The error occurs when:
160+
1. Using a plain `postgresql://` URL without driver specification
161+
2. Solution: The app automatically converts URLs to use psycopg3
162+
163+
### Connection Issues
164+
1. Verify database server is running and accessible
165+
2. Check firewall settings for database port
166+
3. Ensure database user has proper permissions
167+
4. Review Docker logs for detailed error messages
168+
5. Use health check endpoint to diagnose issues
169+
170+
### Health Check Failures
171+
```bash
172+
# Check container health status
173+
docker ps
174+
175+
# View health check logs
176+
docker inspect container_name | grep -A 10 Health
177+
178+
# Manual health check
179+
curl -f http://localhost:5000/health
180+
```
181+
182+
## Docker Environment Variables
183+
184+
```yaml
185+
# docker-compose.yml example
186+
environment:
187+
- DATABASE_URL=postgresql://myuser:mypass@db:5432/subscriptions
188+
- SECRET_KEY=your-secret-key-here
189+
```
190+
191+
## Database Migration
192+
193+
The application automatically:
194+
- Creates tables on first run
195+
- Applies schema migrations for new features
196+
- Creates default admin user (username: `admin`, password: `changeme`)
197+
198+
**Important**: Change the default admin password immediately after first login!

‎Dockerfile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ RUN apt-get update \
2929
gosu \
3030
default-mysql-client \
3131
libpq5 \
32+
curl \
3233
&& rm -rf /var/lib/apt/lists/*
3334

3435
# Copy installed packages from builder stage
@@ -44,6 +45,10 @@ ENV FLASK_APP=run.py \
4445
PUID=1000 \
4546
PGID=1000
4647

48+
# Health check configuration
49+
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
50+
CMD curl -f http://localhost:5000/health || exit 1
51+
4752
EXPOSE 5000
4853

4954
ENTRYPOINT ["/app/docker-entrypoint.sh"]

‎docker-compose.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,13 @@ services:
2323
- PERFORMANCE_LOGGING=${PERFORMANCE_LOGGING:-true}
2424
volumes:
2525
- ./data:/app/instance
26+
healthcheck:
27+
test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
28+
interval: 30s
29+
timeout: 10s
30+
retries: 3
31+
start_period: 40s
32+
restart: unless-stopped
2633

2734
postgres:
2835
image: postgres:15-alpine
@@ -34,6 +41,12 @@ services:
3441
- postgres_data:/var/lib/postgresql/data
3542
ports:
3643
- "${POSTGRES_PORT:-5432}:5432"
44+
healthcheck:
45+
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-subscription_tracker} -d ${POSTGRES_DB:-subscription_tracker}"]
46+
interval: 10s
47+
timeout: 5s
48+
retries: 5
49+
start_period: 30s
3750
profiles:
3851
- postgres
3952
restart: unless-stopped
@@ -49,6 +62,12 @@ services:
4962
- mariadb_data:/var/lib/mysql
5063
ports:
5164
- "${MYSQL_PORT:-3306}:3306"
65+
healthcheck:
66+
test: ["CMD", "/usr/local/bin/healthcheck.sh", "--connect", "--innodb_initialized"]
67+
interval: 10s
68+
timeout: 5s
69+
retries: 5
70+
start_period: 30s
5271
profiles:
5372
- mariadb
5473
restart: unless-stopped

0 commit comments

Comments
 (0)