Intro

ZubHub is an open-source, documentation & collaboration tool for activity-based learning. It is available for custom use for schools, libraries, hackerspaces, educational organizations, etc. Imagine your own online community built around your educational activities! 

Zubhub is designed and developed by Unstructured Studio. We are an educational non-profit organization incorporated in Canada and India. We have our own ZubHub and we use it to expand access to low-cost creative learning opportunities to children and educators. On our ZubHub, children, and educators can get inspired by a collection of activity ideas and projects, learn how to build with the materials and tools that they already have access to, and share their creations with others. Some of the primary features are creator portfolios, community-curated projects, discussion-based collaboration, and workshops. ZubHub takes inspiration from the research conducted on the Build In Progress platform at the MIT Media Lab. 😃

ZubHub is currently in public beta. A public ZubHub instance is hosted here: https://zubhub.unstructured.studio

Want to know more about ZubHub and our feature roadmap? Head to 👉 ZubHub Wiki!

Development Setup

Follow the instructions below to set up your local development environment

Steps

1. Install Git. ( jump to section )
2. Fork and clone zubhub repository. ( jump to section )
3. Install docker. ( jump to section )
4. Install docker-compose. ( jump to section )
5. Install Node.js 14 and npm 7 or later. ( jump to section )
6. Install make. ( jump to section )
7. Setup Backend. ( jump to section )
8. Setup Frontend. ( jump to section )
9. Tests
10. Making changes and Commiting

Windows Specific Setup

• Install Docker and Docker Compose by installing Docker Desktop for Windows.

• Install tools (git, make, cygwin): The easiest way is to use a package manager like Chocolatey. Follow the installation instructions for Windows Powershell (Admin), then run choco install make git cygwin to install all packages. Follow the prompt requests allowing script execution. In the end, verify that packages are available with make --version and git --version, it should return a version for each command. Contributors also reported that installing MozillaBuild automates the installation of a number of these tools. At this point, you need to disable the config core.autocrlf before cloning the zubhub repository, otherwise, all files will use Windows line-endings (CRLF), and docker images will fail to build. To do so, open a Powershell as Admin (right-click on the Start Menu, select Windows Powershell (Admin)), and run:

git config --system --unset core.autocrlf
git config --global core.autocrlf false

You can use git config -l to verify that the value for core.autocrlf is correctly set.

Install Git

NOTE: You can skip this step if you already have git installed on your machine. To check if git is running on your machine, run the following command git --version.

• click on this link, select your operating system from the options given, then download and install git on your local machine.

Fork and clone Zubhub repository

• fork the zubhub repository to your Github account.

• On the homepage of the cloned repository in your own Github account, click on the code button, copy the URL in the dropdown then run the following code in your computer terminal:

      $ git clone <copied url>

The copied URL will have the format of https://github.com/<your github username>/zubhub.git

Install Docker

NOTE: You can skip this step if you already have docker installed on your machine. To check if docker is running on your machine, run the following command docker --version.

• Click on this link, select your operating system from the options given, then download and install docker on your local machine.

Install Docker Compose

NOTE: You can skip this step if you already have docker-compose installed on your machine. To check if docker-compose is running on your machine, run the following command docker-compose --version.

• Click on this link, go through the page and select your operating system from the options given, then follow the given instructions to download and install docker-compose on your local machine.

Install Node and NPM

NOTE: You can skip this step if you already have node and npm installed on your machine. To check if node and npm are already installed on your machine, run the following command node --version and npm --version.

• Click on this link and follow the given instructions to install node and npm on your local machine.

Install Make

NOTE: You can skip this step if you already have make installed on your machine. To check if make is running on your machine, run the following command make --version.

• If you are on a Linux machine, you can install make through this link.
• If you are on a Mac machine, you can google the specific steps of installing make on a mac machine.
• If you are on a Windows machine, you should refer to the Windows Specific Setup section at the beginning of the Developer Setup section.

Setup Backend

NOTE: For windows users, before running the commands below switch to bash (available through WSL), you can achieve that by typing bash to your command line.

• From the root of the repository, run:

       $ cd ./zubhub_backend

• Run:

       $ make init

This will run all the initial setups required and start the server, generate the minimal .env file required to run the backend, spins-up all containers defined in the backend docker-compose file, applies all necessary migrations to the database, and creates a default admin user with username and password of dummy and dummy_password respectively.

In case you're facing issues after running the above, like make: Error, kindly run this before the above command:

       $ docker-compose up

• Run the server:

Subsequently, to start and stop the docker containers, you run the following

To start:

       $ make start

To stop:

• Stop the running container

       $ make stop

• Stop & remove the running container

       $ make down

You can run test by running make test. For other make commands: run make help

Visit http://localhost:8000 on your browser to access the API documentation.

Setup Frontend

• On your terminal/command line, navigate to ./zubhub/zubhub_frontend/zubhub directory

• Create a file named .env in the frontend root folder (same directory with package.json), with the following content

#.env
REACT_APP_NODE_ENV=developement
REACT_APP_BACKEND_DEVELOPMENT_URL=http://127.0.0.1:8000

Using npm

This is advisable for a better development experience.

• Run npm install --legacy-peer-deps to install the dependencies.
• Run npm start to start the frontend.

Using the Docker Container

Use this when you are done with making your changes and you want to test your code on the Docker container.

• Run make start to spin up the frontend container.

Visit localhost:3000 on your browser to access the frontend.

Tests

Before you get started making changes and commiting, you should setup pre-commit on your development machine:

• Run pip install pre-commit
• Run pre-commit --version to verify that pre-commit installation was successful
• Run cd <path to cloned zubhub repository>
• Run pre-commit install to install the git hook scripts

To verify that your setup was successful, run pre-commit in the root of your cloned zubhub repo. You should see this running a number of checks.

Frontend

You can also test the frontend seperately by going to the root of the frontend project (the place you have package.json) and running npm run test -- --coverage --watchAll=false

Backend

To test the backend seperately,

• Run cd ./zubhub_backend
• Run make zubhub-test to run the test suites of the web django app
• Run make media-test to run the test suites of the media django app

Making changes and Commiting

Before making changes, make sure that you've set up pre-commit as described in the previous step. After that just git add . and git commit your changes. pre-commit will automatically run the different tests and will fail to commit until you fix all the errors.

NOTE: If you fail to setup pre-commit on your local machine before making pull requests, our pre-commit action on github will run the same tests on your code and if it fails to pass, your code won't be merged.

Deployment

ZubHub is currently deployed on its main website using Github Actions that act as our build and deployment tooling. If you are interested in deploying Zubhub on your VM for testing and hosting purposes, follow the Single VM Deployment instructions.

API Documentation

• Architecture Overview
• Web Server
• Media Server
• Database and ER Diagram
• Background Tasks
• Reverse-Proxy

Contributions

Contributions are welcome! We suggest you first go through the Contribution Guidelines and Code of Conduct and the Feature Roadmap and Ideas we have been working on. Search the Issues to see there are no duplicates or overlaps before filing new feature requests and bugs.

NOTE: If you are interested in the API documentation instead, you need to follow the instructions above about running the backend on your local machine and afterward visit localhost:8000 on your browser to view the API documentation.