Cookiecutter for django-SHOP

Powered by Cookiecutter, cookiecutter-django-shop is a set of templates for jumpstarting a django-SHOP project quickly.

Use these Cookiecutter Templates to run one of the demo merchant implementations.

• To get a first impression on its features.
• Select the configuration example which is the most similar to your own requirements. Then replace the product models and templates with your own implementations.

Quick How-To

Install Cookiecutter, pipenv and npm onto your operating system, for instance

on Ubuntu

Check that your default Python is version 3.5 or later. In Ubuntu-18.04, Python version 2.7 is the default, therefore activate Python-3.6 using:

sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.7 1

Before installing django-SHOP, a few additional packages must be added:

sudo apt install nodejs npm python3-pip
pip install --user pipenv cookiecutter autopep8

on MacOS

Check that you have install Python version 3.6 or later. If unsure, invoke python --version in a terminal. Otherwise download the latest stable Python release and install it following the instructions.

Check that you have installed NodeJS version 12 or later. If unsure, invoke node --version in a terminal. Otherwise download NodeJS and install it following the instructions.

Kickstarting

To kickstart the project, we must install three Python packages globally:

pip install --user pipenv cookiecutter autopep8
PATH="$(python -m site --user-base)/bin:${PATH}"

To create a demo of a running implementation of django-SHOP, change into the project's directory and invoke:

cookiecutter https://github.com/awesto/cookiecutter-django-shop

Cookicutter will ask a few questions; if unsure, just use the defaults. This creates a directory named my-shop, or whatever project name has been choosen. In django-SHOP's jargon, this generated directory is named the merchant implementation.

For simplicity let's refer to it as my-shop in this documentation. The directory my-shop is where the merchant keeps its configuration and customization. This separation keeps the core of django-SHOP at a barebone minimum. In this directory the merchant declares his own Django product models, overrides the rendering templates, adds custom modifiers to influence the final price in the cart, and defines the workflow for handling orders.

For details, please refer to the full documentation of django-SHOP.

Run django-SHOP demo locally

Running the django-SHOP demo locally is probably the best choice, when you want to experiment with alternative product models, templates, etc. and hence want to edit the code generated by the Cookiecutter template.

When asked by Cookiecutter: Select dockerize, choose 1 - n.

cd my-shop
pipenv install
npm install
pipenv run ./manage.py initialize_shop_demo
export DJANGO_DEBUG=1
pipenv run ./manage.py runserver

After the above job has finished, point a browser onto http://localhost:8000/ and login with user admin and password secret.

This demo uses SQLite as its database. It neither supports caching, nor full text searches, nor an asyncrounous worker.

Please be patient during the first page loads, because media files have to be downloaded and thumbnailed. The latter is a time-consuming task.

Run django-SHOP demo in Docker

Running the django-SHOP demo inside a Docker container, allows you to test all features such as full text search using Elasticsearch, Redis caching, running asynchronous tasks and it uses Postgres instead of SQLite as the database. All these services run in a separate Docker containers, all managed by docker-compose.

There are three different options to run the merchant implementation of django-SHOP inside a Docker container:

• runserver: is intended for local development, for those who do not want to setup their own virtual Python environment.
• uwsgi: is intended for testing a productive or staging system, without having set up NGiNX (see below).
• nginx: is intended for productive environments, where the application server runs behind NGiNX.

After generating the project using Cookiecutter, all of them can be build using these commands:

cd my-shop
docker-compose up --build -d

Run django-SHOP in Docker using runserver

When asked by Cookiecutter: Select dockerize, choose 2 - runserver and debug="y", to build the merchant implementation using Django's built-in runserver. This will start a webserver, listening on the IP-address of the docker-machine and on port 9009 (if unsure invoke docker-machine ip). Here the working directory is mounted inside your local file system. After editing a file, the webserver is restarted, so this setup is well suited during development.

Point a browser onto http://<docker-machine-ip>:9009/ and start surfing. To access the Django admin interface, log in as admin with password secret.

Run django-SHOP in Docker using uwsgi

In environments, accesible from the Internet, we shall never run the application server using Django's runserver. By chosing 3 - uwsgi for dockerize, Django runs as a uWSGI application runner. This configuration can be used to run an unencrypted demo shop, for instance in a staging environment.

Point a browser onto http://<docker-machine-ip>:9009/ and start surfing. To access the Django admin interface, log in as admin with password secret.

Run django-SHOP behind an NGiNX proxy

In the previous configuration, the uWSGI application runner is configured to listen on port 9009 and serve HTTP requests directly. In a productive environment, we usually want to use NGiNX as a reverse proxy in front of our Django application server. This allows us to dispatch our services on multiple domains. In addition, NGiNX also supports https via Let's Encrypt.

First we must create two separate Docker containers. This step must be done only once per host. Behind this setup, we can connect as many application servers as our machine can handle. In a separte folder, named for instance NGiNX-Proxy, create a file named docker-compose.yml adding the following content:

version: '2.0'  # or later

services:
  nginx-proxy:
    restart: always
    image: jwilder/nginx-proxy:latest
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - nginxcerts:/etc/nginx/certs:ro
      - nginxvhostd:/etc/nginx/vhost.d
      - /usr/share/nginx/html
      - /var/run/docker.sock:/tmp/docker.sock:ro
    networks:
      - nginx-proxy

  letsencrypt-nginx-proxy-companion:
    restart: always
    image: jrcs/letsencrypt-nginx-proxy-companion
    # environment:  # remove this fake certificate in production
    # - ACME_CA_URI=https://acme-staging.api.letsencrypt.org/directory
    volumes:
      - nginxcerts:/etc/nginx/certs:rw
      - /var/run/docker.sock:/var/run/docker.sock:ro
    volumes_from:
      - nginx-proxy

networks:
  nginx-proxy:
    external: true

volumes:
  nginxcerts:
  nginxvhostd:

Start both containers, the proxy together with its companion:

docker-compose up -d

If both containers are running, switch back to your the directory and recreate the project answering Cookiecutter on Select dockerize with 4 - nginx. This creates a template which again can be built into a composition of Docker containers with our usual build command (see above).

Here it is important to note that the webserver is listening on the IP address referenced by the answer given on the Cookiecutter question virtual_host. Then point a browser onto http://<virtual_host>/ and start surfing. After a few minutes, the SSL-certificate shall be ready, then you can even browse using https.

Where to proceed from here?

Now that you have a simple working project, it usually is much easier to evolve into a real project for the merchant's needs. Remember that there are 3 different ways to arrange your product models:

• commodity: If you want to use a freeform CMS page to describe your products. It is usually the best solution if you only have a handful of products, or if the kind of product differs a lot.
• smartcard: If you have one concrete product model for all products in your shop.
• polymorphic: If you have different kinds of products, each requiring their own concrete product model.

By answering the Cookiecutter builder with YES to use_i18n, multilingual support is added to the project. Currently only English and German are configured, but this can easily be changed by adopting the LANGUAGE parameters in the project's settings.py.

By answering the Cookiecutter builder with YES to use_paypal, PayPal support is added to the project. You have to apply for PayPal credentials and add them to your environment or into the project's settings.py or through the environment variables PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET.

By answering the Cookiecutter builder with YES to use_stripe, Stripe support is added to the project. Currently you may use the sandbox credentials provided with the demo, but feel free to apply for your own ones and add them to the appropriate parameters in your settings.py or through the environment variables STRIPE_PUBKEY and STRIPE_APIKEY.

By answering the Cookiecutter builder with YES to use_sendcloud, SendCloud support is added to the project. You have to apply for your own ones credentials, since SendCloud does not offer any sandboxing.