Overview

This supplementary guide is intended for CBCA authors. This document will address aspects that may be absent or unclear in the primary author's guide. This guide will be followed along with the actual author’s guide.

This document contains a set of best practices that can upgrade your project creation skills. These best practices will help you prepare the final draft of your project. Think of these suggestions as a checklist to go through before you submit your project for review.

Title

✅ Keep the project title brief and to the point. 

✅ The title should clearly represent the main focus or idea of the project.

✅ Ensure that the title is relevant to the content and accurately reflects the scope of the project.

Summary

✅ The summary should clearly state the purpose or objective of the project.

✅ Keep the summary brief and to the point. It should not be more than 2-3 lines.

✅ Use a formal tone and avoid unnecessary jargon or extremely technical terms to confuse the learners. All the technical terms should be included in the “project description” with proper explanation.

Objectives

✅ Objectives should be directly related to the problem or challenge that the project is intended to address. They should be relevant to the overall goal of the project.

✅ Objectives should be realistic and achievable within the project's timeframe and available resources.

✅ The objectives count should be in even numbers like 2,4,6. To perfectly cover up the landing page space. An example screenshot is attached below:

Project objectives (learners' view)
Project objectives (learners' view)

Project Description

✅ Ensure that the project description is clear, concise, and easy to understand.

✅ Start off by explaining the project in a short paragraph. Describe the methodology or approach that will be used to execute the project.

✅ Then, introduce all the technical terms in the description that the learner is going to use in the project. Also, make sure to tell learners how we are going to use that particular technology.

✅ Tell the learners what we are going to achieve once we complete this project to add excitement. 

✅ Also, add a screenshot of the project's final outcome, if possible.

✅ Avoid using you/your pronouns in the project description. You may use "We/Our/Ours/Us" instead.

Project Runtime

✅ We use Docker to allow our authors to create the custom environments to accommodate a diverse range of programming languages and frameworks on our platform.

✅ First, set up the Dockerfile.

  1. Start by choosing a base image from Docker Hub. This will be the starting point for your Dockerfile using FROM statement.

  2. Identify any dependencies your application needs and install them using the appropriate package manager using the RUN statement.

  3. Copy the files for your application into the Docker image using the COPY statement.

✅ Create a tarball of the Dockerfile and the application files using the following command:

tar -czvf <tarball_name>.tar.gz Dockerfile <project_folder_name>

Make sure the Dockerfile is in the root directory of the tarball.

✅ Build the Dockerfile after uploading the tarball using the “Change Docker file (beta)” button.

Make sure to click the “Save” button upon running the application.

✅ If your Dockerfile does not build successfully, use the “Download build logs” button to verify where the error is occurring in the Dockerfile.

✅ We can create as many docker jobs as we want. But it is advised to use a single Docker Job in a project. Using one docker job does not break the flow of tasks, and the session does not restart for every task.

✅ Select the relevant Docker job type for the project.

  1. Use “Live” type Docker Job for web applications / Jupyter Notebook / DevOps projects.

  2. Use “GUI” type Docker Job for GUI applications.

We’ll discuss more about the jobs and the widgets later on. 

Content Creation

✅ Avoid using We/our/ours/us pronouns in project tasks. Use imperative sentences or use you/your pronouns.

✅ Ensure that you classify the project's tasks. The minimum amount of categories allowed is 2, while the maximum is 5.

✅ Use the following format to give a title to your task:

  Task <Task Number>: <Task Title in Title Case>

✅ Task titles should be meaningful. Examples of some that can enhance the project quality are below:

Instead of this:

Do this:

User Model

Task 5: Create a User Model

Change Function

Task 7: Update the Render Function

Deployment

Task 9: Deploy the Application

✅ Every project starts with Task 0, in which you should provide the general details of the project structure, imported tools and technologies, and the command to start the application. A sample Task 0 is provided below:

Task 0
Task 0

✅ Apart from Task 0, Structure your tasks in the following way:

  1. Explain the aim of the particular task in 1-2 lines. 

  2. Enlist the actions to be performed in the tasks in a numbered list.

  3. Give the following template statement before the hint:    

    1. If you’re unsure how to do this, click the “Show Hint” button.

  4. Provide the hints in an unordered list in the hint widget about all of the actions mentioned above.

  5. Give the following template statement before the solution:

    1. If you’re stuck, click the “Show Solution” button.

  6. Provide the Solution in a numbered list in the hint widget about all of the actions mentioned above.

    1. Rename the button from “Hide Hint / Show Hint” to “Hide Solution / Show Solution”.

    2. The code inside the bullets should be properly aligned.

  7. Additional Point: Provide all of the extra information in the blockquote.

✅ A sample task content is provided below:

General task structure
General task structure

Hint and solution should be in the given format.
Hint and solution should be in the given format.

✅ Provide the absolute path to the files in the content. An absolute path starts from /usercode/ directory.

✅ Add a congratulations task at the end of the project with the title “Congratulations!”.

✅ This is the following template to write a congratulations task:

Congratulations on completing this project! You’ve done an excellent job. Applying your skills with hands-on projects like this is a great way to get comfortable with new techniques and technologies.

You can now create applications in <Framework>. It would be best to try improving your application by <Enlist the enhancement in the project>.

You can visit the Educative Projects home page for more exciting guided projects to take your expertise to the next level.

✅ A sample congratulations task is provided below:

widget

General Code Creation Checks on the Platform

✅ All of the code changes have to be made in the preview mode.

✅ Make sure you reset the project in learner mode to see the latest changes.

✅ Upload the boilerplate application in the /usercode directory. Do not create the project directory in any directory other than /usercode because the code updates will not persist.

Note: The /usercode directory is created once the docker builds successfully on the platform. Please avoid directly creating a /usercode directory in the Dockerfile since it will be overwrite by the new /usercode directory.

✅ There are the following ways to upload your boilerplate application in the /usercode directory.

  1. Create the zip file of your application. Then, right click in the file directory and use the upload button to upload the zip file. After that, unzip the file using the terminal.

    1. apt-get install unzip

    2. unzip .zip

Note: This method only lets you upload the file having less than 1MB size.

  1. (Recommended) If you upload the project in the docker container, your application will reside in the root directory. Use the cp command to copy all the files from the root to the /usercode directory.

    1. cp -rn /<ProjectFolder>/ /usercode/<ProjectFolder>/

Note: This method keeps the original application in the root directory. In order to remove that every time the session connects, it is advised to add the follwoing command in the start script:

rm -rf /<ProjectFolder>/.

  1. You can upload your project from your git repository using the git clone <ProjectLink> command in the /usercode directory.

Note: You need to install the git CLI for this method.

✅ The maximum /usercode directory size is 500MB.

✅ Sometimes, node modules exceed this dedicated size. Use the symlinks / symbolic links of node modules from the root directory to the /usercode directory using the following command:

  ln -s /node_modules /usercode/<ProjectFolder>/node_modules

✅ Run the application task-wise in the learner mode at least once to verify if everything is working fine if you paste the code from each task and there should not be anything left missing.

✅ All the latest changes you perform in the edit mode will be reflected to the learners when you Update the project from the main page.

✅ Ensure your selected widget, checkboxes, and the Docker job name are the same in all tasks to maintain consistency. In this way, your session does not reload upon switching between the tasks.

Web application projects

Docker job

✅ Use the “Live” type docker job for web applications.

✅ Give a random input filename since it is not necessary to add any input file.

✅ Give a general command in the run script since we are not going to use the “Run” button to execute our application. We’ll be using a terminal for that. You may write the clear command in the run script.

✅ Provide the port number on which the front end of your application will be running. Application Port must be in the range 3000-8799 or 9300-65535.

Port 3000 is always open by default, which means if you provide anyother port number in job but execute your application in port 3000, you will still see your application on the browser. This helps us if we have more than one front-end apps running in the terminal.

✅ Select the “HTTPS Strict Mode” if your application is running on HTTPS mode. However, it is left unchecked in most cases.

✅ Select the “Force Relaunch On Run” option in order to restart the terminal if the learner reloads the browser on which the entire workspace is running.

✅ Enter the commands to configure and start the application in the “Star script” section. These will be executed whenever the learners start the project.

Widget selection

✅ Select the “Workspace Widget” for web applications.

✅ Make sure you select the “Allow Browser” option to show the front end of your application in the “App Browser” tab.

✅ Select the docker job name from the drop-down button which you have created on the main page.

✅ Select the same widgets, check boxes, and the docker job name for all the tasks to maintain consistency.

Code Creation

✅ In your project configuration files, you need to mention the IP address of the host as 0.0.0.0 instead of localhost if you don’t see the application on the “App Browser”.

✅ Use the curl command to verify if you are getting the response on the specific IP and port. This is good practice for debugging your application.

Note: You need to install the curl for that.

DevOps projects

Docker Job

✅ Use the “Live” type docker job for DevOps applications.

✅ Give a random input filename since it is not necessary to add any input file.

✅ Give a general command in the run script since we are not going to use the “Run” button to execute our application. We’ll be using a terminal for that. You may write the clear command in the run script.

✅ Provide the port number as 3000 since it is the default exposed port, and we are not executing any application.

✅ Select the “Force Relaunch On Run” option in order to restart the terminal if the learner reloads the browser on which the entire workspace is running.

✅ Enter the commands to configure and start the application in the “Star script” section. These will be executed whenever the learners start the project.

Widget Selection

✅ Select the “Workspace Widget” since we have a terminal in this widget.

✅ Select the “Allow Browser” option to show the front end of your application in the “App Browser” tab if you’re also running an application.

✅ Select the docker job name from the drop-down button which you have created on the main page.

✅ Select the same widgets, check boxes, and the docker job name for all the tasks to maintain consistency.

Code Creation

✅ Use the curl command to verify if you are getting the response on the specific IP and port. This is good practice for debugging your application.

✅ Use the CLI tools to deploy or configure your cloud application.

Data science projects

Docker Job

✅ Use the “Live” type docker job for DevOps applications.

✅ Learn how to execute the Jupyter Notebook on the platform using this link.

✅ Give a general command in the run script since we are not going to use the “Run” button to execute our application. We’ll be using a terminal for that. You may write the clear command in the run script.

✅ Provide 8080 as the port number.

✅ Select the “Force Relaunch On Run” option in order to restart the terminal if the learner reloads the browser on which the entire workspace is running.

✅ Enter the commands to configure and start the application in the “Star script” section. These will be executed whenever the learners start the project.

✅ Provide the dataset in the “course assets” section.

Widget Selection

✅ Select the “Workspace Widget” since we have a terminal in this widget.

✅ We can run the Jupyter Notebook in two ways.

  1. Using Jupyter Notebook configurations to show the Jupyter Notebook in the “App Browser”. 

  2. (Recommended) Using the built-in Jupyter Notebook feature of the VS code.

✅ Select the “Allow Browser” option if you want to run the Jupyter Notebook on the “App Browser”.

✅ Do not select the  “Allow Browser” option if you want to run the Jupyter Notebook through VS Code.

✅ Select the docker job name from the drop-down button which you have created on the main page.

✅ Select the same widgets, check boxes, and the docker job name for all the tasks to maintain consistency.

Code Creation

✅ Click on the .ipynb file in the file editor section to automatically open up the Jupyter Notebook in VS Code.

✅ Structure the boilerplate code so that it should have a markdown heading displaying the task title before the cells used in that particular task, along with the code comments in each block. Look at an example below:

widget

✅ Epochs and dataset size: When doing deep learning projects, platform compatibility will be ensured by reducing the number of epochs and the dataset size to reduce training time.  Other parameters, such as the batch size, learning rate, etc., will not be altered. The following conventions will be followed:

  1. From Scratch: The model will be trained on a reduced dataset for a small number of epochs. A trained model will be provided for testing and evaluation purposes. It will be mentioned in a note that the model needs to be trained on a larger dataset and a higher number of epochs to produce usable results.

  2. Transfer Learning: A model that has already been fine-tuned will be provided to the user and will be trained on a reduced dataset for a small number of epochs as a demo. It will then be used for inference and evaluation.

✅ AWS SageMaker credentials: If a project cannot be run without a GPU, AWS SageMaker will be used. Credentials will be either provided, or the free tier will be used. Either way, the project will still use a reduced dataset and a number of epochs to preserve resources and reduce training time.

✅ RAM limitation: For now we have a RAM limitation of 6MB. We are considering increasing the RAM for some projects. However, we cannot provide any assurances regarding when the service will be operational.

✅ Huggingface Integration: Huggingface can be used in projects in the same way GitHub is being used, as it allows core functionality required by NLP projects.

Desktop application projects

Docker Job

✅ Use the “GUI” type docker job for DevOps applications.

✅ Provide the necessary commands in the run script section. A sample run script is as follows:

nohup /usr/local/lib/web/startup.sh >/dev/null 2>&1 && export DISPLAY=:1.0 && useradd -m chromeuser && google-chrome --no-sandbox

✅ Select the “Force Relaunch On Run” option in order to restart the terminal if the learner reloads the browser.

Widget Selection

✅ Select the “Workspace Widget” since we have a terminal in this widget.

✅ Select the “Allow GUI” option.

✅ Select the docker job name from the drop-down button which you have created on the main page.

✅ Select the same widgets, check boxes, and the docker job name for all the tasks to maintain consistency.

Code Creation

✅ Use the terminal tools to debug or configure your application.