This is the single easiest thing to get wrong when setting up or moving a self-hosted shop. Read this before you enter any Stripe, email or AI keys.
What It Protects
Passwords and API keys that you save in your shop are never stored in plain text. They are locked in the database using a key that you generate yourself, your ENCRYPTION_KEY. Without the exact key that locked them, nothing can read them back, neither you nor the shop. The values protected are:
- Your Stripe secret key and Stripe webhook secret
- Your email (SMTP) password
- Your email marketing provider's API key
- Your AI provider's API key
- Your Pinterest conversion token
Anything you keep only in your .env file is not locked with this key.
Generating It
With your virtual environment activated, run:
python manage.py generate_encryption_key
Add the value it prints to your .env file, replacing the placeholder text that is in .env.example:
ENCRYPTION_KEY=your-generated-key-here
Restart the shop after saving the file. Do this once, early, before you enter any Stripe, email or AI keys. Every key you save afterwards is locked with whichever encryption key is active at that moment.
What You See If It Is Missing
If you try to save a Stripe, email or AI key without an encryption key, the admin shows a red error saying the server has no ENCRYPTION_KEY, and nothing is saved. Fix it by generating a key as above, restarting, and entering the key again. Older versions of the shop failed silently here, which was hard to spot.
The Failure That Actually Happens
The quiet failure is a different key, not a missing one. If you move to a new server, restore a database backup, or start a fresh .env from .env.example without carrying over the same ENCRYPTION_KEY, the shop cannot unlock the keys already saved in your database. They read back as blank. Anything that depends on a key you saved in the admin, such as Stripe, email or your email list, can stop working with no obvious error.
This catches people who follow the local-first route. You build and test your shop on your own computer, then upload the database to your server. That database holds your keys locked with your local encryption key, so the server's .env must carry the same ENCRYPTION_KEY. Other settings, such as SECRET_KEY, can be new for production. The encryption key must not.
How to Avoid It
- Back up your ENCRYPTION_KEY alongside your database. A database backup without the matching key is only half a backup. Your .env file is not included in the admin backup, so copy it somewhere safe yourself.
- When moving to a new server or uploading a build, copy your existing .env across, or at minimum the exact ENCRYPTION_KEY line. Never generate a new one on a shop that already has keys saved.
- Only run generate_encryption_key once, on a brand-new install. If you ever lose the key, nothing else is damaged. You generate a new one and enter your Stripe, email and AI keys again, because old values cannot be converted to a new key.
If Stripe or email stops working after a redeploy or server move with no obvious cause, check this first: is the ENCRYPTION_KEY in the current .env the same value as before the move?