digiserver-v2/old_code_documentation/OPTION1_IMPLEMENTATION.md

Option 1 Implementation - Dockerfile-based Deployment

Implementation Date: January 17, 2026
Status: ✅ COMPLETE

What Changed

1. docker-compose.yml

Removed:

volumes:
  - ./data:/app  # ❌ REMOVED - no longer override code in image

Kept:

volumes:
  - ./data/instance:/app/instance      # Database persistence
  - ./data/uploads:/app/app/static/uploads  # User uploads

2. Dockerfile

Updated comments for clarity:

# Copy entire application code into container
# This includes: app/, migrations/, configs, and all scripts
# Code is immutable in the image - only data folders are mounted as volumes
COPY . .

3. init-data.sh

Archived: Moved to /old_code_documentation/init-data.sh.deprecated

• No longer needed
• Code is now built into the Docker image
• Manual file copying step eliminated

How It Works Now

Previous Architecture (Option 2)

Host:                  Container:
./app/           →     (ignored - overridden by volume)
./data/app/      →     /app (volume mount)
./data/instance/ →     /app/instance (volume mount)
./data/uploads/  →     /app/app/static/uploads (volume mount)

New Architecture (Option 1)

Host:                  Container:
./app/           →     Baked into image during build
                       (no override)
./data/instance/ →     /app/instance (volume mount)
./data/uploads/  →     /app/app/static/uploads (volume mount)

Deployment:
docker-compose build   (includes app code in image)
docker-compose up -d   (runs image with data mounts)

Benefits of Option 1

✅ Simpler Architecture

• Single source of truth: Dockerfile
• No redundant file copying

✅ Faster Deployment

• No init-data.sh step needed
• No file sync delays
• Build once, deploy everywhere

✅ Production Best Practices

• Immutable code in image
• Code changes via image rebuild/tag change
• Cleaner separation: code (image) vs data (volumes)

✅ Better for CI/CD

• Each deployment uses a specific image tag
• Easy rollback: just use old image tag
• Version control of deployments

✅ Data Integrity

• Data always protected in /data/instance and /data/uploads
• No risk of accidental code deletion

Migration Path for Existing Deployments

If you're upgrading from Option 2 to Option 1:

# 1. Stop the old container
docker-compose down

# 2. Backup your data (IMPORTANT!)
cp -r data/instance data/instance.backup
cp -r data/uploads data/uploads.backup

# 3. Update docker-compose.yml
# (Already done - remove ./data:/app volume)

# 4. Rebuild with new Dockerfile
docker-compose build --no-cache

# 5. Start with new configuration
docker-compose up -d

# 6. Verify app is running
docker-compose logs digiserver-app

Data Persistence

Your data is safe because:

• Database: Still mounted at ./data/instance
• Uploads: Still mounted at ./data/uploads
• Only code location changed (from volume mount to image)

What to Do If You Need to Update Code

Development Updates

# Make code changes in ./app/
git pull
docker-compose build   # Rebuild image with new code
docker-compose up -d   # Restart with new image

Production Deployments

# Option A: Rebuild from source
docker-compose build
docker-compose up -d

# Option B: Use pre-built images (recommended for production)
docker pull your-registry/digiserver:v1.2.3
docker tag your-registry/digiserver:v1.2.3 local-digiserver:latest
docker-compose up -d

Rollback Procedure

If something goes wrong after updating code:

# Use the previous image
docker-compose down
docker images | grep digiserver  # Find previous version
docker tag digiserver-v2-digiserver-app:old-hash \
           digiserver-v2-digiserver-app:latest
docker-compose up -d

Or rebuild from a known-good commit:

git checkout <previous-commit-hash>
docker-compose build
docker-compose up -d

Monitoring Code in Container

To verify code is inside the image (not volume-mounted):

# Check if app folder exists in image
docker run --rm digiserver-v2-digiserver-app ls /app/

# Check volume mounts (should NOT show /app)
docker inspect digiserver-v2 | grep -A10 "Mounts"

Troubleshooting

"Module not found" errors

Solution: Rebuild the image

docker-compose build --no-cache
docker-compose down
docker-compose up -d

Database locked/permission errors

Solution: Check instance mount

docker exec digiserver-v2 ls -la /app/instance/

Code changes not reflected

Remember: Must rebuild image for code changes

docker-compose build
docker-compose restart

Files Changed Summary

File	Change	Reason
docker-compose.yml	Removed ./data:/app volume	Code now in image
Dockerfile	Updated comments	Clarify immutable code approach
init-data.sh	Archived as deprecated	No longer needed
deploy.sh	No change needed	Already doesn't call init-data.sh

Testing Checklist ✅

• Docker builds successfully
• Container starts without errors
• App responds to HTTP requests
• Database persists in ./data/instance
• Uploads persist in ./data/uploads
• No volume mount to ./data/app in container

Performance Impact

Startup Time: ~2-5 seconds faster (no file copying) Image Size: No change (same code, just built-in) Runtime Performance: No change Disk Space: Slightly more (code in image + docker layer cache)

---

Reference

• Analysis Document: old_code_documentation/DEPLOYMENT_ARCHITECTURE_ANALYSIS.md
• Old Script: old_code_documentation/init-data.sh.deprecated
• Implementation Date: January 17, 2026
• Status: ✅ Production Ready