This guide covers common issues you may encounter with your self-hosted eCommerce Builder and how to resolve them.
Container and Docker Issues
Problem: Container Won't Start
If docker compose up -d fails or the container immediately stops:
First, check the logs to see what error occurred: docker compose logs web
Common causes include:
Port 8000 already in use. Check what is using the port: sudo lsof -i :8000. Stop the conflicting application or change your eCommerce Builder port in docker-compose.yml.
Invalid environment variables. Review your .env file for syntax errors, missing quotes, or invalid values.
Permissions issues. Ensure the data directory is writable: sudo chown -R 1000:1000 data/
Docker daemon not running. Start Docker: sudo systemctl start docker
Try rebuilding the container from scratch: docker compose down, then docker compose build --no-cache, then docker compose up -d
Problem: Container Keeps Restarting
If docker compose ps shows your container restarting repeatedly:
Check the logs for the specific error: docker compose logs --tail=100 web
Look for errors about missing environment variables, database connection failures, or Python import errors.
Common causes include a corrupted database, missing required environment variable in .env, or insufficient memory.
If the database is suspected, restore from your most recent backup.
Problem: Cannot Connect to Container
If docker compose exec commands fail:
Verify the container is actually running: docker compose ps
Check that you are in the correct directory containing docker-compose.yml.
Ensure you are using the correct service name. The service is called "web" in the default configuration.
Try stopping and starting: docker compose down, then docker compose up -d
Static Files and CSS Issues
Problem: Site Loads But Has No Styling
If your site appears as plain HTML with no CSS styling:
The static files may not have been collected. Run: docker compose exec web python manage.py collectstatic --no-input
Then restart the container: docker compose restart
Check your browser's developer console (F12) for 404 errors loading CSS files.
Verify WhiteNoise is properly configured in settings.py (it should be in the default installation).
Try a hard refresh in your browser: Ctrl+Shift+R on Windows/Linux or Cmd+Shift+R on Mac.
Clear your browser cache completely and try again.
Problem: Admin Panel Styling Broken
If the admin interface appears unstyled:
Verify Adminita is installed: docker compose exec web pip list | grep adminita
Run collectstatic again: docker compose exec web python manage.py collectstatic --no-input
Check that STATIC_ROOT is configured correctly in settings.py.
Restart the container: docker compose restart
Problem: Images Not Displaying
If product images or uploaded files do not display:
Check that the media directory has correct permissions: ls -la data/media
It should be writable by the container user (typically UID 1000).
Verify the image file actually exists in data/media/products or the appropriate subdirectory.
Check your MEDIA_URL and MEDIA_ROOT settings in settings.py.
Ensure Caddy is properly proxying requests to your application without blocking media files.
Database Issues
Problem: Database Locked Errors
If you see "database is locked" errors:
This occurs when multiple processes try to write to SQLite simultaneously.
Check that only one container is running: docker compose ps
Restart the container: docker compose restart
If the problem persists frequently, consider migrating to PostgreSQL for better concurrency handling.
Problem: Cannot Access Admin After Password Change
If you have forgotten your admin password or cannot log in:
Reset the password using the Django management command: docker compose exec web python manage.py changepassword your@email.com
Enter a new password when prompted.
If you have forgotten your email address, list all superusers: docker compose exec web python manage.py shell, then type: from accounts.models import User; print(list(User.objects.filter(is_superuser=True).values_list('email', flat=True)))
Type exit() to leave the shell.
Problem: Database Corruption
If you suspect database corruption:
Check database integrity: docker compose exec web python manage.py dbshell, then run: PRAGMA integrity_check;
If the result is not "ok", your database is corrupted.
Stop the application immediately: docker compose down
Restore from your most recent backup: docker compose exec -T web python manage.py loaddata backup.json
If you have no backup, try running: PRAGMA wal_checkpoint(TRUNCATE); in the database shell, but data loss may occur.
Always maintain regular backups to prevent permanent data loss.
Payment and Stripe Issues
Problem: Payments Fail Immediately
If customers see an error when trying to pay:
Verify your Stripe keys are correct in .env: STRIPE_PUBLIC_KEY and STRIPE_SECRET_KEY
Ensure you are using keys from the correct mode (test keys for testing, live keys for production).
Check that your keys start with the correct prefix: pk_live or pk_test for public keys, sk_live or sk_test for secret keys.
Restart the application after any .env changes: docker compose restart
Test with Stripe test card 4242 4242 4242 4242 if in test mode.
Check your Stripe dashboard for declined payments or error messages.
Problem: Payment Succeeds But No Order Created
This is almost always a webhook issue:
Check your Stripe webhook configuration. Go to Stripe Dashboard, Developers, Webhooks.
Verify the webhook URL is correct: https://yourdomain.com/shop/webhook (include the trailing slash).
Ensure the webhook is listening for payment_intent.succeeded and payment_intent.payment_failed events.
Check that STRIPE_WEBHOOK_SECRET in your .env matches the webhook signing secret in Stripe.
Verify your webhook secret is from the same mode (test or live) as your API keys.
In Stripe, click on the webhook and check the "Event log" tab to see if events were delivered successfully.
If events show "Failed" with 4xx or 5xx errors, check your application logs: docker compose logs web | grep webhook
Test the webhook manually by clicking "Send test webhook" in Stripe.
Ensure your domain's SSL certificate is valid. Stripe requires HTTPS.
Make sure your server's firewall is not blocking inbound requests from Stripe.
Problem: Orders Created But Downloads Not Available
If orders appear in the admin but customers cannot download files:
Verify the product has files attached. Go to Admin, Shop, Products, edit the product, and check the Downloads section.
Check that download files exist in data/media/downloads/.
Verify download limits are not set to zero for the product.
Check the order details in Admin, Shop, Orders to ensure downloads_remaining is greater than zero.
Review application logs for permission errors when serving files: docker compose logs web | grep download
Email Issues
Problem: Emails Not Sending
If order confirmations or password reset emails are not delivered:
Check your email configuration in .env. Verify EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, and EMAIL_HOST_PASSWORD are correct.
For Gmail, ensure you are using an App Password, not your regular Gmail password.
Test email sending manually: docker compose exec web python manage.py sendtestemail your@email.com
Check for error messages in the output.
Verify EMAIL_USE_TLS is set to True for port 587 or False for port 465 (SSL).
Check that your SMTP provider allows sending from the address specified in DEFAULT_FROM_EMAIL.
Some email providers require you to verify sender addresses before allowing outbound mail.
Check your server's firewall allows outbound connections on port 587 or 465.
Problem: Emails Go to Spam
If emails are being delivered but marked as spam:
Configure SPF and DKIM records for your domain. Check your email provider's documentation for specific DNS records to add.
Use a domain-based FROM email address rather than a generic Gmail address.
Avoid spam trigger words in email subject lines and content.
Consider using a transactional email service like SendGrid, Mailgun, or Amazon SES instead of Gmail for production.
Ask customers to whitelist your email address.
Problem: Email Configuration Not Working from Admin
If you set email settings in Admin, Shop Settings but emails still fail:
Remember that .env settings take precedence over admin settings for self-hosted installations.
To use admin settings, temporarily comment out the EMAIL_* variables in your .env file.
Restart the container after changing .env: docker compose restart
For production, we recommend setting email configuration in .env for consistency and easier version control.
Domain and SSL Issues
Problem: Site Not Accessible via Domain
If your domain does not load your site:
Verify DNS propagation. Use whatsmydns.net to check if your domain resolves to your server's IP address.
Check both the root domain and www subdomain.
If DNS has not propagated, wait 15-30 minutes and check again. Full propagation can take up to 48 hours.
Verify your A records in your domain registrar point to the correct IP address.
Check that your firewall allows traffic on ports 80 and 443: sudo ufw status
Ensure Caddy is running: sudo systemctl status caddy
Review Caddy logs: sudo journalctl -u caddy -n 50
Problem: SSL Certificate Not Issued
If your site loads via HTTP but not HTTPS:
Caddy cannot issue SSL certificates until DNS fully propagates. Verify your domain resolves to your server IP using nslookup yourdomain.com
Check Caddy logs for certificate errors: sudo journalctl -u caddy -n 100
Ensure port 443 is open and accessible from the internet.
If you use Cloudflare, ensure the orange cloud (proxy) is turned OFF. Cloudflare's proxy interferes with Let's Encrypt validation.
Verify your Caddyfile syntax is correct: sudo caddy validate --config /etc/caddy/Caddyfile
Try reloading Caddy: sudo systemctl reload caddy
If the problem persists, try restarting Caddy: sudo systemctl restart caddy
Problem: Mixed Content Warnings
If you see warnings about "mixed content" or insecure resources:
Ensure CSRF_TRUSTED_ORIGINS in .env includes https:// prefix.
Check that your site's base URL in Pages, Site Settings uses https://.
Look for any hardcoded http:// URLs in your templates or content.
Use relative URLs or protocol-relative URLs where possible.
Permission Errors
Problem: Permission Denied on Media Files
If you see permission errors when uploading files:
Fix ownership of the data directory: sudo chown -R 1000:1000 /home/user/ebuilder/data
Restart the container: docker compose restart
Check directory permissions: ls -la data/media
Directories should be 755 and files should be 644.
Problem: Cannot Write to Database
If you see "unable to open database file" or similar errors:
Check database directory permissions: ls -la data/db
Fix ownership: sudo chown -R 1000:1000 data/db
Ensure the database file itself is writable: chmod 644 data/db/db.sqlite3
Verify disk space is not full: df -h
Performance Issues
Problem: Site Loads Slowly
If your site is noticeably slow:
Check server resource usage: docker stats
If CPU is consistently high, investigate what processes are consuming resources.
If memory usage is near 100%, consider upgrading to a server with more RAM.
Review application logs for slow database queries: docker compose logs web | grep "slow"
Ensure collectstatic has been run to serve static files efficiently.
Check your network latency between your location and the server.
Consider using a CDN for static assets if serving a global audience.
Review and optimize any custom code or templates you have added.
Problem: High Memory Usage
If your container uses excessive memory:
Check current usage: docker stats --no-stream
Restart the container to clear any memory leaks: docker compose restart
If memory usage remains high, check for large files in /tmp inside the container.
Consider increasing your server's RAM if you have many products or high traffic.
Review logs for errors that might indicate a memory leak.
Problem: Database Growing Large
If your database file grows unexpectedly large:
Check database size: ls -lh data/db/db.sqlite3
Review your data for unnecessary test orders or content that can be deleted.
Vacuum the database to reclaim space: docker compose exec web python manage.py dbshell, then run: VACUUM;
This optimizes the database file but does not delete data.
Consider implementing regular cleanup of old orders if appropriate for your business.
Update and Migration Issues
Problem: Errors After Update
If you encounter errors after updating to a new version:
Check that you ran migrations: docker compose exec web python manage.py migrate
Check that you collected static files: docker compose exec web python manage.py collectstatic --no-input
Review the CHANGELOG file included with the update for any special instructions.
Check application logs: docker compose logs --tail=100 web
If the issue is severe, restore your backup and roll back to the previous version.
Report the issue to support with full error messages and steps to reproduce.
Problem: Migration Fails
If database migrations fail during an update:
Check the specific error message in the output carefully.
Ensure no other processes are accessing the database. Stop the container, then run migrations: docker compose down, then docker compose run --rm web python manage.py migrate
If a specific migration is failing, note the app name and migration number.
Restore from backup if the migration cannot be completed.
Contact support with the full error message for assistance.
Getting Additional Help
If you have tried the troubleshooting steps above and still need assistance:
Before Contacting Support:
Take note of the exact error message you are seeing.
Check application logs: docker compose logs --tail=100 web > logs.txt
Note what you were doing when the problem occurred.
Document the steps you have already tried.
Prepare any relevant screenshots.
Information to Include:
Your eCommerce Builder version number.
Your server's operating system and version.
Docker and Docker Compose versions: docker --version and docker compose version
The contents of your docker-compose.yml (remove sensitive data).
Relevant sections of your .env file (remove actual keys and passwords).
Full error messages and stack traces from logs.
Contacting Support:
Email: djangify@djangify.com
Subject line: "Self-Hosted Support: Brief Description of Issue"
Include all information listed above.
Be as specific as possible about the problem and what you have tried.
Support Limitations:
Support for the self-hosted version covers bugs in the application code and assistance understanding documentation.
Support does not include custom modifications, server setup assistance beyond the provided documentation, or troubleshooting issues caused by modifications you have made to the code.
For custom development or hands-on server assistance, consider the managed hosting option where all infrastructure is handled for you.