Quickstart guide

Initial setup

To make sure that we use SSL for our development environment, we use the hostname swapr-dev.vip.gatech.edu to access the development enviornment. This hostname doesn't actually resolve to anything on Georgia Tech's DNS, so we'll need to add is to your host system's local DNS resolver manually.

See Rackspace's article on how to modify your hosts file. Add the following entry to your hosts file:

127.0.0.1 swapr-dev.vip.gatech.edu

You should now be able to run ping swapr-dev.vip.gatech.edu to see it resolving to 127.0.0.1.

You'll then need to download the self-signed development SSL certificate to add it to your operating system's trust store: Download certificate (right click and save as)

Then, to add it to your operating system's trust store so you don't get SSL warnings in your browser. If you're unfamiliar with the process, follow the guide below for your operating system. Only the macOS guide has been tested, so create an issue in the provisioning repository if that's the case.

• Windows
• macOS
• Linux: could be managed by your browser or your distro, look up how to trust self-signed certificates for your particular distro and browser.

Getting started

To provision a local copy of the SWAPR development environment, first ensure that you have the following dependencies:

• Docker

Next, run the following commands to clone the repository and build the environment.

git clone --recursive [email protected]:GatechVIP/gatech-swapr-provisioning.git
docker-compose up --build

The --recursive flag on our clone command automatically pulls the two git submodules for the backend and frontend from their separate repositories on GitHub. If you're unfamiliar with git submodules, here are some implications to keep in mind:

• The backend and frontend repositories are totally separate and have their own history.
• Git submodules in the provisioning repo (this one) are pinned to a particular commit hash for each submodule. This means that after committing and pushing changes in a submodule, you need to git add <name of submodule directory> and commit that change to the provisioning repo for the provisioning repo to have the correct references to the latest version of that part of the codebase.
• All git submodules can be automatically updated to their newest versions by running git submodule update --remote.

When docker-compose up --build executes, it will build the server container and update it to the latest version, as well as run the PostgreSQL container and the nginx container. The client source watcher container will also start. All of the output will stay in the same console.

Alternatively, you can run the environment as a daemon in the background, if you don't need to view the logs, using docker-compose up -d --build. To stop the environment, run docker-compose down.

After starting the evnironment on your host machine, port 8443 on your host should point to the nginx service which should be serving the most recent build of the client code from the client-watch container. Live-reloading should also work, so when you change any code, your web browser will refresh to update. However, make sure to restart the stack whenever any node dependencies are added to package.json.

Access the development server via your browser to make sure it is working. Some details about the development server:

• Accessible from your host machine at https://swapr-dev.vip.gatech.edu:8443/
• API root is https://swapr-dev.vip.gatech.edu:8443/api/
• Login route is proxied to the backend at https://swapr-dev.vip.gatech.edu:8443/login/
• We need to use a .gatech.edu local dev domain or we can't test CAS login. We work around this by using the faked domain name of swapr-dev.vip.gatech.edu.
• The backend will automatically reload itself when changes to the code are made.
• The frontend will refresh your web browser when changes are made.

From here, just make sure to use the copies of the client and server code that are found as submodules of this repo. Whenever there is an update to one of the submodules, just make sure to run git submodule update in the provisioning repo.

Running the test suite

A good first step is running the test suite to make sure that the results match up with other team members. You can do so by running docker-compose -f docker-compose.test.yaml run test.

Next steps

Now, you have a local copy of our stack that should be running! Check out these other pages for further steps:

• Interacting with the stack

Troubleshooting

• Sometimes, our stack fails to start on the first run due to the database being initialized. If you encounter this issue, try stopping and starting the stack again.