Self-Hosted eCommerce Builder Install Guide

Gather these before you start. Tick the step when you have each one, or know where you will get it.

• An AI assistant: any one of them, as described above.
• Hosting with your custom domain set up. Your own computer to build and test first (recommended), and a hosting account with a Linux server when you go live, with your custom domain pointed at it. If you do not have these yet, your assistant can walk you through choosing a host, creating the server and pointing your domain at it, and step 8 covers it. You sign up and pay, and it handles the rest with you. Ubuntu 22.04 or newer works, with 1 GB of memory at minimum and 2 GB better. Hetzner, DigitalOcean, Linode and Vultr all work. Shared hosting does not.
• A Stripe account. Test mode is enough to start. Live payments need Stripe to verify your business, which can take a few days, so sign up early.
• Email (SMTP) details: host, port, username, password and a from address. Email matters as much as Stripe. The shop sends order confirmations, download access and password resets by email, so customers cannot get what they bought without it. Your assistant can tell you where to find these for your email provider.
• Your shop name and currency. The currency must match your Stripe account's default currency.

Finding your Stripe keys and your email details usually takes the longest, so start on those first. The install itself is quick once they are ready.

python --version
git --version

python3 --version
git --version

Keep everything in one permanent place, not your Downloads folder. Make a folder called Djangify inside your Documents folder, then download the code ZIP and unzip it into the Djangify folder. That is a couple of clicks.

The right folder to work in is the one that contains manage.py. I call it djangify-ebuilder here, so use whatever yours is called. If you see a folder inside a folder, go one level deeper.

mkdir "$HOME\Documents\Djangify"

mkdir -p ~/Documents/Djangify

Open the folder in your assistant

If your assistant can open folders (Claude Code and Codex can), open the code folder, the one with manage.py, as your project. It can then read everything and does not need uploads. A normal chat window cannot open a folder, so there you upload a few files in the next step instead.

It may ask permission to create a folder outside the project. Say yes. The notes folder sits next to your code folder on purpose, so anything you keep in it stays out of the shop's own files.

When it is done you should have this:

mkdir "$HOME\Documents\Djangify\docs"

mkdir -p ~/Documents/Djangify/docs

These two take the longest, because you collect details from other websites, so it helps to do them early. Your shop needs both. Stripe takes the payments, and email sends order confirmations, download access and password resets. Without email, customers cannot get what they bought.

Your Stripe test keys

1. Sign in at dashboard.stripe.com and switch to Test mode. Stripe may call this a sandbox.
2. Open Developers, then API keys.
3. Copy the Publishable key. It starts with pk_test_.
4. Click to reveal the Secret key and copy it. It starts with sk_test_.

Your email (SMTP) details

You need five things from your email provider: the host (for example smtp.gmail.com), the port (usually 587), your username (normally your full email address), your password, and the address you want order emails to come from. Gmail needs an App Password rather than your normal password. Every provider is a little different, so ask your assistant about yours, or see the email setup page for Gmail, Microsoft 365, SendGrid, Mailgun, Namecheap and GoDaddy.

Save everything in a plain text file called my-keys.txt inside your docs folder. Make this file yourself rather than asking your assistant to, so the keys and password never pass through a chat. It should look like this:

STRIPE_PUBLIC_KEY=pk_test_paste_yours_here
STRIPE_SECRET_KEY=sk_test_paste_yours_here
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_HOST_USER=you@example.com
EMAIL_HOST_PASSWORD=paste_yours_here
DEFAULT_FROM_EMAIL=noreply@yourdomain.com

Also look at your Stripe account's default currency. You will match it to your shop in step 11.

Python is the language the shop is written in, and your computer needs it installed to run the shop. You need version 3.11 or newer. Git is a tool for tracking changes to code. It is optional here, because your download is a ZIP.

sudo apt update
sudo apt install -y python3 python3-venv python3-pip python3-dev build-essential git

python --version
git --version

python3 --version
git --version

This step puts the shop's parts in place. It sounds bigger than it is. Your assistant makes a private box for the shop's parts (called a virtual environment, so nothing clashes with other software on your computer), downloads the parts the shop needs, and makes your settings file from the template.

cd "$HOME\Documents\Djangify\djangify-ebuilder"
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

cd ~/Documents/Djangify/djangify-ebuilder
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

The .env file is a list of settings for your shop: your web address, your payment keys, your email details and two secret keys. Your assistant fills in everything that is not a secret. The only things you type yourself are the secret values, and the assistant tells you exactly where each one goes.

notepad .env

nano .env

python -c "import secrets; print(secrets.token_urlsafe(50))"
python manage.py generate_encryption_key

DEBUG=True
SECRET_KEY=paste_your_secret_key
ALLOWED_HOSTS=localhost,127.0.0.1
SITE_URL=http://localhost:8000
CSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000
CORS_ALLOWED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000
SESSION_COOKIE_SECURE=False
CSRF_COOKIE_SECURE=False
ADMIN_EMAIL=you@example.com
STRIPE_PUBLIC_KEY=pk_test_paste_yours_here
STRIPE_SECRET_KEY=sk_test_paste_yours_here
STRIPE_WEBHOOK_SECRET=leave_for_step_10
ENCRYPTION_KEY=paste_your_encryption_key

DEBUG=False
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
SITE_URL=https://yourdomain.com
CSRF_TRUSTED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
CORS_ALLOWED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com
SESSION_COOKIE_SECURE=True
CSRF_COOKIE_SECURE=True

EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_HOST_USER=you@example.com
EMAIL_HOST_PASSWORD=paste_your_email_password
EMAIL_USE_TLS=True
DEFAULT_FROM_EMAIL=noreply@yourdomain.com

A. On your own computer

Your assistant creates the shop's database, makes your admin login, collects the files the site needs and starts the shop so you can see it in your browser.

python manage.py migrate
python manage.py createsuperuser_verified
python manage.py collectstatic --no-input
python manage.py create_default_settings
python manage.py create_default_policies

python manage.py runserver

Building on your own computer first is the safest route. Set up the shop and add products now, then do part B when you are ready to go live.

B. On your live server

Your assistant checks each stage in turn and tells you the command for each check. You tell it what you see.

The shop has a built-in health page at /health/. It answers ok with status 200 when the app is running. You want to see a 200, your home page loading with a padlock, and your admin login working.

curl -s -o /dev/null -w "%{http_code}\n" https://yourdomain.com/health/

(Invoke-WebRequest https://yourdomain.com/health/).StatusCode

A webhook is how Stripe tells your shop that a payment worked, so the order is marked paid and the customer gets their download. Stripe needs a public HTTPS address to reach, so do this on your live server.

1. In Stripe (still in Test mode), open Developers, then Webhooks, then Add endpoint.
2. Set the URL to:

   https://yourdomain.com/shop/webhook/

3. Select these three events. The shop's webhook code handles all of them:
   • payment_intent.succeeded completes the order and grants access to the download.
   • payment_intent.payment_failed records the failed attempt.
   • checkout.session.completed is the safety net for free orders paid with a 100 percent coupon.
4. Save the endpoint, open it, and reveal the Signing secret. It starts with whsec_.
5. Put it in your .env yourself, then restart the service:

   STRIPE_WEBHOOK_SECRET=whsec_paste_yours_here

   sudo systemctl restart ebuilder

In Stripe, use Send test webhook on the endpoint. A 200 response means it is wired up. A 400 means the signing secret in your .env does not match.

stripe listen --forward-to localhost:8000/shop/webhook/

If you save Stripe keys in Admin, Shop Settings, those saved values win over the ones in .env. Keep the two places in agreement.

Settings in the admin

• Pages, then Site Settings: business name, site URL, support email, logo, colors and fonts, and the currency code and symbol. The default is GBP, so change it if yours differs. It must match your Stripe account's currency.
• Shop, then Shop Settings: your Stripe keys if you prefer to keep them here rather than in .env, and your SMTP email details. Both are saved encrypted, which is why your ENCRYPTION_KEY must be set.
• Info Pages: read and edit the draft policy pages from step 8 so they describe your business.

Add a product

Go to Shop, then Products and add a title, description, image, the downloadable file and a price. Set it to published.

python manage.py test_stripe
python manage.py test_email --to you@example.com

Card number   4242 4242 4242 4242
Expiry        any future date
CVC           any 3 digits

Make a test purchase

On your shop, add the product to the cart and check out with Stripe's test card. Then confirm four things: the order appears in Admin, Orders and is marked paid; the confirmation email arrives; the download works from the customer dashboard; and Stripe shows the webhook as delivered. Finally, select the test order and use Refund selected orders via Stripe to practice a refund.

1. In Stripe, switch from Test mode to Live mode.
2. Copy your live keys from Developers, API keys: pk_live_ and sk_live_.
3. Create a new webhook endpoint in Live mode. Webhooks are separate for each mode. Use the same URL and the same three events as step 10, and copy its new whsec_ secret.
4. Replace all three values in your server .env. If you also saved Stripe keys in Admin, Shop Settings, update them there too, because those win over .env.

   STRIPE_PUBLIC_KEY=pk_live_paste_yours_here
   STRIPE_SECRET_KEY=sk_live_paste_yours_here
   STRIPE_WEBHOOK_SECRET=whsec_paste_the_live_one_here

5. Restart and check:

   sudo systemctl restart ebuilder
   python manage.py test_stripe

   test_stripe should now say LIVE.
6. Confirm DEBUG=False, both cookie flags are True, and your currency still matches Stripe.
7. Make one small real purchase with your own card, check the order, the confirmation email and the download, then refund it from the admin.

There are three parts: register Claude as an allowed application, run a small second service next to your shop (the sidecar), and add two routes to your Caddy config. Then you add the connector inside Claude.

python manage.py mcp_create_client

[Unit]
Description=Djangify eCommerce - MCP sidecar (Claude connector)
After=network.target

[Service]
User=youruser
WorkingDirectory=/home/youruser/ebuilder
Environment=DJANGO_SETTINGS_MODULE=ebuilder.settings
Environment=MCP_OAUTH_ISSUER=https://yourdomain.com
Environment=MCP_RESOURCE_URL=https://yourdomain.com/mcp
Environment=MCP_ALLOWED_HOSTS=yourdomain.com
ExecStart=/home/youruser/ebuilder/venv/bin/uvicorn mcp_server.app:app --host 127.0.0.1 --port 8001
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now ebuilder-mcp.service

    handle /mcp* {
        reverse_proxy 127.0.0.1:8001
    }
    handle /.well-known/oauth-protected-resource* {
        reverse_proxy 127.0.0.1:8001
    }

curl -s -o /dev/null -w "%{http_code}\n" https://yourdomain.com/.well-known/oauth-protected-resource/mcp
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://yourdomain.com/mcp -H "Content-Type: application/json" -d '{}'

Add it in Claude

In Claude, go to Settings, Connectors, Add custom connector, and enter https://yourdomain.com/mcp. Leave any Client ID and Secret fields blank. Claude opens a sign-in prompt, and you log in as the shop owner and approve it.

Back up from the admin

Log in as the owner and open Data, then Backups (or go straight to /admin/downloads/). Click Download full backup (.zip). The zip holds database.json, your whole media/ folder and a short README. Keep it off the server, on your own computer or in cloud storage, and keep the last three or four.

Updates

Updates are included for 12 months from purchase, or until you use your 5-download allowance, whichever comes first. Take a backup, then ask your assistant to replace the application files with the new version, keeping your .env, your data/ folder and your media/ folder, and run the update commands.

python manage.py dumpdata > backup.json
tar -czf media-backup.tar.gz media/

source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic --no-input
sudo systemctl restart ebuilder