Yadaguru Dev Environment Setup
Follow this guide to get a complete local development stack for Yadaguru up-and-running on your machine.
If you are not familiar with Docker, check out their Getting Started guide.
This will allow you to bring up an entire stack at once. See installation instructions here.
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.
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.
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.
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.
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:
-
3005- API -
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 theyadaguru-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
all containers.
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:
docker ps
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
and see 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 admin and
the password password. Once logged in, you should be able to view, create, update, and delete any of the
resources.
yadaguru-api and 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.
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.
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.
If you need assistance you can email us at yadaguru@gmail.com, or hit us up in the
#yadaguru channel in the CodeForPhilly Slack.
Below are some helpful commands for working with Docker.
For any docker-compose commands, be sure to cd into ~/yadaguru/dockerfiles/compose/yada-dev-stack
docker-compose stop
Stop all containers in the stack (but keep them).
docker-compose start
Start all containers in the stack
docker-compose restart
Restart all containers in the stack
docker-compose down
Stop and destroy all containers in the stack. NOTE that this will reset the database to it's original state.
docker ps
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
isn't necessary). bash can be replaced with any command that you would want to run from inside the container.
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.