add comments

82Flex · Nov 30, 2019 · ba56a25 · ba56a25
1 parent f28b3f4
commit ba56a25
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 60 deletions.
diff --git a/DCRM/settings.py b/DCRM/settings.py
@@ -20,80 +20,85 @@
 
 import os
 
-# SITE
-# IMPORTANT:
-# Just set this to the first Site instance's id in database.
-# Usually, it is set to 1, do not change it at the very first.
+
+# SITE ID
+"""
+!!! DO NOT CHANGE THIS SECTION IF YOU DO NOT KNOW WHAT IT MEANS !!!
+"""
 SITE_ID = 1
 
+
 # PATH
-# TIPS: Build paths inside the project like this: os.path.join(BASE_DIR, ...)
+"""
+!!! DO NOT CHANGE THIS SECTION IF YOU DO NOT KNOW WHAT IT MEANS !!!
+"""
 BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
+
 # THEME
 THEME = 'DefaultStyle'
 
+
 # FEATURES
-ENABLE_REDIS = True  # redis-server, rq are required.
-ENABLE_CACHE = True  # memcached, python-memcached are required.
-ENABLE_API = True  # restful api
+ENABLE_REDIS = True  # redis-server, rq are required
+ENABLE_CACHE = True  # memcached, python-memcached are required
+ENABLE_API = True    # restful api framework
+
 
 # SECURITY
 # WARNING: keep the secret key used in production secret!
 SECRET_KEY = '$!#)nxr8rv83s(b%#kg*8a)m%igd+o%2=mgvqkba_zbc3(bpan'
-
-# SECURITY
 # WARNING: don't run with debug turned on in production!
-DEBUG = True
-SECURE_SSL = False  # https -> True
-
-# SECURITY
+DEBUG = True         # disable it in production environment
+SECURE_SSL = False   # force https -> True
 ALLOWED_HOSTS = [
     'apt.82flex.com',  # your domain here
     '127.0.0.1',
     'localhost'
 ]
 print("[DCRM] Host: " + ALLOWED_HOSTS[0])
 
+
 # INTERNATIONAL
 USE_I18N = True
 USE_L10N = True
-USE_TZ = True  # pytz is required.
-LANGUAGE_CODE = 'en'  # zh-Hans for Simplified Chinese
-TIME_ZONE = 'Asia/Shanghai'  # Asia/Shanghai, etc.
-
-# Database
-# You cannot use SQLite3 due to the lack of advanced database supports.
-# !!! Change the 'NAME' here if you have multiple DCRM installed !!!
+USE_TZ = True                # pytz module is required.
+LANGUAGE_CODE = 'en'         # zh-Hans -> Simplified Chinese
+TIME_ZONE = 'Asia/Shanghai'
 
 
+# DATABASE
+# You cannot use SQLite3 due to the lack of advanced database supports.
+# !!! change the 'NAME' here if you have multiple DCRM installed !!!
 DATABASES = {
     'default': {
         'ENGINE': 'django.db.backends.mysql',
-        'NAME': 'DCRM',  # mysql database name here
-        'USER': 'dcrm',  # mysql user name here
-        'PASSWORD': 'dcrm_user_password',  # mysql user password here
-        'HOST': 'dcrm-db',  # if you don't use docker, set it to 127.0.0.1
+        'NAME': 'DCRM',                          # mysql database name here, should match `docker-compose.yml`
+        'USER': 'dcrm',                          # mysql user name here, should match `docker-compose.yml`
+        'PASSWORD': 'dcrm_user_password',        # mysql user password here, should match `docker-compose.yml`
+        'HOST': 'dcrm-db',                       # if you don't use docker, set it to 127.0.0.1
         'PORT': '3306',
         'OPTIONS': {
             'init_command': "SET sql_mode='STRICT_TRANS_TABLES'"
         }
     }
 }
 
+
+# REDIS (TASK QUEUE)
 if ENABLE_REDIS is True:
     # Redis
-    # !!! Change the 'DB' number here if you have multiple DCRM installed !!!
+    # !!! change the 'DB' number here if you have multiple DCRM installed !!!
     RQ_QUEUES = {
         'default': {
-            'HOST': 'dcrm-redis',  # if you don't use docker, set it to 127.0.0.1
+            'HOST': 'dcrm-redis',                # if you don't use docker, set it to 127.0.0.1
             'PORT': 6379,
             'DB': 0,
             'PASSWORD': '',
             'DEFAULT_TIMEOUT': 360,
         },
         'high': {
-            'HOST': 'dcrm-redis',  # if you don't use docker, set it to 127.0.0.1
+            'HOST': 'dcrm-redis',                # if you don't use docker, set it to 127.0.0.1
             'PORT': 6379,
             'DB': 0,
             'PASSWORD': '',
@@ -104,6 +109,8 @@
 else:
     print("[DCRM] Redis Queue: Disabled")
 
+
+# MEMCACHED (PAGE CACHING)
 CACHE_TIME = 0
 if ENABLE_CACHE is True:
     # Cache
@@ -120,19 +127,26 @@
 else:
     print("[DCRM] Page Caching: Disabled")
 
-# Nginx Locations
 
-# !!! please configure Nginx to make an alias from STATIC_URL to STATIC_ROOT !!!
+# NGINX
+"""
+!!! DO NOT CHANGE THIS SECTION IF YOU USE DOCKER !!!
+"""
+# !!! remember to configure Nginx to make an alias from STATIC_URL to STATIC_ROOT !!!
 STATIC_URL = '/static/'
 STATIC_ROOT = os.path.join(BASE_DIR, 'static')
-STATICFILES_DIRS = [
-
-]
-
-# !!! please configure Nginx to make an alias from MEDIA_URL to MEDIA_ROOT !!!
+STATICFILES_DIRS = []
+"""
+!!! DO NOT CHANGE THIS SECTION IF YOU USE DOCKER !!!
+"""
+# !!! remember to configure Nginx to make an alias from MEDIA_URL to MEDIA_ROOT !!!
 MEDIA_URL = '/resources/'
 MEDIA_ROOT = os.path.join(BASE_DIR, 'resources')
 
+
+
+
+
 """
 !!! DO NOT EDIT ANYTHING BELOW !!!
 !!! DO NOT EDIT ANYTHING BELOW !!!
@@ -248,3 +262,4 @@
     "django.contrib.staticfiles.finders.FileSystemFinder",
     "django.contrib.staticfiles.finders.AppDirectoriesFinder"
 )
+
diff --git a/README.md b/README.md
@@ -50,7 +50,11 @@ This demo is deployed using [Container Optimized OS](https://cloud.google.com/co
 如果你还没有下载此项目, 建议使用 `git` 克隆该仓库, 并修改部署设置:
 
 ```bash
+# clone this repo
 git clone --depth 1 https://github.com/82Flex/DCRM.git && cd DCRM
+
+# should be carefully
+vi DCRM/settings.py
 ```
 
 2. build and launch DCRM via `docker-compose`
@@ -60,25 +64,29 @@ git clone --depth 1 https://github.com/82Flex/DCRM.git && cd DCRM
 docker-compose up --build
 ```
 
-3. if there is no error, you can access DCRM via `http://127.0.0.1:8080/`
-如果没有发生错误, 你可以尝试访问首页
-
-4. attach to `dcrm_app` container:
+3. attach to `dcrm_app` container:
 先附加到容器中:
 
 ```bash
 docker exec -i -t dcrm_app_1 /bin/bash
 ```
 
-5. create superuser in container:
-在容器中创建后台超级管理员帐户:
+4. in container:
+在容器中执行命令:
 
 ```bash
+# collect static files
+python manage.py collectstatic
+
+# create required database structures
+python manage.py migrate
+
+# create super user in database
 python manage.py createsuperuser
 ```
 
-6. access admin panel via `http://127.0.0.1:8080/admin/`
-创建完成后, 你现在可以访问 DCRM 后台了
+5. access admin panel via `http://127.0.0.1:8080/admin/`
+现在可以尝试访问 DCRM 后台了
 
 
 ## 2.1. DOCKER COMMANDS 常用命令

diff --git a/docker-compose.yml b/docker-compose.yml
@@ -4,13 +4,13 @@ services:
   web:
     image: nginx:1.17.6
     volumes:
-      - ./docker/nginx/conf.d:/etc/nginx/conf.d
-      - ./docker/nginx/certs:/etc/nginx/certs
+      - ./docker/nginx/conf.d:/etc/nginx/conf.d         # your web configuration: docker/nginx/conf.d
+      - ./docker/nginx/certs:/etc/nginx/certs           # your https certs: docker/nginx/certs
       - app_static:/usr/share/nginx/html/static
       - app_resources:/usr/share/nginx/html/resources
     ports:
-      - "8080:80"
-      #- "80:80"  # production
+      - "8080:80"   # test
+      #- "80:80"    # production
       #- "443:443"  # https
     depends_on:
       - app
@@ -34,7 +34,7 @@ services:
     environment:
       PYTHONUNBUFFERED: 1
       DCRM_WORKER: none
-  worker-default:
+  worker-default:           # if you need more `default` workers, duplicate this section
     build: .
     volumes:
       - app_resources:/usr/src/app/resources
@@ -46,8 +46,8 @@ services:
       - memcached:dcrm-memcached
     environment:
       PYTHONUNBUFFERED: 1
-      DCRM_WORKER: default
-  worker-high:  # if you need more workers, you can duplicate this section
+      DCRM_WORKER: default  # worker priority
+  worker-high:              # if you need more `high` workers, duplicate this section
     build: .
     volumes:
       - app_resources:/usr/src/app/resources
@@ -59,27 +59,28 @@ services:
       - memcached:dcrm-memcached
     environment:
       PYTHONUNBUFFERED: 1
-      DCRM_WORKER: high  # worker priority: default/high
+      DCRM_WORKER: high     # worker priority
   db:
     image: mysql:5.7
     volumes:
       - db_data:/var/lib/mysql
     restart: always
-    environment:  # should match `DCRM/settings.py`
+    environment:
       MYSQL_ROOT_PASSWORD: dcrm_root_password
-      MYSQL_DATABASE: DCRM
-      MYSQL_USER: dcrm
-      MYSQL_PASSWORD: dcrm_user_password
+      MYSQL_DATABASE: DCRM                       # important: should match `DCRM/settings.py`
+      MYSQL_USER: dcrm                           # important: should match `DCRM/settings.py`
+      MYSQL_PASSWORD: dcrm_user_password         # important: should match `DCRM/settings.py`
   redis:
     image: redis
     restart: always
   memcached:
     image: memcached
     restart: always
 
+# your data will not lost until you clean these docker volumes
 volumes:
-  db_data:
-  app_static:
-  app_resources:
+  db_data:        # mysql database
+  app_static:     # static files
+  app_resources:  # packages
   app_temp:
 
diff --git a/uwsgi-run.sh b/uwsgi-run.sh
@@ -5,10 +5,10 @@ if [ "${DCRM_WORKER}" = "none" ]; then
     python manage.py migrate --no-input
     uwsgi --ini uwsgi.ini
 elif [ "${DCRM_WORKER}" = "default" ]; then
-    sleep 60  # wait for app
+    sleep 60  # wait for main app to launch
     python manage.py rqworker default
 elif [ "${DCRM_WORKER}" = "high" ]; then
-    sleep 60  # wait for app
+    sleep 60  # wait for main app to launch
     python manage.py rqworker high
 fi