Yadaguru Dev Environment Setup
Follow this guide to get a complete local development stack for Yadaguru up-and-running on your machine.
Step 1 - Install Docker
If you are not familiar with Docker, check out their Getting Started guide.
Step 2 - Install Docker Compose
This will allow you to bring up an entire stack at once. See installation instructions here.
Step 3 - Install NodeJS
While NodeJS will automatically be setup in the yadaguru/api container, it will still need to be setup on the host machine in order to use NPM.
See installation instructions here.
Step 4 - Install Build Tools
In the terminal, run the following commands to globally install the necessary build tools:
npm install -g gulp npm install -g bower npm install -g karma npm install -g mocha npm install -g sequelize-cli
This will install the gulp task runner, the bower package manager, karma for running front-end tests, and mocha for running back-end tests.
Step 5 - Pull down the repos
Pull all of the Yadaguru repos into a folder called
yadaguru in your home folder.
mkdir ~/yadaguru cd ~/yadaguru git clone https://github.com/yadaguru/dockerfiles.git git clone https://github.com/yadaguru/yadaguru-api.git git clone https://github.com/yadaguru/yadaguru-app.git git clone https://github.com/yadaguru/yadaguru-admin.git
Below is a summary of the repos:
- https://github.com/yadaguru/dockerfiles - contains all of the Dockerfiles and docker-compose files for building Yadaguru images.
- https://github.com/yadaguru/yadaguru-api - the NodeJS REST API for all YadaGuru services.
- https://github.com/yadaguru/yadaguru-app - the user-facing AngularJS app.
- https://github.com/yadaguru/yadaguru-admin - the internal-facing admin portal for managing Yadaguru content.
Step 6 - Configure the repos
cd ~/yadaguru/yadaguru-api npm install
This will install all dependencies for the API.
cd ~/yadaguru/yadaguru-app npm install bower install gulp build
This will install all development and app dependencies, and build the js/css assets. NOTE: bower may ask you to resolve version conflicts for some packages. If this occurs, refer to the bower.json file for the correct version.
cd ~/yadaguru/yadaguru-admin npm install
This will install all development and app dependencies. For this project,
npm install will also run
bower install when finished. NOTE: bower may ask you to resolve version conflicts for some packages. If this
occurs, refer to the bower.json file for the correct version.
Step 7 - docker-compose up
This will bring up the entire Yadaguru development stack. IMPORTANT NOTE: This guide assumes that all repos will reside in a folder called
yadaguru in your home folder. If you place the repos elsewhere, you will need to modify the docker-compose.yml file in the
dockerfiles repo to mount the volumes to the appropriate location.
cd ~/yadaguru/dockerfiles/compose/yada-dev-stack docker-compose up -d
This command will do the following:
- Pull down the all necessary images from Yadaguru's Docker Hub.
- Expose the following ports:
5858- API remote debugging
3000- front-end app
9000- admin portal
5432- Postgres DB
- Create a data volume link between the repos on the host machine and the containers.
- Run the API with
nodemon, so that any changes in the
yadaguru-apirepo will cause the app to restart.
Note that the
-d flag will run the containers in 'detached mode' (see Docker Tips below for more information).
You can omit the
-d flag, and this will cause all containers to output to the console. Hit CTRL+C to stop
Even after the containers have been started, it may take some time for them to complete their entrypoint scripts. You can check on the status of a container by doing the following:
This will show you all of the containers that are running. Note the name of the container in the last column.
docker logs -f <container-name>
This will tail the stdout of the container. You will know that the stack is ready if you tail the api container
Starting http server on port: 3005.
##Step 8 - Run Migrations
Go to the API repo and run the DB migration script.
cd ~/yadaguru/yadaguru-api npm run migrations
This will update the database schema with recent changes.
##Step 9 - Verify
The Yadaguru development stack should be ready; let's verify this.
Browsing to localhost:3000 you should see the Yadaguru app. You should be able to create a new account and add school(s).
Browing to localhost:9000 you should get the admin login screen. You can login with the username
password. Once logged in, you should be able to view, create, update, and delete any of the
Step 10 - Test
yadaguru-admin both have test suites. You can further verify that everything is working
by running the tests.
cd ~/yadaguru/yadaguru-admin npm test
to test the admin portal.
cd ~/yadaguru/yadaguru-api npm test
to test the API.
Step 11 - Create an account and login.
In order to work on the app, you will need to create an account on your local dev setup. To do this, follow the onboarding process in
yadaguru-app. Any 10 digit number will work for the phone number. The generated confirmation code will be outputted to the Chrome dev tools console. Once you create an account, add a test school (and set a date at least 90 days from now).
If you need to start fresh with a new account, click on the speech bubble icon and, and then select "Forget my phone number." This will delete your user, schools, and reminders from the database, as well as clear the local storage keys holding your access token and onboarding state.
Step 12 - Code!
Congratulations! You now have your own personal Yadaguru running on your computer. We need lots of development help. Check out our waffle.io board to see where you can help.
Please create a feature branch off of master, and make a pull request when your feature is ready.
Below are some helpful commands for working with Docker.
docker-compose commands, be sure to
Stop all containers in the stack (but keep them).
Start all containers in the stack
Restart all containers in the stack
Stop and destroy all containers in the stack. NOTE that this will reset the database to it's original state.
See all of the runnning containers. Adding
--all will show running and stopped containers. The last column is
the name of the container (this is auto-generated by docker-compose).
docker logs -f <container-name>
Tail the stdout of a container
docker exec -ti <container-name> bash
Start bash in the container. Use this if you want to perform operations from within the container (this usually
bash can be replaced with any command that you would want to run from inside the container.
Connecting to the Database
Postgres is exposed on port 5432, if you need to connect directly to the database.
psql -h localhost -p 5432 -d yadaguru -U yadaguru --password
and enter the password
yadaguru. NOTE that you will need to have psql installed on your host machine.
See installation instructions here.