System Requirements
Before you begin installing the eCommerce Builder, ensure your server meets these minimum specifications:
Server Resources:
- VPS or dedicated server (shared hosting is not supported)
- Minimum: 1 CPU core and 1GB RAM
- Recommended: 2 CPU cores and 2GB RAM
Operating System:
- Ubuntu 22.04 or higher (Ubuntu 24.04 LTS recommended)
- Other Linux distributions may work but are not officially supported
Required Software:
- Python 3.11 or higher
- pip (installed with Python)
- A reverse proxy such as Caddy (recommended — handles HTTPS automatically) or Nginx
The eCommerce Builder runs as a plain Django application under Gunicorn. There is no Docker step and nothing else to install.
Additional Requirements:
- A registered domain name
- A Stripe account for payment processing
- HTTPS/SSL capability (Caddy handles this automatically)
Recommended VPS Providers: Popular choices include Hetzner, DigitalOcean, Linode, and Vultr. Choose a provider that offers good performance in your target market region.
Downloading and Extracting the Files
After purchasing the self-hosted version of eCommerce Builder, you will receive download access through your customer dashboard. You can download the files up to 5 times.
Step 1: Download the Package
Log into your account at djangify.com and navigate to your downloads area. Download the self-hosted package to your local computer.
Step 2: Build It Locally First
The recommended workflow is to build and configure your store on your own computer before touching a server at all — see the Self-Hosted Local Development Setup Guide (Phase 2). Come back to this page once you're ready to move to your VPS.
Step 3: Upload to Your Server
Once your store is working locally, upload the files to your server using SCP (scp -r djangify-ebuilder/ user@yourserver:/home/user/ebuilder) or an SFTP client such as FileZilla, WinSCP, or Cyberduck.
Step 4: Verify the Upload
Connect to your server via SSH and navigate to the directory where you uploaded the files. Verify the contents are present — you should see manage.py, requirements.txt, a .env.example file, and folders for each Django app (accounts, shop, pages, blog, and so on).
Step 5: Create Data Directories
The application needs persistent storage for your database, uploaded media files, and log files. Create these directories now:
mkdir -p data/db data/media data/logs
These directories hold your persistent data and are never touched when you update the application code.
Environment Setup
The eCommerce Builder is configured through environment variables stored in a .env file. This file contains sensitive information and should never be committed to version control or shared publicly.
Step 1: Create Your .env File
Copy the example environment file: cp .env.example .env
Then open the file for editing: nano .env
Step 2: Generate Your Secret Key
Django requires a unique secret key for security functions like session management and cryptographic signing. Generate one using Python:
python3 -c "import secrets; print(secrets.token_urlsafe(50))"
Copy this entire string and paste it as your SECRET_KEY value in the .env file.
Step 3: Generate Your Encryption Key
Stripe, SMTP and email-marketing credentials are stored encrypted in your database, not in plain text. With your virtual environment activated, generate the key used for that:
python manage.py generate_encryption_key
Add the key it prints to your .env file: ENCRYPTION_KEY=your-generated-key-here
⚠️ CRITICAL: store this key securely and back it up somewhere safe. If you lose it, every encrypted credential in your database becomes unreadable and will need to be re-entered. See the Encryption Key doc for the full detail on why this matters.
Step 4: Configure Essential Variables
Your .env file needs several required variables to function. Here is a complete example showing all the essential configuration:
Django Core Settings:
SECRET_KEY should be set to the long random string you just generated.
DEBUG should be set to False for production. Never set this to True on a live site as it exposes sensitive debugging information.
ALLOWED_HOSTS must include your domain names, separated by commas with no spaces. For example: yourdomain.com,www.yourdomain.com
CSRF_TRUSTED_ORIGINS must include your full domain URLs with https:// prefix. For example: https://yourdomain.com,https://www.yourdomain.com
Stripe Payment Settings:
STRIPE_PUBLIC_KEY is your publishable key from Stripe, starting with pk_live_ for production or pk_test_ for testing.
STRIPE_SECRET_KEY is your secret key from Stripe, starting with sk_live_ for production or sk_test_ for testing.
STRIPE_WEBHOOK_SECRET is your webhook signing secret from Stripe, starting with whsec_. This is critical for secure payment verification.
Email Configuration:
EMAIL_HOST is your SMTP server address, such as smtp.gmail.com for Gmail.
EMAIL_PORT is usually 587 for TLS or 465 for SSL.
EMAIL_HOST_USER is your full email address.
EMAIL_HOST_PASSWORD is your email password. For Gmail, you must use an App Password, not your regular Gmail password.
EMAIL_USE_TLS should be set to True if using port 587.
DEFAULT_FROM_EMAIL is the email address that will appear as the sender on customer emails, such as noreply@yourdomain.com.
Database Configuration:
By default, the application uses SQLite and no database configuration is needed. The database file will be created automatically at data/db/db.sqlite3.
If you want to use PostgreSQL instead for high-traffic sites, you can set DATABASE_URL to a PostgreSQL connection string like: postgresql://user:password@localhost:5432/ebuilder
Step 5: Secure Your .env File
After creating your .env file, ensure it has proper permissions so only you can read it:
chmod 600 .env
Never commit this file to git or share it publicly. It contains sensitive credentials that could compromise your store's security.
Step 6: Test Mode vs Live Mode
Before launching to customers, you should test your store using Stripe test mode credentials. Test mode keys are completely separate from live mode keys.
For testing, use keys starting with pk_test_ and sk_test_ from your Stripe dashboard in test mode.
For production, use keys starting with pk_live_ and sk_live_ from your Stripe dashboard in live mode.
Never mix test and live credentials. They must all match the same mode or payments will fail.
Next Steps
With your .env file configured, you are ready to proceed to the Local Development Setup Guide (Phase 2) to build your store, then the Server Configuration Guide to deploy it, set up your reverse proxy, and configure your domain.
Remember that you will need to create Stripe webhooks separately for test mode and live mode, and you must restart your application service after making any changes to your .env file for those changes to take effect.