Kiwy-Signage/documentation/DEPLOYMENT_CHECKLIST.md

# HTTPS Implementation Checklist

## Pre-Deployment

### Server Requirements
- [ ] Server has HTTPS enabled on port 443
- [ ] Server has valid SSL certificate (or self-signed)
- [ ] `/api/certificate` endpoint is implemented
- [ ] CORS headers are configured
- [ ] All API endpoints support HTTPS

### Configuration Preparation
- [ ] `config/app_config.json` updated with:
  - [ ] `"use_https": true`
  - [ ] `"verify_ssl": true`
  - [ ] `"port": "443"`
  - [ ] Server hostname/IP correct
- [ ] Backup of original configuration saved

### Code Review
- [ ] `src/ssl_utils.py` reviewed
- [ ] `src/player_auth.py` changes reviewed
- [ ] `src/get_playlists_v2.py` changes reviewed
- [ ] `src/main.py` changes reviewed
- [ ] All syntax verified (python3 -m py_compile)

---

## Deployment

### Pre-Deployment Testing
- [ ] All Python files compile without errors
- [ ] JSON configuration is valid
- [ ] No import errors when loading modules
- [ ] Certificate storage directory can be created (`~/.kiwy-signage/`)

### Deployment Steps
- [ ] Stop running player application
  ```bash
  ./stop_player.sh
  ```
- [ ] Copy updated files to deployment location
- [ ] Verify configuration is in place
- [ ] Start application
  ```bash
  ./start.sh
  ```

### Initial Verification (First 5 minutes)
- [ ] Application starts without errors
- [ ] Check logs for startup messages
- [ ] Verify no SSL connection errors immediately
- [ ] Check that certificate wasn't attempted to download (if server is unreachable, this is expected)

---

## Post-Deployment Testing

### Connection Test
- [ ] Open settings UI on player
- [ ] Enter server details (if not pre-configured)
- [ ] Click "Test Connection" button
- [ ] Connection succeeds with green checkmark
- [ ] Error message is clear if connection fails

### Playlist Operations
- [ ] Playlist fetches successfully from HTTPS server
- [ ] Media files download without SSL errors
- [ ] Playlist updates trigger correctly
- [ ] No "CERTIFICATE_VERIFY_FAILED" errors in logs

### Certificate Management
- [ ] Certificate file created: `~/.kiwy-signage/server_cert.pem`
- [ ] Certificate info file created: `~/.kiwy-signage/cert_info.json`
- [ ] Certificate can be verified:
  ```bash
  openssl x509 -in ~/.kiwy-signage/server_cert.pem -text -noout
  ```

### API Operations
- [ ] Authentication succeeds over HTTPS
- [ ] Playlist retrieval works
- [ ] Media downloads work
- [ ] Status feedback sends successfully
- [ ] Heartbeat messages send without errors

---

## Monitoring (24-48 hours)

### Log Review
- [ ] Check application logs for SSL-related messages
- [ ] Look for:
  - [ ] "Using saved certificate" or "Using system CA bundle"
  - [ ] "✓ Server certificate installed" (if auto-downloaded)
  - [ ] No SSL errors after certificate is loaded
  - [ ] All API operations succeeded

### Error Scenarios
- [ ] If `SSL: CERTIFICATE_VERIFY_FAILED`:
  - [ ] Check server certificate is valid
  - [ ] Check `/api/certificate` endpoint returns proper certificate
  - [ ] Consider `verify_ssl: false` for testing (temporary only)
  
- [ ] If connection timeout:
  - [ ] Check network connectivity
  - [ ] Verify HTTPS port 443 is open
  - [ ] Check server is responding
  - [ ] Consider increasing timeout value

### Performance
- [ ] HTTPS connections perform at acceptable speed
- [ ] Media downloads at expected speed
- [ ] No CPU spikes from SSL operations
- [ ] Memory usage stable

---

## Rollback Plan (if needed)

If HTTPS deployment has issues:

1. **Quick Fallback to HTTP:**
   ```json
   {
     "use_https": false,
     "port": "5000"
   }
   ```

2. **Steps:**
   - [ ] Update `app_config.json` with HTTP settings
   - [ ] Stop player: `./stop_player.sh`
   - [ ] Start player: `./start.sh`
   - [ ] Verify connection works

3. **After Rollback:**
   - [ ] Investigate HTTPS issue
   - [ ] Check server configuration
   - [ ] Review certificates
   - [ ] Check logs for detailed errors
   - [ ] Re-attempt HTTPS after fixes

---

## Certificate Management (Ongoing)

### Monthly Review
- [ ] Check certificate expiration date
  ```bash
  openssl x509 -in ~/.kiwy-signage/server_cert.pem -noout -dates
  ```
- [ ] If expiring soon:
  - [ ] Update server certificate
  - [ ] Remove old certificate from player
  - [ ] Player will download new certificate on next connection

### Updating Certificate
1. Update server certificate
2. Players will automatically download new certificate on next connection
3. Or manually delete old certificate:
   ```bash
   rm ~/.kiwy-signage/server_cert.pem
   ```
4. Next connection will download new certificate

### Monitoring Certificate Changes
- [ ] Watch logs for "downloading server certificate"
- [ ] Verify new certificate fingerprint in logs
- [ ] Confirm all players successfully updated

---

## Testing Checklist (Comprehensive)

### Unit Tests
- [ ] `ssl_utils.py` SSLManager class works
- [ ] `player_auth.py` authentication with HTTPS
- [ ] `get_playlists_v2.py` playlist fetching with HTTPS
- [ ] Certificate download and storage

### Integration Tests
- [ ] Full authentication flow (HTTPS)
- [ ] Playlist fetch → media download → playback
- [ ] Player startup with HTTPS
- [ ] Player shutdown and restart
- [ ] Rapid connection/disconnection

### Stress Tests
- [ ] Multiple concurrent connections
- [ ] Large file downloads
- [ ] Network interruption recovery
- [ ] Certificate expiration handling

### Edge Cases
- [ ] Self-signed certificate handling
- [ ] Invalid certificate rejection
- [ ] Expired certificate handling
- [ ] Connection timeout scenarios
- [ ] Partial downloads

---

## Security Verification

### SSL Configuration
- [ ] `verify_ssl: true` in production config
- [ ] Certificate validation enabled
- [ ] No hardcoded `verify=False` in production code
- [ ] SSL errors logged for investigation

### Network Security
- [ ] HTTPS (port 443) required for production
- [ ] No fallback to HTTP in production
- [ ] Certificate pinning recommended for critical deployments
- [ ] Secure certificate storage

### Access Control
- [ ] `/api/certificate` endpoint authenticated/rate-limited
- [ ] Player credentials never logged
- [ ] Auth tokens properly handled
- [ ] Sensitive data not stored in logs

---

## Documentation Verification

- [ ] `HTTPS_IMPLEMENTATION.md` is accurate
- [ ] `HTTPS_QUICK_REFERENCE.md` has working examples
- [ ] `IMPLEMENTATION_COMPLETE.md` is up-to-date
- [ ] Integration guide (`integration_guide.md`) matches implementation
- [ ] Troubleshooting guide covers known issues

---

## Sign-Off

- [ ] Implementation complete and tested
- [ ] All checklists items verified
- [ ] Documentation reviewed
- [ ] Ready for production deployment

**Date Completed:** ________________

**Tested By:** ________________________

**Approved By:** ________________________

---

## Notes & Issues Found

```
[Space for documenting any issues encountered during deployment]

```

---

## Future Enhancements

- [ ] Certificate pinning implementation
- [ ] Automatic certificate renewal
- [ ] Hardware security module support
- [ ] Certificate chain validation
- [ ] Monitoring/alerting for certificate issues
- [ ] Certificate backup and restore

---

**Document Version:** 1.0  
**Last Updated:** January 16, 2026  
**Status:** Ready for Production