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`](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:**

```yaml
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`

```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:**

```bash
cp .env.example .env
```

2. **Update .env with your secure credentials:**

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

3. **Deploy with templates:**

```bash
./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

```bash
# 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

````bash
### 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.
```