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!
Follow the instructions below to set up your local development environment
- Install Git. ( jump to section )
- Fork and clone zubhub repository. ( jump to section )
- Install docker. ( jump to section )
- Install docker-compose. ( jump to section )
- Install Node.js 14 and npm 7 or later. ( jump to section )
- Install make. ( jump to section )
- Setup Backend. ( jump to section )
- Setup Frontend. ( jump to section )
- Tests
- Making changes and Commiting
-
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 withmake --version
andgit --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.
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 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
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.
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.
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
andnpm --version
.
- Click on this link and follow the given instructions to install node and npm on your local machine.
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.
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.
-
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
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.
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.
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.
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
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
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.
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.
- Architecture Overview
- Web Server
- Media Server
- Database and ER Diagram
- Background Tasks
- Reverse-Proxy
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.