Skip to content

Latest commit

 

History

History
212 lines (131 loc) · 9.7 KB

README.md

File metadata and controls

212 lines (131 loc) · 9.7 KB
Raw

CI/CD

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!

screenshot

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 )


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

  • 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:

       $ make stop or 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

  • Create a file named .env in the frontend root folder (same directory with package.json)
  • Copy the content of .env.example and paste into the new .env file.
  • On your terminal/command line, navigate to ./zubhub/zubhub_frontend/zubhub directory

Using npm

This is advisable for a better development experience.

  • Run npm install 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.



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



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.