Docker Rollback Plan¶

Created: February 2, 2026
Last Updated: February 26, 2026
Status: ⚠️ ARCHIVED - Historical reference only
Purpose: Document how to quickly revert from Docker back to Pipenv if issues arise

⚠️ Important Notice¶

This document is ARCHIVED and kept for historical reference only.

As of February 2026, production now uses Docker. This rollback plan was written during the initial Docker development phase when production still used pipenv. The instructions below are outdated but preserved for historical context.

Current production stack: - Server: uplink.sensational.systems - Deployment: Docker with 6 containers (web, daphne, huey, redis, nginx, certbot) - Branch: main (Uplink 2.0 - fully Dockerized)

For current deployment procedures, see: - Docker Deployment Guide - Local Development Guide

When to Rollback¶

Rollback if you encounter: - Docker containers won't build or start - Database connection issues that can't be resolved - Application errors that don't occur in pipenv - Performance problems - Any blocker that prevents development work

Important: Docker is currently development-only. Production still uses pipenv, so production is unaffected.

Quick Rollback (< 5 minutes)¶

Step 1: Stop Docker Containers¶

# Stop all running containers
docker-compose down

# Optional: Remove volumes if you want a complete cleanup
docker-compose down -v

Step 2: Return to Pipenv Environment¶

# Activate pipenv environment
source /home/hannah/.local/share/virtualenvs/uplink-zdKcNoqD/bin/activate

# Verify you're in the correct environment
which python
# Should show: /home/hannah/.local/share/virtualenvs/uplink-zdKcNoqD/bin/python

# Check Django works
python manage.py check

# Start development server
python manage.py runserver

Step 3: Verify Everything Works¶

# Check database connection
python manage.py dbshell --command="SELECT 1;"

# Run migrations (if needed)
python manage.py migrate

# Run a quick test
python manage.py test catalogue.tests.test_models

Done! You're back to the working pipenv setup.

What's Preserved (Safety Net)¶

The following files are NOT affected by Docker and remain intact:

✅ Pipfile - All pipenv dependencies
✅ Pipfile.lock - Exact package versions
✅ Database - Your local MySQL database is unchanged
✅ Media files - All uploaded files
✅ Source code - All Python code
✅ Git history - Full version control

Files Created by Docker (Can be Safely Deleted)¶

If you want to completely remove Docker:

# Remove Docker files
rm Dockerfile
rm docker-compose.yml
rm docker-compose.prod.yml
rm .dockerignore
rm docker-entrypoint.sh
rm .env.example

# Remove Docker volumes (if any)
docker volume prune

# Remove Docker images
docker rmi $(docker images -q uplink*)

Note: Only do this if you're certain you won't need Docker again.

Partial Rollback (Keep Docker Files)¶

If you want to keep Docker files for future attempts but use pipenv now:

# Just stop containers
docker-compose down

# Use pipenv as normal
source /home/hannah/.local/share/virtualenvs/uplink-zdKcNoqD/bin/activate
python manage.py runserver

Docker files remain in the repository but don't affect your pipenv workflow.

Troubleshooting Common Issues Before Rollback¶

Try these before giving up on Docker:

Issue: Database Connection Refused¶

# Check if MySQL container is running
docker-compose ps

# Check database logs
docker-compose logs db

# Restart just the database
docker-compose restart db

# Wait for health check
docker-compose ps

Issue: Port Already in Use¶

# Find what's using port 8000
sudo lsof -i :8000

# Kill the process or change docker-compose.yml port
# Change "8000:8000" to "8001:8000"

Issue: Permission Denied¶

# Fix docker-entrypoint.sh permissions
chmod +x docker-entrypoint.sh

# Rebuild image
docker-compose build

Issue: Migrations Failing¶

# Run migrations manually
docker-compose exec web python manage.py migrate

# Check migration status
docker-compose exec web python manage.py showmigrations

Issue: Can't Connect to Container¶

# Restart all services
docker-compose restart

# View logs
docker-compose logs -f web

# Get shell access to debug
docker-compose exec web bash

What to Document if Rollback Needed¶

If you do rollback, please document in docs/Uplink2.0_UpgradeLogs.md:

What went wrong - Specific error messages
What you tried - Troubleshooting steps attempted
Why you rolled back - The blocker that forced rollback
Timestamp - When the rollback occurred

This helps us understand what to fix before trying Docker again.

Re-attempting Docker Later¶

If you rollback now but want to try Docker again later:

Keep the Docker files - Don't delete them
Document the issues - So we can fix them
Try again when ready - Docker files will still be there
Same process - docker-compose up -d

Production Deployment Safety¶

Important: Production is completely unaffected by local Docker experimentation.

Production still uses pipenv
Production deployment process unchanged
No risk to live site
Docker is opt-in for development only

When ready to deploy Docker to production (future): 1. Test thoroughly in development first 2. Follow deployment procedures in docs/Uplink2.0_PLAN.md Appendix D 3. Have database backups 4. Know how to rollback production (documented in plan)

Emergency Contacts¶

If you're stuck and need help: - Check docs/Uplink2.0_PLAN.md for detailed procedures - Review Docker logs: docker-compose logs - Git history: git log to see what changed - This file: How to rollback quickly

Remember: Pipenv is your safety net. It's always there to fall back on.