docs: add security policy and deployment guide
- Add SECURITY.md with vulnerability reporting process - Add comprehensive deployment guide (docs/deployment/index.md) - Generate uv.lock for reproducible builds - Update audit rules to check correct deployment path - Remove Node.js dependency, use Tailwind CLI standalone Resolves audit warnings: - THIRD-DEP-001: Dependency lock file - DOC-SEC-001: Security policy - DOC-OPS-001: Deployment documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,277 @@
|
||||
# Deployment Guide
|
||||
|
||||
This guide covers deploying the Wizamart platform to production environments.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- PostgreSQL 14+ (production) or SQLite (development)
|
||||
- Redis (optional, for caching/sessions)
|
||||
- Tailwind CSS CLI (standalone binary)
|
||||
- uv package manager
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
```bash
|
||||
# Application
|
||||
APP_ENV=production
|
||||
SECRET_KEY=<generate-secure-key>
|
||||
DEBUG=false
|
||||
|
||||
# Database
|
||||
DATABASE_URL=postgresql://user:password@host:5432/wizamart
|
||||
|
||||
# Security
|
||||
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
|
||||
CORS_ORIGINS=https://yourdomain.com
|
||||
|
||||
# Email
|
||||
SMTP_HOST=smtp.provider.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USER=your-email
|
||||
SMTP_PASSWORD=your-password
|
||||
EMAIL_FROM=noreply@yourdomain.com
|
||||
|
||||
# Letzshop Integration
|
||||
LETZSHOP_API_ENDPOINT=https://letzshop.lu/graphql
|
||||
ENCRYPTION_KEY=<generate-fernet-key>
|
||||
|
||||
# Optional: Redis
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
```
|
||||
|
||||
### Generating Secrets
|
||||
|
||||
```bash
|
||||
# Generate SECRET_KEY
|
||||
python -c "import secrets; print(secrets.token_urlsafe(64))"
|
||||
|
||||
# Generate ENCRYPTION_KEY (Fernet)
|
||||
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||||
```
|
||||
|
||||
## Deployment Steps
|
||||
|
||||
### 1. Clone and Setup
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd wizamart
|
||||
|
||||
# Install dependencies
|
||||
uv sync --frozen
|
||||
|
||||
# Activate virtual environment
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
### 2. Database Setup
|
||||
|
||||
```bash
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Initialize production data
|
||||
python scripts/init_production.py
|
||||
```
|
||||
|
||||
### 3. Static Assets
|
||||
|
||||
```bash
|
||||
# Build Tailwind CSS using standalone CLI
|
||||
# Download from: https://github.com/tailwindlabs/tailwindcss/releases
|
||||
|
||||
tailwindcss -i ./static/shared/css/input.css -o ./static/shared/css/tailwind.output.css --minify
|
||||
|
||||
# Same for admin and vendor CSS
|
||||
tailwindcss -i ./static/admin/css/tailwind.css -o ./static/admin/css/tailwind.output.css --minify
|
||||
tailwindcss -i ./static/vendor/css/tailwind.css -o ./static/vendor/css/tailwind.output.css --minify
|
||||
```
|
||||
|
||||
### 4. Run Application
|
||||
|
||||
#### Using Uvicorn (recommended)
|
||||
|
||||
```bash
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
|
||||
```
|
||||
|
||||
#### Using Gunicorn with Uvicorn workers
|
||||
|
||||
```bash
|
||||
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
|
||||
```
|
||||
|
||||
## Reverse Proxy Configuration
|
||||
|
||||
### Nginx Example
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name yourdomain.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name yourdomain.com;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
location /static {
|
||||
alias /path/to/app/static;
|
||||
expires 30d;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Dockerfile
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.11-slim
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Install uv and download Tailwind CLI
|
||||
RUN pip install uv && \
|
||||
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64 && \
|
||||
chmod +x tailwindcss-linux-x64 && \
|
||||
mv tailwindcss-linux-x64 /usr/local/bin/tailwindcss
|
||||
|
||||
# Copy dependency files
|
||||
COPY pyproject.toml uv.lock ./
|
||||
|
||||
# Install dependencies
|
||||
RUN uv sync --frozen --no-dev
|
||||
|
||||
# Copy application
|
||||
COPY . .
|
||||
|
||||
# Build static assets
|
||||
RUN tailwindcss -i ./static/shared/css/input.css -o ./static/shared/css/tailwind.output.css --minify
|
||||
|
||||
EXPOSE 8000
|
||||
|
||||
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
web:
|
||||
build: .
|
||||
ports:
|
||||
- "8000:8000"
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://postgres:password@db:5432/wizamart
|
||||
depends_on:
|
||||
- db
|
||||
|
||||
db:
|
||||
image: postgres:14
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
environment:
|
||||
- POSTGRES_DB=wizamart
|
||||
- POSTGRES_PASSWORD=password
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
The application provides health check endpoints:
|
||||
|
||||
- `GET /health` - Basic health check
|
||||
- `GET /health/ready` - Readiness check (includes DB)
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Logging
|
||||
|
||||
Logs are output to stdout in JSON format for production:
|
||||
|
||||
```bash
|
||||
# View logs
|
||||
docker logs -f wizamart-web
|
||||
|
||||
# Or with systemd
|
||||
journalctl -u wizamart -f
|
||||
```
|
||||
|
||||
### Metrics
|
||||
|
||||
Consider integrating:
|
||||
- Prometheus for metrics collection
|
||||
- Grafana for visualization
|
||||
- Sentry for error tracking
|
||||
|
||||
## Backup Strategy
|
||||
|
||||
### Database Backups
|
||||
|
||||
```bash
|
||||
# PostgreSQL backup
|
||||
pg_dump -U postgres wizamart > backup_$(date +%Y%m%d).sql
|
||||
|
||||
# Automated daily backups (cron)
|
||||
0 2 * * * pg_dump -U postgres wizamart | gzip > /backups/wizamart_$(date +\%Y\%m\%d).sql.gz
|
||||
```
|
||||
|
||||
## Rollback Procedure
|
||||
|
||||
```bash
|
||||
# Rollback database migration
|
||||
alembic downgrade -1
|
||||
|
||||
# Rollback to specific revision
|
||||
alembic downgrade <revision_id>
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Database connection errors**
|
||||
- Verify DATABASE_URL format
|
||||
- Check PostgreSQL is running
|
||||
- Verify network connectivity
|
||||
|
||||
2. **Static files not loading**
|
||||
- Rebuild Tailwind CSS
|
||||
- Check Nginx static file configuration
|
||||
- Verify file permissions
|
||||
|
||||
3. **Email not sending**
|
||||
- Verify SMTP credentials
|
||||
- Check firewall allows outbound SMTP
|
||||
- Test with `python scripts/test_email.py`
|
||||
|
||||
### Debug Mode
|
||||
|
||||
For troubleshooting, temporarily enable debug mode:
|
||||
|
||||
```bash
|
||||
DEBUG=true uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
**Warning**: Never use debug mode in production with real traffic.
|
||||
|
||||
Reference in New Issue
Block a user