Merge branch 'master' into gabor/add-redis-support

docker-compose.yml

@@ -21,30 +21,25 @@ services:
     image: redis:4
     ports:
       - "6379:6379"
-    
+
   ocim:
     build:
       context: .
       dockerfile: Dockerfile.ocim
-    depends_on: 
+    depends_on:
       - postgresql
       - redis
     env_file: .env
-    environment: 
-      ALLOWED_HOSTS: '["*"]'
-      DATABASE_URL: '${DATABASE_URL:-postgres://opencraft@postgresql/opencraft}'
-      REDIS_URL: '${REDIS_URL:-redis://redis:6379}'
     ports:
       - "127.0.0.1:5000:5000"
     volumes:
       - ./:/usr/src/ocim/
-    
+
   ocim-frontend:
     build:
       context: frontend/
-    depends_on: 
+    depends_on:
       - ocim
-    environment: {} 
     ports:
       - "127.0.0.1:3000:3000"
     tty: true
@@ -55,4 +50,4 @@ services:
 volumes: {}
 
 networks:
-  default:
+  default:

documentation/development/docker.md

@@ -6,55 +6,41 @@ This describes how to create an environment for development using Docker.
 
 ## Running OCIM in a docker container
 
-First, set your `.env` file as you would normally:
-```env
-DEBUG=True
-OPENSTACK_USER='username'
-OPENSTACK_PASSWORD='password'
-OPENSTACK_TENANT='tenant-name'
-OPENSTACK_AUTH_URL='https://auth.cloud.ovh.net/v2.0'
-OPENSTACK_REGION='BHS1'
-OPENSTACK_SANDBOX_SSH_KEYNAME='keypair-name'
-DEFAULT_INSTANCE_BASE_DOMAIN='example.com'
-GANDI_API_KEY='api-key'
-GITHUB_ACCESS_TOKEN='github-token'
-SECRET_KEY='tests'
-DEFAULT_INSTANCE_MYSQL_URL=...
-DEFAULT_RABBITMQ_API_URL=...
-DEFAULT_INSTANCE_RABBITMQ_URL=...
-DEFAULT_INSTANCE_REDIS_URL=...
-DEFAULT_MONGO_REPLICA_SET_USER=...
-DEFAULT_MONGO_REPLICA_SET_PASSWORD=...
-DEFAULT_MONGO_REPLICA_SET_NAME=...
-DEFAULT_MONGO_REPLICA_SET_PRIMARY=...
-DEFAULT_MONGO_REPLICA_SET_HOSTS=...
-REDIS_URL=...
-```
 
-Start a one-off container for setup of the backend:
+First, set your `.env` file as you would normally,
+but set the following vars:
+
 ```sh
-# --rm destroys the container at the end
-docker-compose run --rm ocim bash
+ALLOWED_HOSTS='["*"]'
+DATABASE_URL='postgres://opencraft@postgresql/opencraft'
+REDIS_URL='redis://redis:6379'
+```
 
-# then, inside the container...
+Run some initial setup tasks in the backend:
 
-# initialize datastores
-make migrate
-# create super user
-make manage createsuperuser
-# exit the container
-exit
+```sh
+docker-compose run --rm ocim make migrate
+docker-compose run --rm ocim make manage createsuperuser
 ```
 
-Then, start another one-off container for setting up the client-facing frontend:
+And on the frontend:
+
 ```sh
 docker-compose run --rm ocim-frontend bash -c 'npm run build-api-client && npm install'
 ```
 
-Then, start OCIM:
+Then, launch the stack (detached):
+
 ```sh
-docker-compose up
+docker-compose up -d
 ```
 
-The OCIM UI should be available at http://localhost:5000 .
-The registration UI should be available at http://localhost:3000 .
+The OCIM UI should be available at <http://localhost:5000>.
+The registration UI should be available at <http://localhost:3000>.
+
+To view or follow the logs for any of the running services, use `docker-compose logs`.
+For example:
+
+```sh
+docker-compose logs -f ocim
+```

documentation/installation.md

@@ -234,7 +234,7 @@ To access the console, you can use `shell_plus`:
 
 ## OCIM Frontend
 
-The frontend of OCIM is a single-page app using the React and Redux.
+The frontend of OCIM is a single-page app using React and Redux.
 All the code can be found inside `frontend` directory.
 All reusable UI components description been described in the `/demo` route in dev environment.
 

documentation/marketing_usage.md

@@ -0,0 +1,120 @@
+Using the Marketing app
+-----------------------
+
+Email Marketing App/functionality allows sending bulk followup emails to `Subscribers` after a predefined number of days from their instance activation. The app allows scheduling and personalizing the emails using django templates. Some of the usage examples include:
+
+1. Sending email to all users on the 25th day of their trial to remind them of the trial ending.
+2. Sending emails to users on the 10th day of their trial explaining additional features and services offered by Opencraft.
+3. Sending a feedback form after their end of trial.
+
+## Configuration Settings
+
+`marketing` app uses following django settings for configuration:
+
+1. `MARKETING_DELETE_FOLLOWUP_EMAILS_AFTER_DAYS`: An `int` value for the number of days after which a sent email record will be deleted from the database. Defaults to `30`.
+2. `MARKETING_EMAIL_SENDER`: The sender email address for marketing emails.
+3. `MARKETING_EMAIL_REPORT_RECIPIENTS`: A list of email addresses who will recieve the report email.
+
+## Email Templates
+
+### Creating a new followup email template
+
+To create a new followup email template:
+
+1. Visit page `/admin/marketing/emailtemplate/add/` on the OCIM admin.
+2. Fill in the required fields (`name`, `subject`, `html_body`, `plaintext_body` and `send_after_days`). 
+3. The fields `subject`, `plaintext_body` and `html_body` support complete django templating (explained below).
+4. Keep the is_active field unchecked and make it active after testing the template (explained below)
+5. Click on the `Save` button to create the new email template.
+
+### Personalising the email template
+
+Each template (subject, plaintext_body and html_body) are provided with some user information variables which can be used in the template to provide a personalized followup email.
+
+#### Basic template variable usage
+
+Following are the variables available in the templates:
+
+1. `full_name`: The full name of P&T or trial user stored in the profile model
+2. username
+3. `subdomain`: The instance subdomain associated with the application instance.
+4. `instance_name`: The instance_name associated with the application instance.
+5. `application`: This is an instance of the BetaTestApplication and can be used to retrieve all other information related to the application instance.
+
+Value of these variables can be used by wrapping them with double curly brackets ( `{{ variable_name }}` ) in the templates.
+Following is a sample template using some of these variables:
+
+```text
+Welcome {{ full_name }}!
+
+Your Open edX instance {{ instance_name }} is ready!
+
+Thank you for signing up with OpenCraft!
+We are very excited to have you onboard.
+
+If you need anything, or have any questions or suggestions,
+don’t hesitate to reply to this email.
+```
+
+#### Advanced template features
+
+Two reusable templates defined in OCIM source can also be used in your Email Templates
+
+1. `emails/_email_signature.html`: This template can be used to add the default signature to the emails. Add `{% include “emails/_email_signature.html %}`  in any html body where you wish to include the default signature.
+2. `emails/email_base.html`: This template contains the default styling of an OpenCraft email and can be used as base for the html body of your email templates (see image below). Add ``{% extends "emails/email_base.html" %}`` at the beginning of html body and include the content inside as `{% block content %} <your content here> {% endblock %}`
+
+The following screenshot represents these special email components:
+
+![Advanced email example](images/advanced-email-template.jpg)
+
+Following is a sample email template using the advanced features:
+
+```html
+{% extends "emails/email_base.html" %}
+{% block content %}
+    <p>Hello {{ full_name }},</p>
+    <p>Click the following link to receive a fresh pizza for free every week:
+      <a href="https://pizza.com">https://pizza.com</a>
+    </p>
+
+    <p>Thanks for your consideration.</p>
+
+    <p>Best,&nbsp;</p>
+    <p>Joe Pizza</p>
+
+    {% include "emails/_email_signature.html" %}
+{% endblock %}
+```
+
+### Testing the email templates
+
+Make sure to test the email templates before marking them active and actually sending them to our users. Following are the instructions to test them before activating:
+
+1. Open email templates in admin ( admin/marketing/emailtemplate/ )
+2. Select the email template to test.
+3. Select `Send sample email for selected templates` from the action dropdown at the bottom of the page and hit the Go button.
+![Send Sample Toolbar](images/send-sample-toolbar.png)
+
+You should receive an email in your inbox shortly with some dummy data populated for the application.
+
+## Subscribers
+
+Subscribers are a list of users who will receive the followup emails. A user not added to the Subscriber list will not receive any emails.
+
+### Adding a Subscriber
+
+A user is automatically added to the subscriber list when the first appserver is provisioned and made active.
+
+To add a new subscriber manually
+
+1. Visit /admin/marketing/subscriber/add/ on the OCIM site
+2. Fill in the user details
+3. Make sure to check the “Receive followup” checkbox. You can uncheck this field later to unsubscribe a user.
+4. Click on Save button to save the changes.
+
+!!! note
+
+	1. Emails are triggered everyday at 0100 hrs UTC and a report is sent to all the email addresses set in `MARKETING_EMAIL_REPORT_RECIPIENTS` setting, containing a list of all the emails sent afterwards.
+	2. Sent emails can be checked at `/admin/marketing/sentemail/` on admin website.
+	3. The app does not send any emails that are already delivered to the user.
+	4. `Subscriber` field `Trial started at` and `EmailTemplate` field `Send after days` are compared to determine if an email has to be sent today.

documentation/users.md

@@ -26,9 +26,10 @@ To create an instance manager user:
     In [2]: from django.contrib.contenttypes.models import ContentType
     In [3]: content_type = ContentType.objects.get_for_model(InstanceReference)
     In [4]: permission = Permission.objects.get(content_type=content_type, codename='manage_own')
-    In [5]: user = User.objects.create(username='instance_manager', password='password')
-    In [6]: user.user_permissions.add(permission)
-    In [7]: user.save()
+    In [5]: user = User.objects.create(username='instance_manager')
+    In [6]: user.set_password('password')
+    In [7]: user.user_permissions.add(permission)
+    In [8]: user.save()
 
 And set `Organization` and `UserProfile` to the right values.
 
@@ -42,6 +43,7 @@ To create a staff user:
     make shell
 
     In [1]: from django.contrib.auth.models import User
-    In [2]: user = User.objects.create(username='staff_user', password='password')
-    In [3]: user.is_staff = True
-    In [4]: user.save()
+    In [2]: user = User.objects.create(username='staff_user')
+    In [3]: user.set_password('password')
+    In [4]: user.is_staff = True
+    In [5]: user.save()

instance/models/mixins/openedx_config.py

@@ -89,8 +89,15 @@ def _get_configuration_variables(self):
                     "BLOG": "",
                     # use different contact page
                     "CONTACT": "/contact",
+                    # Explicitly set TOS_AND_HONOR link to '#' so that they are not combined.
+                    "TOS_AND_HONOR": "#"
                 },
             },
+            "EDXAPP_MKTG_URL_LINK_MAP": {
+                # set the tos and honor pages separately. Required for koa and above.
+                "TOS": "tos",
+                "HONOR": "honor"
+            },
             "EDXAPP_LMS_NGINX_PORT": 80,
             "EDXAPP_LMS_SSL_NGINX_PORT": 443,
             "EDXAPP_LMS_BASE_SCHEME": 'https',

marketing/admin.py

@@ -28,6 +28,7 @@
 
 from marketing import models
 from registration.models import BetaTestApplication
+from opencraft.utils import get_site_url
 
 
 class EmailTemplateAdmin(admin.ModelAdmin): #pylint: disable=missing-docstring
@@ -46,6 +47,9 @@ def send_sample_emails(self, request, queryset):
             instance_name="EmailTemplate Sample"
         )
         context = Context({
+            "base_url": get_site_url(),
+            "signature_title": settings.EMAIL_SIGNATURE_TITLE,
+            "signature_name": settings.EMAIL_SIGNATURE_NAME,
             "full_name": request.user.get_full_name(),
             "username": request.user.username,
             "instance_name": "EmailTemplate Sample",

marketing/utils.py

@@ -28,6 +28,7 @@
 from django.template import Context
 
 from marketing.models import Subscriber, EmailTemplate, SentEmail
+from opencraft.utils import get_site_url
 
 
 # Logging #####################################################################
@@ -43,6 +44,9 @@ def render_and_dispatch_email(template: EmailTemplate, subscriber: Subscriber):
     application = subscriber.user.betatestapplication
     user = subscriber.user
     context = Context({
+        "base_url": get_site_url(),
+        "signature_title": settings.EMAIL_SIGNATURE_TITLE,
+        "signature_name": settings.EMAIL_SIGNATURE_NAME,
         "full_name": user.profile.full_name,
         "username": user.get_username(),
         "instance_name": application.instance_name,

mkdocs.yml

@@ -6,6 +6,7 @@ repo_url: https://github.com/open-craft/opencraft
 edit_uri: edit/master/documentation/
 markdown_extensions:
   - codehilite
+  - admonition
 extra_css:
   - css/extra.css
 nav:
@@ -19,6 +20,7 @@ nav:
   - howtos.md
   - periodic_builds.md
   - infrastructure.md
+  - "Using the Marketing app": marketing_usage.md
   - "Development":
       - "Docker": development/docker.md
   - "Operations":