forked from signmeup/signmeup
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Minor changes to README, and major changes to CONTRIBUTING to fix long-standing errors and make it Cornell-specific.
- Loading branch information
Showing
2 changed files
with
52 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,19 +2,20 @@ | |
|
|
||
| Here's a quick guide to developing SignMeUp and deploying it to production. | ||
|
|
||
| ## Setup | ||
| ## Local Development Setup | ||
|
|
||
| 1. Install the Docker engine on your machine. For Mac or Windows, use the app. | ||
| For Linux, use `docker-toolbox`. | ||
|
|
||
| 2. Clone this repository: | ||
|
|
||
| ```shell | ||
| $ git clone https://github.com/athyuttamre/signmeup.git | ||
| $ git clone https://github.com/etremel/signmeup.git | ||
| ``` | ||
|
|
||
| 3. Generate self-signed certificates for `local.cis-dev.brown.edu` using | ||
| http://selfsignedcertificate.com, and add the two files to the `nginx/ssl` folder. Change the certificate's extension from `.cert` to `.crt`. | ||
| http://selfsignedcertificate.com, and add the two files to the `nginx/ssl` folder. | ||
| Change the certificate's extension from `.cert` to `.crt`. | ||
|
|
||
| 4. In your terminal, run: | ||
|
|
||
|
|
@@ -38,14 +39,14 @@ Here's a quick guide to developing SignMeUp and deploying it to production. | |
| 6. Now we need to fill in various values inside `settings.json`. | ||
|
|
||
| - Replace `INSERT-PASSWORD-HERE` with a good password. | ||
| - Replace `saml.cert` with the IDP cert. You can get this by talking to the | ||
| project coordinator. They will have to notify CIS before giving it to you | ||
| so CIS knows who has this cert. | ||
| - Replace `shibidp` with `shibidp-test` in `saml.entryPoint`. | ||
| - Replace `saml.cert` with the certificate for the test IDP, which is displayed | ||
| at https://shibidp-test.cit.cornell.edu/idp/shibboleth (under the "X509Certificate" tag). | ||
| - Replace `saml.serviceProviderCert` and `saml.decryptionPvk` with a *new* | ||
| certificate/key pair from http://selfsignedcertificate.com. Skip the header | ||
| and footer (The `---BEGIN...` and `---END...` parts). Also remove any newlines | ||
| to make sure the values are in a single line. | ||
| - Replace `appID` and `appSecret` with the correct values from kadira.io. | ||
| - Replace `appID` and `appSecret` with the correct values from kadira.io. (Contact the project maintainer at Cornell to get these). | ||
|
|
||
| 7. Finally, from the `signmeup` directory, run `docker-compose up`. The first | ||
| time will take a long time since it'll pull all the dependent images along | ||
|
|
@@ -69,46 +70,55 @@ If everything went well so far, you should see something like this when running | |
|  | ||
| ## Development | ||
| ### Docker Cleanup | ||
| We follow the [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) method of developing software. | ||
| Every time you restart your Docker containers, Docker will accumulate old | ||
| containers and images on your hard drive. If you restart the app a lot during | ||
| development, this can quickly eat up all your disk space, so you should | ||
| regularly run the `docker-gc.sh` script to delete them. | ||
| [This article](http://blog.yohanliyanage.com/2015/05/docker-clean-up-after-yourself/) | ||
| explains how it works. | ||
| ## Contributions | ||
| This project follows the [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) method of developing software. | ||
| This method has two important axioms: | ||
| - `master` is always ready to deploy. | ||
| - `dev` represents the current version under development. | ||
| - `production` is always ready to deploy. | ||
| - `master` represents the current version under development. | ||
| Never directly push to either of these branches. | ||
| When developing a new feature, or fixing a bug: | ||
| 1. Branch off of `dev` into something like `feature/my-feature-name`. | ||
| 1. Branch off of `master` into something like `feature/my-feature-name`. | ||
| 2. While developing, if you need to pull in changes to `dev` that occurred after | ||
| branching, use `git rebase dev`. | ||
| 2. While developing, if you need to pull in changes to `master` that occurred after | ||
| branching, use `git rebase master`. | ||
| 3. Once finished developing your feature, push to GitHub, and open a pull | ||
| pull request to the `dev` branch. | ||
| pull request to the `master` branch. | ||
| 4. Get feedback from other developers. You can continue pushing commits to the | ||
| branch; these will be automatically reflected in the pull request. | ||
| 5. Once approved, merge into `dev`. Move on to developing something new. | ||
| 5. Once approved, merge into `master`. Move on to developing something new. | ||
| If fixing a bug in production: | ||
| 1. Branch off `master` into something like `hotfix/fix-this-bug`. | ||
| 1. Branch off `production` into something like `hotfix/fix-this-bug`. | ||
| 2. Once ready, push to GitHub, and open two pull requests, one to `master`, and | ||
| one to `dev`. | ||
| one to `production`. | ||
| 3. Once approved, merge both pull requests. | ||
| ## Production | ||
| ## Publishing a new Production Version | ||
| Once you've merged a bunch of features into `dev`, and are ready to deploy to production, follow these steps: | ||
| Once you've merged a bunch of features into `master`, and are ready to deploy to production, follow these steps: | ||
|
|
||
| 1. Create a pull-request from `dev` to `master` branch detailing your changes, | ||
| 1. Create a pull-request from `master` to `production` branch detailing your changes, | ||
| named something like `Release 2.2.3: Add this feature, fix this bug`. | ||
|
|
||
| We version our app in `major.minor.patch` format. Increment the patch number | ||
|
|
@@ -118,34 +128,37 @@ Once you've merged a bunch of features into `dev`, and are ready to deploy to pr | |
| features. | ||
|
|
||
| 2. Once a collaborator has looked through your changes, merge the pull request | ||
| into `master`. | ||
| into `production`. | ||
|
|
||
| 3. Create a new release on GitHub with good release notes. Name the tag and | ||
| release something like `v2.2.3`. | ||
|
|
||
| 3. Now, SSH into your Brown CS account. Then run `kinit`, and enter your | ||
| password. Then type `ssh smu` to log in into the virtual machine. | ||
| ## Deploying in Production | ||
|
|
||
| The Cornell instance of SignMeUp is currently running on an Amazon EC2 server. | ||
| Only users with authorized SSH keys can connect to the server, so if you're | ||
| not an authorized user you'll need to contact someone who is and ask them to | ||
| add your SSH public key as an authorized key. | ||
|
|
||
| 4. `cd` into `/usr/local/docker/signmeup`. | ||
| Assuming you have SSH access to the server, follow these steps to deploy a new version of SignMeUp: | ||
|
|
||
| Because `docker-compose` isn't packaged for Debian yet | ||
| (see [#2235](https://github.com/docker/compose/issues/2235)), we must run it | ||
| in a Python `virtualenv`. Run `source venv/bin/activate` to start the virtual | ||
| environment. Type `docker-compose` to make sure it's available. | ||
| 1. SSH to `[email protected]` and cd into `~/signmeup`. | ||
|
|
||
| To deploy, run `make prod`. | ||
| 2. Ensure that `app/settings.json` has the correct production settings, | ||
| including the production Shibboleth IDP URL, the corresponding production | ||
| IDP certificate, and the production server's self-signed public/private key | ||
| pair under `saml.serviceProviderCert` and `saml.decryptionPvk`. Also ensure | ||
| that `docker-compose.prod.yml` has the correct password embedded for the | ||
| `[email protected]` e-mail account. | ||
| 3. From the `signmeup` directory, run `make prod`. | ||
| This will: | ||
| - Pull the latest release on `master` from GitHub | ||
| - Pull the latest release on `production` from GitHub | ||
| - Load the release version into an environment variable | ||
| - Load `settings.json` into an environment variable | ||
| - Build an image for the new codebase | ||
| - Run it with production settings | ||
| It will not touch the already running `db` and `proxy` containers. For more | ||
| deployment options, check out the `Makefile`. | ||
|
|
||
| ## Docker Tips | ||
|
|
||
| If you accumulate a bunch of containers or images, clean-up with the | ||
| instructions in [this article](http://blog.yohanliyanage.com/2015/05/docker-clean-up-after-yourself/). | ||
| It will not touch the already running `db` and `proxy` containers. For more | ||
| deployment options, check out the `Makefile`. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,7 +11,7 @@ This repository is a fork of [the main SignMeUp repository](https://github.com/s | |
|
|
||
| ## Contributing | ||
|
|
||
| Contributions are welcome from one and all. Please read [CONTRIBUTING.md](CONTRIBUTING.md) to get set up. For questions, please email [email protected]. | ||
| Contributions are welcome from one and all. Please read [CONTRIBUTING.md](CONTRIBUTING.md) to get set up. For questions related to core SignMeUp features, please email [email protected]. For questions related to the Cornell localization of SignMeUp, contact Edward (@etremel). | ||
|
|
||
| ## Credits | ||
|
|
||
|
|
||