Skip to content

Latest commit

 

History

History
163 lines (128 loc) · 6.25 KB

SETUP.md

File metadata and controls

163 lines (128 loc) · 6.25 KB
Raw

Diligence Doer Setup Guide

This is a comprehensive setup guide that will allow you to make changes and redeploy seamlessly, enabling you to do things like...

  • Redeploy in seconds
  • Enable / Disable functionalities
  • Contribute to the project and make pull requests!

Following these steps to set up your environment will give you maximum control and flexibility.

Introduction

All instructions assume macOS, that you have Homebrew and git installed, and tries not to assume anything else. Let me know if I overlooked anything or if you run into any troubles getting set up using these instructions.

Project Architecture

Before diving into the specifics, let's take a look at the project architecture...

Diligence Doer Architecture

Prerequisites

Third Party Accounts

We will be using a few third party tools, some of which will require admin privileges.

Infrastructure

  • Amazon Web Services
  • Atlassian Forge

SaaS

  • Jira
  • Github
  • Tableau Server / Tableau Online

Are these services free?

This project can run entirely within free tier AWS service quotas. Atlassian offers a free trial of their Jira software, however, this project is best suited for an enterprise Jira deployment.

Credentials

Following the steps below will give you access to all the credentials that you will need for this project. If you have some of these accounts and are not sure if you have all the credentials, you can view the .env.example for a full list of the credentials you will need.

If you are not familiar with environment variables, hidden files like .env and the Python dotenv package, you can visit this document for a crash course.

Create a copy of the .env.example and name it .env.

You will be replacing the sample values with your credentials and desired variable names as you complete the next steps.

Third Party Setup & Configuration

Atlassian developer account steps...

• Make account or log in

Jira steps...

• Make account or log in

Tableau steps…

Development Environment

1. Clone Repository

  • $ git clone https://github.com/bcrant/diligence-doer.git

2. Python

Install the Python version manager pyenv

  • $ brew install pyenv
  • $ brew install pyenv-virtualenv

Download the Python version used in this project.

  • $ pyenv install 3.8.10
  • $ pyvenv local 3.8.10

Create a virtual environment for this project using that Python version.

  • $ pyenv virtualenv 3.8.10 diligence-doer
  • $ pip install --upgrade pip
  • $ pip install -r requirements-cli.txt

Install the build dependencies to your virtual environment (mainly AWS CLI)

  • $ cd backend && pip install -r ./requirements.txt

3. NodeJS

Install the NodeJS version manager nvm from source...

  • $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

Restart your shell so the path changes take effect...

  • $ exec $SHELL

4. AWS CLI

You will then need to install and configure the AWS CLI with your credentials

  • $ aws configure

5. AWS CDK

  • Make account or log in
  • Look at .env.example to get a preview of the credentials you will be producing
  • The cdk.json file tells the CDK Toolkit how to execute your app.
  • Useful commands:
    • $ npm run build compile typescript to js
    • $ npm run watch watch for changes and compile
    • $ npm run test perform the jest unit tests
    • $ cdk deploy deploy this stack to your default AWS account/region
    • $ cdk diff compare deployed stack with current state
    • $ cdk synth emits the synthesized CloudFormation template

6. Atlassian Forge

Deploying the Project

When making changes to the Jira app's manifest.yml file, you will need to redeploy and reinstall the app to Jira...
$ forge deploy
$ forge install --upgrade

When making changes to the UI of the app as it appears in Jira, which would be done in index.jsx file, you only need to redeploy to Jira...
$ forge deploy

When making changes to AWS Lambda functions, such as any changes to the files in the backend/lambda directory, you will need to redeploy for remote execution...
$ cdk deploy --profile {YOUR_AWS_PROFILE}

Troubleshooting

See the Use Case Specific Caveats section in the README.md file for the majority of troubleshooting issues.

Beyond those caveats, make sure that you set your environment variables as outlined here and at that they are available to the AWS Lambda execution environment.


I hope this guide was helpful! Shoot me a message if you have any questions or would like to learn more.

Cheers,
Brian