Django Oscar E-Commerce Store on AWS User Guide

Overview

Django Oscar is a mature open source e-commerce framework for the Django web framework. It provides a full storefront and a comprehensive staff dashboard covering catalogue and product management, ranges and promotional offers, baskets and checkout, orders, vouchers, customer accounts and reporting, and it is designed to be extended and customised for domain specific online retail. The cloudimg image ships Oscar's own canonical starter store as a Django application in a dedicated Python virtual environment, served by gunicorn and reverse proxied behind nginx, with a PostgreSQL database, then locks it down for a marketplace appliance. gunicorn is bound to loopback 127.0.0.1:8002 and never exposed directly; nginx on port 80 is the only way in, plus an unauthenticated /healthz endpoint for load balancer probes. The image is secure by default: the sample store's default account is never created, and on the first boot of every instance a fresh Django secret key and PostgreSQL password are generated and the administrator account is created with a unique, randomly generated password written to a root only file. A sample catalogue of demonstration products, images, ranges and offers is pre loaded so the storefront, catalogue browse and dashboard are populated out of the box. Backed by 24/7 cloudimg support.

What is included:

• Django Oscar 4.1 installed in a dedicated Python virtual environment and running as the django-oscar gunicorn systemd service
• The full Oscar storefront and staff dashboard on :80, fronted by nginx with gunicorn bound to loopback only
• A PostgreSQL 16 database holding the store on a dedicated, independently resizable EBS data volume mounted at /var/lib/postgresql, with a per instance database password generated on first boot
• A pre loaded sample catalogue of demonstration products, images, ranges and offers so the store is populated on first boot
• No default account: the administrator is created on first boot with a unique random password, and a per instance Django secret key is generated, never baked into the image
• Host settings configured so sign in works on the public IP address or a custom domain, with no baked in hostname
• An unauthenticated /healthz endpoint for load balancer health probes
• postgresql.service, django-oscar.service (gunicorn) and nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Connecting to your instance

Connect over SSH on port 22 as the default login user for your operating system variant:

Prerequisites

An AWS account, an EC2 key pair in the target region, and a VPC plus subnet. m5.large (2 vCPU / 8 GiB RAM) is the recommended starting size. Security group inbound: allow 22/tcp from your management network, 80/tcp for the web application, and 443/tcp if you add TLS. Django Oscar serves plain HTTP on port 80; for production use, terminate TLS in front of it with your own domain and restrict access to trusted IP ranges (see Maintenance).

Step 1 - Launch from the AWS Marketplace

In the AWS Marketplace, search for Django Oscar by cloudimg and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch. Pick the m5.large instance type, your VPC and subnet, an EC2 key pair, and a security group that allows inbound 22 (SSH) and 80 (HTTP). Launch the instance.

Step 2 - Launch from the EC2 console or CLI

You can also launch the published AMI directly. Select it in the EC2 console Launch an instance flow, or with the CLI:

aws ec2 run-instances \
  --image-id <the-django-oscar-ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <sg-with-22-and-80> \
  --subnet-id <your-subnet>

Step 3 - Connect to your instance

ssh ubuntu@<instance-public-ip>

Step 4 - Confirm the services are running

systemctl is-active postgresql django-oscar nginx

All three report active. Django Oscar runs under gunicorn on the loopback address 127.0.0.1:8002; nginx fronts it on port 80 and PostgreSQL is bound to loopback. The application is never bound to a public interface, so nginx is the only way in.

Step 5 - Retrieve your admin password

Django Oscar uses a Django login. The username is admin and a unique password is generated on the first boot of your instance and written to a root only file:

sudo cat /root/django-oscar-credentials.txt

This file contains OSCAR_ADMIN_USER, OSCAR_ADMIN_PASSWORD and the OSCAR_URL to open in a browser. The file is mode 0600 root:root, and no default account is ever created in the image, so no shared or default credential exists. Store the password somewhere safe and change it after first sign in (see Maintenance).

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/healthz

It returns ok. This endpoint never requires authentication, so it is safe for an Elastic Load Balancer health check.

Step 7 - Confirm authentication is required

The storefront is public so shoppers can browse, but the staff dashboard and the Django admin require signing in. An unauthenticated request to the admin returns HTTP 302 and redirects to the sign in page, while the storefront and health endpoint stay open:

echo "storefront: $(curl -s -o /dev/null -w '%{http_code}' -L http://127.0.0.1/)"
echo "health    : $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/healthz)"
echo "admin     : $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/admin/)"

It prints storefront: 200, health: 200 and admin: 302. The storefront and health endpoint are open; the dashboard and admin require the per instance admin password. gunicorn is bound to loopback and nginx is the only way in.

Step 8 - Confirm the installed version and sample catalogue

Django Oscar runs on Django in a dedicated virtual environment. Confirm the framework and Oscar versions, and that the sample catalogue loaded:

/opt/django-oscar/venv/bin/python -c "import django, oscar; print('Django', django.get_version()); print('Django Oscar', oscar.get_version())"
sudo /usr/local/sbin/oscar-manage shell -c "from oscar.core.loading import get_model; print('products:', get_model('catalogue','Product').objects.count()); print('categories:', get_model('catalogue','Category').objects.count())"

It reports Django 5.2, Django Oscar 4.1, and a populated catalogue of demonstration products across several categories, so the storefront and dashboard are non empty on first boot.

Step 9 - Browse the storefront

Browse to http://<instance-public-ip>/. Django Oscar shows its storefront, branded as the cloudimg Store, with the pre loaded sample catalogue. You can browse products by category, search, and drill into product detail pages, all without signing in.

Step 10 - View a product

Click any product to open its detail page. The sample catalogue ships real products with titles, prices and stock levels, an add to basket button, wish list and review options, so you can see how a live product page looks and behaves.

Step 11 - Sign in to the dashboard

Browse to http://<instance-public-ip>/dashboard/ and sign in with admin and the password from Step 5. The Oscar staff dashboard opens with store statistics and the full set of management tools: Catalogue, Fulfilment (orders), Customers, Offers, Content pages and Reports. This is where you manage the store day to day.

Step 12 - Explore the Django admin

Oscar also exposes the standard Django admin at http://<instance-public-ip>/admin/, signed in with the same admin account. The admin lists every Oscar model, from catalogue products and categories to baskets, orders and countries, for low level data inspection and edits.

Step 13 - Add your own products and build your store

The image ships a sample catalogue so the store is not empty. When you are ready to build your own store, use the dashboard Catalogue menu to add product classes, categories and products, set stock and pricing under Partners, and configure shipping, offers and vouchers. To start from a clean catalogue, remove the sample products from Catalogue -> Products in the dashboard. Oscar is a framework designed to be forked and extended in your own Django project; see the Oscar documentation for building custom apps on top of this install.

Maintenance

• Password: the administrator password is generated on first boot and stored in /root/django-oscar-credentials.txt (mode 0600 root:root). Change it from the command line with sudo /usr/local/sbin/oscar-manage changepassword admin, or from the Django admin under the admin user.
• Add staff users: create additional dashboard users with sudo /usr/local/sbin/oscar-manage createsuperuser, or from the dashboard Customers menu.
• Restrict access: Django Oscar serves plain HTTP on port 80. For production, restrict access to trusted IP ranges in your security group, and front it with TLS (for example an Application Load Balancer with an ACM certificate, or certbot with your own domain terminating on :443). Add your domain to CSRF_TRUSTED_ORIGINS in /opt/django-oscar/oscar.env and sudo systemctl restart django-oscar if you use a custom hostname for the dashboard sign in.
• Loopback binding: gunicorn is bound to 127.0.0.1:8002 in /etc/systemd/system/django-oscar.service, so nginx is the only path in. Keep it that way - do not change the bind address to a public interface.
• Database: the store lives in the oscar PostgreSQL database on the dedicated EBS data volume mounted at /var/lib/postgresql. Back it up with sudo -u postgres pg_dump oscar > oscar.sql. The database password is generated on first boot and held in /opt/django-oscar/oscar.env (mode 0640 root:oscar). The volume is independently resizable - grow it in the EC2 console and extend the filesystem without touching the OS disk.
• Configuration: application settings are read from /opt/django-oscar/oscar.env; restart with sudo systemctl restart django-oscar after edits. Custom Django settings can be added to /opt/django-oscar/src/sandbox/settings_local.py.
• Upgrades: Django Oscar is installed from a pinned release into its virtual environment. To upgrade, update the package with /opt/django-oscar/venv/bin/pip, run sudo /usr/local/sbin/oscar-manage migrate and sudo /usr/local/sbin/oscar-manage collectstatic --noinput, then sudo systemctl restart django-oscar.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.