rxminder/SECURITY.md

🔐 Security Configuration Guide for RxMinder

This guide outlines the security configurations in RxMinder and how to properly secure your deployment.

📋 Related Documentation: For application-level security practices (password requirements, authentication, etc.), see docs/development/APPLICATION_SECURITY.md

⚠️ Critical Security Updates

We use a template-based approach with environment variables for secure, user-friendly credential management.

🔑 Template-Based Configuration

Kubernetes Deployment

Files: k8s/*.yaml.template

RxMinder uses Kubernetes template files that automatically substitute environment variables. No manual base64 encoding required!

Template files:

• k8s/couchdb-secret.yaml.template - Database credentials
• k8s/ingress.yaml.template - Ingress configuration
• k8s/configmap.yaml.template - Application configuration
• k8s/frontend-deployment.yaml.template - Frontend deployment

Example secret template:

apiVersion: v1
kind: Secret
metadata:
  name: couchdb-secret
  labels:
    app: ${APP_NAME:-rxminder}
type: Opaque
stringData:
  username: ${COUCHDB_USER:-admin}
  password: ${COUCHDB_PASSWORD:-change-this-secure-password}

Environment Variables

File: .env

# Application Name (used in Kubernetes labels)
APP_NAME=rxminder

# Database Credentials (automatically substituted in templates)
COUCHDB_USER=admin
COUCHDB_PASSWORD=your-very-secure-password
VITE_COUCHDB_USER=admin
VITE_COUCHDB_PASSWORD=your-very-secure-password

# Kubernetes Configuration
INGRESS_HOST=rxminder.yourdomain.com

🚀 Template-Based Deployment

Quick Start

1. Copy environment template:

cp .env.example .env

2. Update .env with your secure credentials:

# Edit .env with your secure passwords and configuration
nano .env

3. Deploy with templates:

./scripts/k8s-deploy-template.sh deploy

The deployment script automatically:

• ✅ Loads environment variables from .env
• ✅ Substitutes variables in template files
• ✅ Applies resources in correct dependency order
• ✅ Runs database seeding
• ✅ Shows deployment status

🛡️ Security Best Practices

1. Strong Passwords

• Use passwords with at least 16 characters
• Include uppercase, lowercase, numbers, and symbols
• Use a password manager to generate unique passwords

2. Environment-Specific Credentials

• Development: Use different credentials than production
• Staging: Use different credentials than production
• Production: Use strong, unique credentials

3. Credential Rotation

• Rotate database credentials regularly
• Update Kubernetes secrets using kubectl
• Update Docker environment variables

4. Secret Management

• Never commit actual credentials to version control
• Use Kubernetes secrets for production deployments
• Consider external secret management (HashiCorp Vault, etc.)

🔄 Updating Credentials

Kubernetes Environment

# Create new secret with secure credentials
kubectl create secret generic couchdb-secret \
  --from-literal=username=your-secure-username \
  --from-literal=password=your-very-secure-password \
  --dry-run=client -o yaml | kubectl apply -f -

# Restart pods to pick up new credentials
kubectl rollout restart statefulset/couchdb
kubectl rollout restart deployment/frontend

Docker Environment

### Docker Environment

```bash
# Update environment variables and restart containers
export COUCHDB_PASSWORD="your-very-secure-password"
export VITE_COUCHDB_PASSWORD="your-very-secure-password"
docker compose down && docker compose up -d

🔄 CI/CD Security

GitHub Actions / Gitea Workflows

Set these secrets in your repository settings:

• VITE_COUCHDB_PASSWORD: Your production CouchDB password
• GITEA_TOKEN / GITHUB_TOKEN: For container registry authentication

Important: CI/CD workflows use secure fallback values but should use repository secrets for production builds.

Test Environments

Test databases use secure passwords by default:

• CI containers: test-secure-password
• End-to-end tests: Use dedicated test credentials (acceptable for testing)

✅ Security Checklist

## ⚡ Quick Security Checklist

- [ ] Changed default admin password in `k8s/couchdb-secret.yaml`
- [ ] Updated `.env` file with secure credentials
- [ ] Used different passwords for each environment
- [ ] Credentials are not in version control (in `.gitignore`)
- [ ] Reviewed all scripts for hardcoded values
- [ ] Configured proper network policies (if using Kubernetes)
- [ ] Set up TLS/SSL for production deployments

## 🚨 Emergency Response

If credentials are compromised:

1. **Immediately** change passwords in all environments
2. Rotate Kubernetes secrets
3. Review access logs
4. Update any applications using the old credentials
5. Consider rotating container registry credentials if needed

## 📚 Additional Resources

- [CouchDB Security Best Practices](https://docs.couchdb.org/en/stable/intro/security.html)
- [Kubernetes Secrets Management](https://kubernetes.io/docs/concepts/configuration/secret/)
- [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/)

---

**Remember**: Security is an ongoing process, not a one-time setup. Regularly review and update your security configurations.