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

  ./stop_player.sh
  

• Copy updated files to deployment location
• Verify configuration is in place
• Start application

  ./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:

  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:

   {
     "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

  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:

   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