Setting up the OpenDSA Development Environment (OpenDSA-DevStack)
NEW Full Instructions:
- Install Docker. It is the only requirement, and it runs on just about every platform.
- Clone this repostory. Download could work too.
- Run the setup for your projects:
docker-compose run setup make <<service>>
- The service name will match the
up
Docker command, listed in the projects table below.
- The service name will match the
- Spin up your service:
docker-compose up <<service>>
- If you are using code-workout and/or opendsa-lti, you should also initialize their databases with:
docker-compose exec opendsa-lti rake db:populate
ordocker-compose exec code-workout rake db:create db:populate
- If you are using code-workout and/or opendsa-lti, you should also initialize their databases with:
- Go to your service's URL
OpenDSA Projects:
Repository | Docker command | Service's URL after up command |
---|---|---|
OpenDSA | docker-compose up opendsa |
https://opendsa.localhost.devcom.vt.edu/ |
OpenDSA-LTI | docker-compose up opendsa-lti |
https://opendsa-lti.localhost.devcom.vt.edu/ |
CodeWorkout | docker-compose up code-workout |
https://code-workout.localhost.devcom.vt.edu/ |
OpenPOP | docker-compose up openpop |
https://openpop.localhost.devcom.vt.edu/ |
Navigating Projects and using Docker:
The docker-compose.yml
file is how docker-compose
manages the many images and containers where your services are running. The Dockerfile
is used by docker
to create the image of a useful machine environment, which can produce containers to do the work.
docker-compose run <<service>> bash
allows you to dive into container and have a shell and command line interface.docker-compose up <<services>>
Begins services in new containers. Meant for tasks that have no 'finish', like a server.docker-compose down
to both stop and remove the containers that were brought up.
docker-compose run <<service>> <<commands>>
starts a new container with a task than has a 'finish'; Some example commands are:python test.py
orbash
- replace
run
withexec
to use a running container instead.
- replace
docker-compose build <<services>>
Builds a new image for services (Note: old containers are not updated)docker images
anddocker container list
displays the images/containers that are currently active. Can add--all
to see inactive ones as well.
Useful tips and options:
- Adding the
--detach
or-d
option allows some docker commands to run in the background, giving you back control of the command line. - Setting a
docker-compose
alias is nice to avoid typing it as much. We recommenddocc=docker-compose
- On Windows, you may want to do
git config --global core.filemode false
. Repositories cloned within Docker can show many changes to the file permissions whengit diff
is used outside of the Docker container. - The
up
command can spin up several services, e.g.:docker-compose up opendsa opendsa-lti code-workout
- There are also two specific profiles set up for common development stacks
docker-compose --profile odsa-cw up
will bring up a stack including OpenDSA-LTI and CodeWorkoutdocker-compose --profile cw-op up
will bring up a stack including CodeWorkout and OpenPOP
- In the
docker-compose.yml
theopendsa-lti
container has a few arguments that you can use to declare which branches of OpenDSA and OpenDSA-LTI you want to use
OLD Installation Steps:
- Install Docker
- Install Make (Make can be found in the default package manager on Linux, in Brew on Mac, and here for Windows. For a Windows installation, you should put the entire folder in Program Files, NOT Program Files (x86). Then, edit your environment variable PATH to add: C:/Program Files/Make/bin. If you don’t know how to edit an environment variable on Windows, google for “windows set environment variable”.)
- Clone this repository
$ cd OpenDSA-DevStack
$ make setup
or$ ./setup.sh
(first time only)
- If you are Windows User: Windows paths are case insensitive, make sure you have both repository cloned and named exactly
opendsa-lti
andopendsa
(remove any spaces or return character).
-
$ make up
or$ docker-compose -f docker-compose.yml up
-
Once you see
RAILS_ENV=development bundle exec thin start --ssl --ssl-key-file server.key --ssl-cert-file server.crt -p 80
in the terminal (this may take a few minutes) -
$ make database
or$ ./db_setup.sh
(first time only and in another terminal) then, the app will be available at:- https://localhost:8443 for OpenDSA-LTI server (note the HTTPS because we are using SSL)
Stop the Containers:
After you finish your work, you need to bring down the Docker containers.
- If you entered the container, exit the terminal by typing
exit
- Change directory to
OpenDSA-DevStack
$ make down
or$ docker-compose -f docker-compose.yml down
Re-run Development Servers:
If you have taken down the containers using $ make down
you can restart them by running $ make up
again or $ make restart
.
Reprovision The Containers:
If anything went wrong, you want to reset your database, or just want to reset the app for any reason, follow these steps.
- Change directory to
OpenDSA-DevStack
$ git pull
$ make nuke
or$ docker-compose down -v
$ make up
Container sudo password:
When running commands in the container, there is not sudo password, (in case you need to execute any commands that require sudo).
Development Workflow:
The provisioning script will clone the OpenDSA and OpenDSA-LTI repositories inside the OpenDSA-DevStack directory. The OpenDSA-DevStack directory is shared between your host machine and the Docker containers, so you can do your development to any of these repositories on your host machine using your preferred tools or IDEs (from "outside" the container environment). All changes that you make will take effect immediately, and you can test them through the virtual machine server URLs provided earlier. You can commit and push your changes from your host machine. However, if you want to compile books in OpenDSA, you have to do that from within the container. Do so as follows:
- Open a new terminal on your host machine
$ cd OpenDSA-DevStack
$ make ssh
or$ docker-compose exec opendsa-lti bash
(you don't need to domake up
if the container is already up and running)$ cd /opendsa
make <<CONFIG_FILE_NAME>>
Keep OpenDSA-DevStack up to date:
Other developers might make changes to any of the repositories cloned by the OpenDSA-DevStack. To keep your local version up to date with the latest version do the following:
- Open a new terminal
- Change directory to
OpenDSA-DevStack
$ make update
or$ ./get_latest.sh
Common Errors
Make sure that you have started Docker before running of the Makefile commands.
If you are on Windows, you may run into issues with line endings. If you do, simply open Git Bash and run $ dos2unix filename
to fix them. This will most likely happen on a script file.
If you are on Windows, you may run into issues with any docker exec
commands (such as make ssh
). To solve them, you may have to start any such command with winpty
.
opendsa
Database Test Data
The initial database population is defined by lib/tasks/sample_data.rake. It uses the factories defined in spec/factories/* to generate entities. If you add new model classes and want to generate test data in the database, please add to the sample_data.rake file so that this population will happen automatically for everyone. The sample_data.rake contains only "sample/try out" data for use during development, and it won't appear on the production server. Initial database contents provided for all new installs, including the production server, is described in db/seeds.rb instead.
-
opendsa
database includes the following admin account:- admin@opendsa.org (pass: adminadmin)
-
opendsa
database also includes the following accounts:- example-1@railstutorial.org (pass: hokiehokie), has instructor access
- example-*@railstutorial.org (pass: hokiehokie) 50 students
It also includes the following other objects:
- Five terms (Spring, Summer I, Summer II, Fall, and Winter 2016),
- one organization (VT)
- one course (CS 1114)
- two offerings of 1114 (one each term)
- one course offering is set up with the admin and instructor as instructors, and all other sample accounts as students
Generate Canvas course using OpenDSA web interface.
- Make sure OpenDSA-DevStack is up to date by following the instructions here.
- After you are done you should have OpenDSA-LTI server running. Go to https://localhost:8443 to make sure your application is up and running.
- Follow the instructions on the instructor's guide page to set up your Canvas course. Note: skip the first step in this guide since you can use the admin account (admin@opendsa.org, pass: adminadmin) to cerate the course.
OLD Production deployment workflow
If you are responsible for maintaining an OpenDSA-LTI production server, follow the instructions in this section to perform deployment to the production server.
Deployment to the production server is initiated from the development environment. It starts with changes you make to OpenDSA-LTI or OpenDSA repositories in OpenDSA-DevStack. First, test these changes locally using OpenDSA-DevStack development servers. Second, commit and push any OpenDSA-LTI and OpenDSA changes. Finally, initiate the production deployment command from within OpenDSA-DevStack. It is important to push your changes before the deployment. Every time you deploy your code, Capistrano will clone the latest version of OpenDSA-LTI, then perform the deployment tasks. One of the tasks gets the latest version of OpenDSA from GitHub as well.
The following steps need to be done only once to generate a pair
of authentication keys.
Note: Do not enter a passphrase, and replace prod_server with
your domain name.
Some installations use both a staging and a production server.
If yours has both, then you will need to do the cat
line for each
one.
Change directory to OpenDSA-DevStack
$ vagrant up
$ vagrant ssh
$ ssh-keygen -t rsa
$ cat .ssh/id_rsa.pub | ssh deploy@prod_server 'cat >> .ssh/authorized_keys'
Enter deploy user password for the last time
Here are the steps that you need to follow every time you want to perform a production deployment:
Change directory to OpenDSA-DevStack
$ vagrant up
$ vagrant ssh
$ cd /vagrant/OpenDSA-LTI
$ git pull any new code
$ commit and push any changes
Execute the following command to deploy to the staging server:
$ bundle exec cap staging deploy
Execute the following command to deploy to the production server:
$ bundle exec cap production deploy
...
$ Please enter a branch (<current_branch>): <Branch to deploy. Leave blank to deploy current_branch>
Connect to Docker Container Database:
During development, it is convenient to connect to the opendsa
database from your host machine using MySQL Workbench. Once you installed MySQL Workbench create a new connection to Vagrant VM Database using the following setup:
- Connection Name: OpenDSA-Devstack
- Connection Method: Standard TCP/IP
- MySQL Hostname: 127.0.0.1
- MySQL Server Port: 3307
- Username: root
- Password: opendsa
Getting Chrome to accept Self Signed SSL for Local Development with Docker
- On the page with the untrusted certificate (
https://
is crossed out in red), click the lock > Certificate Information. - Click the
Details tab > Export
. ChoosePKCS #7, single certificate
as the file format. - Then follow my original instructions to get to the Manage Certificates page. Click the `Authorities tab > Import and choose the file to which you exported the certificate.
- If prompted certification store, choose Trusted Root Certificate Authorities
- Check all boxes and click OK. Restart Chrome.