From 3b5bbff20f53958725dd4d0d0d1811a2fc1718bc Mon Sep 17 00:00:00 2001 From: Eugene Cheah Date: Fri, 10 Jan 2020 16:46:17 +0000 Subject: [PATCH] README and deployment guide cleanup --- CODE-GUIDE.md | 43 +++++++ DEPLOY-GUIDE-LOCALHOST.md | 97 +++++++++++++++ DEPLOY-GUIDE-SERVERLESS.md | 90 ++++++++++++++ README.md | 247 ++----------------------------------- 4 files changed, 242 insertions(+), 235 deletions(-) create mode 100644 CODE-GUIDE.md create mode 100644 DEPLOY-GUIDE-LOCALHOST.md create mode 100644 DEPLOY-GUIDE-SERVERLESS.md diff --git a/CODE-GUIDE.md b/CODE-GUIDE.md new file mode 100644 index 0000000..1295cde --- /dev/null +++ b/CODE-GUIDE.md @@ -0,0 +1,43 @@ +# Code Guide +If you are interested to developing Inboxkitten, this is a brief guide of how Inboxkitten has been structured. + +## Main Components + - API - that serves as the backbone to connect to MailGun + - UI - the user interface that you see on Inboxkitten that interacts with the API + - CLI - the command line tool that you can use to interact with the API + +### API +Under the `api` folder is where all the code resides for the API component. The API component utilizes `axios` to perform its requests to Mailgun. + +- The configuration settings of the API are all located under `config/` + - `mailgunConfig.js` is the configuration file that contains the keys and domains + - `mailgunConfig.sample.js` is the template that `./config.sh` used to write into `mailgunConfig.js` +- The rest of the code resides in `src/`. + - The main point of entry in an ExpressJS setup is at `app-setup.js`. In this file, + - `mailgunReader.js` contains the underlying code that connects to Mailgun + - the `api` folder will contain the code that performs the validation of the params in the endpoint that the user called before sending over to `mailgunReader.js`. +- The `test` folder contains the mocha test cases to check the `mailgunReader.js`. + +To add any endpoints, it is recommended to create a prototype function in `mailgunReader.js` that performs the execution that connects to Mailgun. Following which, you should create the endpoint that user will be using as a new file under `src/api/` folder for easy maintenance. + +### UI +The UI component code is under `ui` folder. It is constructed using Vue.js for its frontend development and `axios` to perform to requests to API component. + +- The configuration settings of the UI are all located under `config/` + - `apiconfig.js` contains the configuration for connecting to API component as well as the domain to display on the UI. + - `apiconfig.sample.js` is the template used in `./config.sh` for writing into `apiconfig.js` + - The other configuration to be concerned would be the `shareConfig.js` where it is the settings for shareable features such as Twitter's tweeting and GitHub's fork. + - The other files are auto generated files by vue-cli. +- The `src` folder contains the body for UI. It is separated into 3 folders. + - The `assets` will contain the images. + - The `components` will contain the components used in the UI. + - The `router` is an auto generated file but it is used to add subpaths to link to the components. + - The `scss` contains the styling used for Inboxkitten's UI. +- The `dist` folder contains the files built using the `npm run build` command. +- The `uilicious-test` is an uilicious test script that can be ran on [test.uilicious.com](https://test.uilicious.com) to check if your email has been received properly. + +The main entrypoint will be the `App.vue` and by default the Vue router will direct to `landingpage.vue`. + + +### CLI +The CLI is under the `cli` folder. There are only one file that performs the tasks to connect to the API component. It is `inboxkitten.go` under the `src` folder. The `go.sh` script is a custom go script that ensures the environment is within the `cli` folder. \ No newline at end of file diff --git a/DEPLOY-GUIDE-LOCALHOST.md b/DEPLOY-GUIDE-LOCALHOST.md new file mode 100644 index 0000000..6c26cd1 --- /dev/null +++ b/DEPLOY-GUIDE-LOCALHOST.md @@ -0,0 +1,97 @@ +# Developing on localhost / Custom deployment + +Note: You will still need to do the mail gun setup in the firebase guide. + +Instead of running `./config.sh`, you should setup the config files respectively for the deployment. + +## Running the api server + +**Configuring : api/config/mailgunConfig.js** + +``` +module.exports = { + "apiKey" : "", + "emailDomain" : "", + "corsOrigin" : "http://localhost:8000" +} +``` + ++ MAILGUN_API_KEY : Mailgun private api key ++ MAILGUN_EMAIL_DOMAIN : domain for mailgun ++ UI_HOST : Url to the UI domain. `http://localhost:8000` is the default for the UI `npm run dev`, + +**Running the express.js API server** + +``` + # Assuming that you are on the root directory of Inboxkitten + $ cd api + + # Start the server + $ npm start +``` + +Validate your API server is online at `http://localhost:8000/api/v1/mail/list?recipient=hello-world` + +You should see an empty array representing an empty inbox. + +## Running the ui server - in development mode + +**Configuring ui/config/apiconfig.js** +``` +export default { + apiUrl: 'http://localhost:8000/api/v1/mail', + domain: '' +} +``` + ++ apiUrl : Api server to point to, `localhost:8000` is the default for the api server `npm start` ++ MAILGUN_EMAIL_DOMAIN : domain for mailgun + +**Running the nodejs+webpack UI server** + +``` + # Assuming that you are on the root directory of Inboxkitten + $ cd ui + + # If you do not have a http server, you can install one + $ npm run dev +``` + +You can now access it on `http://localhost:8000` and enjoy your kitten-ventures. + +## Running cli + +This is built using the `./build.sh` script + +``` + # Assuming that you are on the root directory of Inboxkitten + $ cd cli + + # You can immediately execute the executable + $ ./bin/inboxkitten + + # Retrieving list of email + $ ./bin/inboxkitten list exampleEmailName + + # Retrieving individual email + $ ./bin/inboxkitten get sw eyJwIjpmYWxzZSwiayI6IjI3YzVkNmZkLTk5ZjQtNGY5MC1iYTM4LThiNDBhNTJmNzA1OCIsInMiOiI0NzFhZjYxYjA4IiwiYyI6InRhbmtiIn0= + + # Target different api endpoint + $ ./bin/inboxkitten -api http://localhost:8000/api/v1 (list|get) [params] +``` +To run without compilation of `inboxkitten.go` in the src/ folder +``` + $ ./go.sh run src/inboxkitten.go +``` + +## Calling the API using curl +If you have your API running on port `8000`, +``` + # Get list of email + $ curl localhost:8000/api/v1/mail/list\?recipient=hard-dust-64 + + # Get individual email + $ curl localhost:8000/api/v1/mail/list\?mailKey=se-eyJwIjpmYWxzZSwiayI6ImVlMWNiMTAzLWZhZjMtNDg3Ni04MjI2LWE1YmE1ZTU3YzMxMiIsInMiOiI3NTdhNTY5ZGFkIiwiYyI6InRhbmtiIn0= +``` + +If you have it hosted on the net, change the endpoint to where you have hosted it on :) \ No newline at end of file diff --git a/DEPLOY-GUIDE-SERVERLESS.md b/DEPLOY-GUIDE-SERVERLESS.md new file mode 100644 index 0000000..142701c --- /dev/null +++ b/DEPLOY-GUIDE-SERVERLESS.md @@ -0,0 +1,90 @@ +# Serverless Deployment Guide + +Follow the 5 steps guide below to get started on Firebase! + +- [Step 0 - Clone Me](#step-0---clone-me) +- [Step 1 - Setup Serverless provider](#step-1---mailgun--firebase-signup) +- [Step 2 - Configuration](#step-2---configuration) +- [Step 3 - Build the package](#step-3---build-the-package) +- [Step 4 - Deployment](#step-4---deployment) + +> Also do let us know how we can help make this better 😺 + +## Step 0 - Clone Me + +``` + $ git clone https://github.com/uilicious/inboxkitten.git +``` + +### Step 1a - Setup Firebase + +1. Go to Firebase and click on `Get Started`. +2. Sign in with your favorite Google account. +3. Click on `Add Project` and create your own firebase inboxkitten project. +4. Remember the project ID + +On your local machine where your InboxKitten is located at, +``` + # Go to the root folder of InboxKitten + $ cd + + # Ensure that firebase CLI tool is installed + $ npm install -g firebase-tools + + # Login to your firebase account + $ firebase login + + # Set your firebase project + $ firebase use --add +``` + +OR + +### Step 1b - Setup Cloudflare Workers + +1. Go to Cloudflare and signup with a domain. +2. Setup cloudflare worker and get an API key +___ + +## Step 2 - Configuration + +In the root directory of Inboxkitten, run the following command +``` + $ ./config.sh +``` + +During the run time of `./config.sh`, there are three environment variables that is being used to set the configuration for your configuration files. + +1. `MAILGUN_EMAIL_DOMAIN` - any custom domain that you owned or the default domain in Mailgun +2. `WEBSITE_DOMAIN` - any custom domain that you owned. If you use your default firebase url, it will be `.firebaseapp.com` +3. `MAILGUN_API_KEY` - retrieve the api key from your Mailgun account + +configuration + +___ + +## Step 3 - Build the package + +``` + $ ./build.sh +``` + +`./build.sh` will package the three components to be ready for deployment. + +___ + +## Step 4 - Deployment + +For API deployment on Firebase: + +``` + # Run the deployment script + $ ./deploy/firebase/deploy.sh +``` + +For API deployment on Cloudflare: + +``` + # Run the deployment script + $ ./deploy/cloudflare/deploy.sh +``` \ No newline at end of file diff --git a/README.md b/README.md index ff3eed9..94d15cc 100755 --- a/README.md +++ b/README.md @@ -10,7 +10,9 @@ Visit [our site](https://inboxkitten.com) to give a spin, or ... # Docker Deployment Guide -Its one simple line - after signing up for mailgun, and getting your api key +Its one simple line - to use our prebuilt docker container. + +Note you will need to [setup your mailgun account first](#setup-mailgun) ``` # PS: you should modify this for your use case @@ -19,11 +21,16 @@ docker run \ -e MAILGUN_API_KEY="" \ -e WEBSITE_DOMAIN="localhost:8000" \ -p 8000:8000 \ - inboxkitten + uilicious/inboxkitten ``` And head over to port 8000 - for your inboxkitten +# Other Deployment Options + +- [Serverless deployment guide (for cloudflare/firebase)](./DEPLOY-GUIDE-SERVERLESS.md) +- [localhost/custom deployment/configuration guide](./DEPLOY-GUIDE-LOCALHOST) + # Support us on product hunt 🚀 + https://www.producthunt.com/posts/inboxkitten @@ -34,31 +41,12 @@ And head over to port 8000 - for your inboxkitten + [What I have learnt from a 14 hours project](https://dev.to/jmtiong/what-i-have-learnt-from-a-14-hours-project-2joo) + [Development timeline](https://blog.uilicious.com/development-timeline-for-inboxkitten-com-lessons-learnt-e802a2f0a47c) -# Firebase Deployment Guide - -## Step 0 - Clone Me - -Follow the 5 steps guide below to get started on Firebase! - -- [Step 0 - Clone Me](#step-0---clone-me) -- [Step 1 - Mailgun & Firebase signup](#step-1---mailgun--firebase-signup) -- [Step 2 - Configuration](#step-2---configuration) -- [Step 3 - Build the package](#step-3---build-the-package) -- [Step 4 - Deployment](#step-4---deployment) - -For other deployment options, refer to the following guide. - -- [localhost/custom manual configuration guide](#developing-on-localhost--custom-deployment) - -> Also do let us know how we can help make this better 😺 - -``` - $ git clone https://github.com/uilicious/inboxkitten.git -``` +# Other References +- [Coding Guide](./CODE-GUIDE.md) ___ -## Step 1 - Mailgun & Firebase signup +## Setup Mailgun ### Mailgun To sign up for a Mailgun account, go to the signup page. @@ -89,214 +77,3 @@ Or you can go to the security settings and locate the API key there. Mailgun API key ___ - -### Firebase Deployment - -1. Go to Firebase and click on `Get Started`. -2. Sign in with your favorite Google account. -3. Click on `Add Project` and create your own firebase inboxkitten project. -4. Remember the project ID - -On your local machine where your InboxKitten is located at, -``` - # Go to the root folder of InboxKitten - $ cd - - # Ensure that firebase CLI tool is installed - $ npm install -g firebase-tools - - # Login to your firebase account - $ firebase login - - # Set your firebase project - $ firebase use --add -``` - -___ - -## Step 2 - Configuration - -In the root directory of Inboxkitten, run the following command -``` - $ ./config.sh -``` - -During the run time of `./config.sh`, there are three environment variables that is being used to set the configuration for your configuration files. - -1. `MAILGUN_EMAIL_DOMAIN` - any custom domain that you owned or the default domain in Mailgun -2. `WEBSITE_DOMAIN` - any custom domain that you owned. If you use your default firebase url, it will be `.firebaseapp.com` -3. `MAILGUN_API_KEY` - retrieve the api key from your Mailgun account - -configuration - -___ - -## Step 3 - Build the package - -``` - $ ./build.sh -``` - -`./build.sh` will package the three components to be ready for deployment. - -___ - -## Step 4 - Deployment - -For API deployment on Firebase: - -``` - # Run the deployment script - $ ./deploy/firebase/deploy.sh -``` - -For API deployment on Cloudflare: - -``` - # Run the deployment script - $ ./deploy/cloudflare/deploy.sh -``` - ---- - -# Developing on localhost / Custom deployment - -Note: You will still need to do the mail gun setup in the firebase guide. - -Instead of running `./config.sh`, you should setup the config files respectively for the deployment. - -## Running the api server - -**Configuring : api/config/mailgunConfig.js** - -``` -module.exports = { - "apiKey" : "", - "emailDomain" : "", - "corsOrigin" : "http://localhost:8000" -} -``` - -+ MAILGUN_API_KEY : Mailgun private api key -+ MAILGUN_EMAIL_DOMAIN : domain for mailgun -+ UI_HOST : Url to the UI domain. `http://localhost:8000` is the default for the UI `npm run dev`, - -**Running the express.js API server** - -``` - # Assuming that you are on the root directory of Inboxkitten - $ cd api - - # Start the server - $ npm start -``` - -Validate your API server is online at `http://localhost:8800/api/v1/mail/list?recipient=hello-world` - -You should see an empty array representing an empty inbox. - -## Running the ui server - in development mode - -**Configuring ui/config/apiconfig.js** -``` -export default { - apiUrl: 'http://localhost:8800/api/v1/mail', - domain: '' -} -``` - -+ apiUrl : Api server to point to, `localhost:8800` is the default for the api server `npm start` -+ MAILGUN_EMAIL_DOMAIN : domain for mailgun - -**Running the nodejs+webpack UI server** - -``` - # Assuming that you are on the root directory of Inboxkitten - $ cd ui - - # If you do not have a http server, you can install one - $ npm run dev -``` - -You can now access it on `http://localhost:8000` and enjoy your kitten-ventures. - -## Running cli - -This is built using the `./build.sh` script - -``` - # Assuming that you are on the root directory of Inboxkitten - $ cd cli - - # You can immediately execute the executable - $ ./bin/inboxkitten - - # Retrieving list of email - $ ./bin/inboxkitten list exampleEmailName - - # Retrieving individual email - $ ./bin/inboxkitten get sw eyJwIjpmYWxzZSwiayI6IjI3YzVkNmZkLTk5ZjQtNGY5MC1iYTM4LThiNDBhNTJmNzA1OCIsInMiOiI0NzFhZjYxYjA4IiwiYyI6InRhbmtiIn0= - - # Target different api endpoint - $ ./bin/inboxkitten -api http://localhost:8800/api/v1 (list|get) [params] -``` -To run without compilation of `inboxkitten.go` in the src/ folder -``` - $ ./go.sh run src/inboxkitten.go -``` - -## Calling the API using curl -If you have your API running on port `8800`, -``` - # Get list of email - $ curl localhost:8800/api/v1/mail/list\?recipient=hard-dust-64 - - # Get individual email - $ curl localhost:8800/api/v1/mail/list\?mailKey=se-eyJwIjpmYWxzZSwiayI6ImVlMWNiMTAzLWZhZjMtNDg3Ni04MjI2LWE1YmE1ZTU3YzMxMiIsInMiOiI3NTdhNTY5ZGFkIiwiYyI6InRhbmtiIn0= -``` - -If you have it hosted on the net, change the endpoint to where you have hosted it on :) - -# Code Guide -If you are interested to developing Inboxkitten, this is a brief guide of how Inboxkitten has been structured. - -## Main Components - - API - that serves as the backbone to connect to MailGun - - UI - the user interface that you see on Inboxkitten that interacts with the API - - CLI - the command line tool that you can use to interact with the API - -### API -Under the `api` folder is where all the code resides for the API component. The API component utilizes `axios` to perform its requests to Mailgun. - -- The configuration settings of the API are all located under `config/` - - `mailgunConfig.js` is the configuration file that contains the keys and domains - - `mailgunConfig.sample.js` is the template that `./config.sh` used to write into `mailgunConfig.js` -- The rest of the code resides in `src/`. - - The main point of entry in an ExpressJS setup is at `app-setup.js`. In this file, - - `mailgunReader.js` contains the underlying code that connects to Mailgun - - the `api` folder will contain the code that performs the validation of the params in the endpoint that the user called before sending over to `mailgunReader.js`. -- The `test` folder contains the mocha test cases to check the `mailgunReader.js`. - -To add any endpoints, it is recommended to create a prototype function in `mailgunReader.js` that performs the execution that connects to Mailgun. Following which, you should create the endpoint that user will be using as a new file under `src/api/` folder for easy maintenance. - -### UI -The UI component code is under `ui` folder. It is constructed using Vue.js for its frontend development and `axios` to perform to requests to API component. - -- The configuration settings of the UI are all located under `config/` - - `apiconfig.js` contains the configuration for connecting to API component as well as the domain to display on the UI. - - `apiconfig.sample.js` is the template used in `./config.sh` for writing into `apiconfig.js` - - The other configuration to be concerned would be the `shareConfig.js` where it is the settings for shareable features such as Twitter's tweeting and GitHub's fork. - - The other files are auto generated files by vue-cli. -- The `src` folder contains the body for UI. It is separated into 3 folders. - - The `assets` will contain the images. - - The `components` will contain the components used in the UI. - - The `router` is an auto generated file but it is used to add subpaths to link to the components. - - The `scss` contains the styling used for Inboxkitten's UI. -- The `dist` folder contains the files built using the `npm run build` command. -- The `uilicious-test` is an uilicious test script that can be ran on [test.uilicious.com](https://test.uilicious.com) to check if your email has been received properly. - -The main entrypoint will be the `App.vue` and by default the Vue router will direct to `landingpage.vue`. - - -### CLI -The CLI is under the `cli` folder. There are only one file that performs the tasks to connect to the API component. It is `inboxkitten.go` under the `src` folder. The `go.sh` script is a custom go script that ensures the environment is within the `cli` folder. \ No newline at end of file