Permalink
Browse files

[*] Update READMEs, remove Nylas-specific cloud instructions

  • Loading branch information...
bengotow committed Jul 27, 2017
1 parent 548b17f commit 5b49a298e35a1e6d36ad80d2e17ddc1c2b3e8798
Showing with 110 additions and 98 deletions.
  1. +96 −9 README.md
  2. +1 −0 package.json
  3. +1 −1 packages/client-app/build/tasks/eslint-task.js
  4. +11 −87 packages/cloud-core/README.md
  5. +1 −1 packages/cloud-workers/README.md
105 README.md
@@ -1,6 +1,11 @@
# Nylas Mail
# Nylas Mail - the open-source, extensible mail client
![N1 Screenshot](https://github.com/nylas/nylas-mail-all/raw/cleanup/screenshot/hero_graphic_mac%402x.png)
This is a collection of all components required to run Nylas Mail.
**Nylas Mail is an open-source mail client built on the modern web with [Electron](https://github.com/atom/electron), [React](https://facebook.github.io/react/), and [Flux](https://facebook.github.io/flux/).** It was designed to be easy to extend, and many third-party plugins are available that add functionality to the client. Nylas Mail was initially released and open-sourced in Spring 2015 and was maintained by Nylas until Spring 2017. While Nylas no longer supports Nylas Mail, you can download the latest release or build it from source. There are also [several forks](#forks) that are being actively developed and maintained.
### Exploring the Source
This repository contains the full source code to the Nylas Mail client and it's backend services. It is divided into the following packages:
1. [**Isomorphic Core**](https://github.com/nylas/nylas-mail-all/tree/master/packages/isomorphic-core): Shared code across local client and cloud servers
1. [**Client App**](https://github.com/nylas/nylas-mail-all/tree/master/packages/client-app): The main Electron app for Nylas Mail
@@ -15,24 +20,106 @@ See `/packages` for the separate pieces. Each folder in `/packages` is
designed to be its own stand-alone repository. They are all bundled here
for the ease of source control management.
# Initial Setup for All Local & Cloud Services:
# Getting Started
## New Computer (Mac):
## Setup your Environment (Mac):
1. Install [Homebrew](http://brew.sh/)
1. Install [NVM](https://github.com/creationix/nvm) & Redis `brew install nvm redis`
1. Install Node 6 via NVM: `nvm install 6`
1. `npm install`
## New Computer (Linux - Debian/Ubuntu):
## Setup your Environment (Linux - Debian/Ubuntu):
1. Install Node 6+ via NodeSource (trusted):
1. `curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -`
1. `sudo apt-get install -y nodejs`
1. Install Redis locally `sudo apt-get install -y redis-server redis-tools`
benefit of letting us use subdomains.
1. `npm install`
## Running Nylas Mail
1. `npm run client`: Starts the app
1. `npm run test-client`: Run the tests
1. `npm run lint-client`: Lint the source (ESLint + Coffeelint + LESSLint)
## Digging Deeper
In early 2016, the Nylas Mail team wrote [extensive documentation](https://nylas.github.io/nylas-mail/) for the app that was intended for plugin developers. This documentation lives on GitHub Pages and offers a great overview of the app's architecture and important classes. Here are some good places to get started:
- [Application Architecture](https://nylas.github.io/nylas-mail/guides/Architecture.html)
- [Debugging Nylas Mail](https://nylas.github.io/nylas-mail/guides/Debugging.html)
## Running the Cloud
When you download and build Nylas Mail from source it runs without its cloud components. The concept of a "Nylas ID" / subscription has been removed, and plugins that require server-side processing are disabled by default. (Plugins like Snooze, Send Later, etc.)
In order to use these plugins and get the full Nylas Mail experience, you need to deploy the backend infrastructure located in the `cloud-*` packages. Deploying these services is challenging because they are implemented as microservices and designed to be run at enterprise scale with Redis, Postgres, etc. Because these backend services must access your email account, it is also important to use security best-practices (at the very least, SSL, encryption at rest, and a partitioned VPC). For more information about building and deploying this part of the stack, check out the [cloud-core README](https://github.com/nylas/nylas-mail-all/blob/master/packages/cloud-core/README.md).
## Themes
The Nylas Mail user interface is styled using CSS, which means it's easy to modify and extend. Nylas Mail comes stock with a few beautiful themes, and there are many more which have been built by community developers
<center><img width=550 src="http://i.imgur.com/PWQ7NlY.jpg"></center>
#### Bundled Themes
- [Dark](https://github.com/nylas/nylas-mail/tree/master/internal_packages/ui-dark)
- [Darkside](https://github.com/nylas/nylas-mail/tree/master/internal_packages/ui-darkside) (designed by [Jamie Wilson](https://github.com/jamiewilson))
- [Taiga](https://github.com/nylas/nylas-mail/tree/master/internal_packages/ui-taiga) (designed by [Noah Buscher](https://github.com/noahbuscher))
- [Ubuntu](https://github.com/nylas/nylas-mail/tree/master/internal_packages/ui-ubuntu) (designed by [Ahmed Elhanafy](https://github.com/ahmedlhanafy))
- [Less Is More](https://github.com/nylas/nylas-mail/tree/master/internal_packages/ui-less-is-more) (designed by [Alexander Adkins](https://github.com/P0WW0W))
#### Community Themes
| | | |
| ----- | ----- | ----- |
| [ToogaBooga](https://github.com/brycedorn/N1-ToogaBooga) | [Material](https://github.com/jackiehluo/n1-material) | [Monokai](https://github.com/dcondrey/n1-monokai) |
| [Agapanthus](https://github.com/taniadaniela/n1-agapanthus)—Inbox-inspired theme | [Stripe](https://github.com/oeaeee/n1-stripe)| [Kleinstein] (https://github.com/diklein/Kleinstein)—Hide the account list sidebar|
| [Arc Dark](https://github.com/varlesh/Nylas-Arc-Dark-Theme)| [Solarized Dark](https://github.com/NSHenry/N1-Solarized-Dark) | [Darkish](https://github.com/dyrnade/N1-Darkish)|
| [Predawn](https://github.com/adambmedia/N1-Predawn)| [Ido](https://github.com/edipox/n1-ido)—Polymail-inspired theme|[Berend](https://github.com/Frique/N1-Berend) |
| [ElementaryOS](https://github.com/edipox/elementary-nylas) | [LevelUp](https://github.com/stolinski/level-up-nylas-n1-theme)|[Sunrise](https://github.com/jackiehluo/n1-sunrise) |
| [BoraBora](https://github.com/arimai/N1-BoraBora) | [Honeyduke](https://github.com/arimai/n1-honeyduke)| [Snow](https://github.com/Wattenberger/N1-snow-theme)|
|[Hull](https://github.com/unity/n1-hull)|[Express](https://github.com/oeaeee/n1-express)|[DarkSoda](https://github.com/adambullmer/N1-theme-DarkSoda)|
|[Bemind](https://github.com/bemindinteractive/Bemind-N1-Theme)|[Dracula](https://github.com/dracula/nylas-n1)|[MouseEatsCat](https://github.com/MouseEatsCat/MouseEatsCat-N1)|
|[Sublime Dark](https://github.com/rishabhkesarwani/Nylas-Sublime-Dark-Theme)|[Firefox](https://github.com/darshandsoni/n1-firefox-theme)|[Gmail](https://github.com/dregitsky/n1-gmail-theme)|
#### To install community themes:
1. Download and unzip the repo
2. In Nylas Mail, select `Developer > Install a Package Manually... `
3. Navigate to where you downloaded the theme and select the root folder. The theme is copied into the `~/.nylas-mail` folder for your convinence
5. Select `Change Theme...` from the top level menu, and you'll see the newly installed theme. That's it!
Want to dive in more? Try [creating your own theme](https://github.com/nylas/nylas-mail-theme-starter)!
## Plugins
Some plugins come pre-installed, and are a great starting points for creating your own:
- [Translate](https://github.com/nylas/nylas-mail/tree/master/internal_packages/composer-translate)—Works with 10 languages
- [Quick Replies](https://github.com/nylas/nylas-mail/tree/master/internal_packages/composer-templates)—Send emails faster with templates
- [Emoji Keyboard](https://github.com/nylas/nylas-mail/tree/master/internal_packages/composer-emoji)—Insert emoji by typing a colon (:) followed by the name of an emoji symbol
- [GitHub Sidebar Info](https://github.com/nylas/nylas-mail/tree/master/internal_packages/github-contact-card)
- [View on GitHub](https://github.com/nylas/nylas-mail/tree/master/internal_packages/message-view-on-github)
- [Personal Level Indicators](https://github.com/nylas/nylas-mail/tree/master/internal_packages/personal-level-indicators)
- [Phishing Detection](https://github.com/nylas/nylas-mail/tree/master/internal_packages/phishing-detection)
#### Community Plugins
Note these are not tested or officially supported by Nylas, but we still think they are really cool! If you find bugs with them, please open GitHub issues on their individual project pages, not the Nylas Mail (N1) repo page. Thanks!
| | | |
| ----- | ----- | ----- |
|[Jiffy](http://noahbuscher.github.io/N1-Jiffy/)—Insert animated GIFs|[Weather](https://github.com/jackiehluo/n1-weather)|[Todoist](https://github.com/alexfruehwirth/N1TodoistIntegration)|
|[Unsubscribe](https://github.com/colinking/n1-unsubscribe)|[Squirt Speed Reader](https://github.com/HarleyKwyn/squirt-reader-N1-plugin/)|[Website Launcher](https://github.com/adriangrantdotorg/nylas-n1-background-webpage)—Opens a URL in separate window|
|[Cypher](https://github.com/mbilker/cypher) (PGP Encryption, In Development)|[Avatars](https://github.com/unity/n1-avatars)|[Events Calendar (WIP)](https://github.com/nerdenough/n1-events-calendar)|
|[Mail in Chat (WIP)](https://github.com/yjchen/mail_in_chat)|[Evernote](https://github.com/grobgl/n1-evernote)|[Wunderlist](https://github.com/miguelrs/n1-wunderlist)|
|[Participants Display](https://github.com/kbruccoleri/nylas-participants-display)|[GitHub](https://github.com/ForbesLindesay/N1-GitHub)||
When you install packages, they're moved to ~/.nylas-mail/packages, and Nylas Mail runs apm install on the command line to fetch dependencies listed in the package's package.json
# Forks
# Running Nylas Mail
There are several forks of Nylas Mail that you should check out!
1. `npm install` (Only on fresh install and new packages)
1. `npm run start-client`: Starts Electron app client
1. `npm run start-cloud`: Starts cloud API locally
- [Merra](https://gomerra.com) - Significant rewrite by one of the original authors
- [Nylas Mail Lives](https://github.com/nylas-mail-lives/nylas-mail) - Community effort to fix bugs and improve the client!
@@ -49,6 +49,7 @@
"test-client": "packages/client-app/node_modules/.bin/electron packages/client-app --enable-logging --test",
"test-client-window": "packages/client-app/node_modules/.bin/electron packages/client-app --enable-logging --test=window",
"test-client-junit": "",
"lint-client": "grunt lint --gruntfile=packages/client-app/build/Gruntfile.js --base=./",
"build-client": "grunt build-client --gruntfile=packages/client-app/build/Gruntfile.js --base=./",
"cloud": "pm2 stop all; pm2 delete all; pm2 start packages/cloud-core/pm2-dev.yml --no-daemon",
"cloud-debug": "pm2 stop all; pm2 delete all; pm2 start packages/cloud-core/pm2-debug-cloud-api.yml --no-daemon",
@@ -6,7 +6,7 @@ module.exports = (grunt) => {
eslint: {
options: {
ignore: false,
configFile: 'build/config/eslint.json',
configFile: '../../.eslintrc',
},
target: grunt.config('source:es6'),
},
@@ -21,8 +21,8 @@ infrastructure.
# Getting Started
## New to AWS:
1. Make sure you can login at [https://nylas.signin.aws.amazon.com/console](https://nylas.signin.aws.amazon.com/console). (Ask a Nylas AWS admin to create your username if it doesn't exist already)
1. Make sure you're on **US West (Oregon)**
1. Create an AWS account and sign in
1. Create your AWS IAM Security Credentials
1. Go to Console -> Home -> IAM -> Users -> {{Your Name}} ->
@@ -47,26 +47,6 @@ infrastructure.
1. `brew install awsebcli` on Mac
1. `pip install --upgrade --user awsebcli` on Linux
1. Setup the Elastic Beanstalk CLI to use `n1Cloud` on `us-west-2`.
Note: This uses your AWS IAM Security Credentials you previously setup
to authenticate against Elastic Beanstalk. **You must do this from the
root /nylas-mail-all folder**. It will create a gitignored
`.elasticbeanstalk/` folder when it's done.
1. `eb init`
1. Use region `us-west-2`, application `n1Cloud`
1. Test out the Elastic Beanstalk CLI:
1. `eb logs` OR `eb ssh`
1. NOTE: While `eb ssh` is the easiest, if you want to ssh into a specific
box Get the ec2-user private SSH key. Ask a Nylas teammember for a copy of
the private SSH key. Copy it to your ~/.ssh folder. We currently use a
single master SSH keypair called `k2-keypair` that you can find in the
Console -> EC2 Dashboard -> Network & Security -> Key Pairs.
1. Move to `~/.ssh/`
1. Make read-only: `chmod 400 ~/.ssh/k2-keypair.pem`
1. `ssh -i ~/.ssh/k2-keypair.pem ec2-user@some-ec2-box-we-own.amazonaws.com`
## New to Docker:
1. Read [Understanding Docker](https://docs.docker.com/engine/understanding-docker/)
@@ -75,7 +55,11 @@ infrastructure.
machine.
# Developing the Cloud Components Locally:
From the root /nylas-mail-all directory:
Open `cloud-core/pm2-dev.yml` and replace `XXXXXX` fields with values.
You need to generate a Google Client ID and Secret.
From the root of the nylas-mail repository:
```
npm install
@@ -85,24 +69,20 @@ npm run start-cloud
We use [pm2](http://pm2.keymetrics.io/) to launch a variety of processes
(sync, api, dashboard, processor, etc).
The `npm run start-cloud` command will run `pm2 start
packages/cloud-core/pm2-dev.yml --no-daemon`
The `npm run start-cloud` command will run `pm2 start packages/cloud-core/pm2-dev.yml --no-daemon`
You can see the scripts that are running and their arguments in
`pm2-dev.yml`
You can see the scripts that are running and their arguments in `pm2-dev.yml`
The `pm2-dev.yml` file sets up required environment variables for a dev
environment. The prod environment variables are stored on the (Elastic
Beanstalk AWS Console)[https://nylas.signin.aws.amazon.com/console].
To test to see if the basic API is up go to: `http://lvh.me:5100/ping`.
You should see `pong`.
`lvh.me` is a DNS hack that redirects back to 127.0.0.1 with the added
You should see `pong`. (`lvh.me` is a DNS hack that redirects back to 127.0.0.1.)
## Debugging
From the root of the /nylas-mail-all directory:
From the root of the nylas-mail repository:
```
npm run start-cloud-debug
@@ -118,59 +98,3 @@ the url is
You can either set breakpoints through the inspector, or by putting `debugger;`
statements in your code.
# Deploying
1. Make sure you're in the root of /nylas-mail-cloud, and have alredy run `eb
init`. Verify you're on the right env with `eb list` then:
`./deploy-it <target>`
Woah wtf, did that just do‽ See the [EB CLI](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3.html) as a start.
In a nutshell, this will use `git archive` to package up the repo as a
zip, upload it to the configured EC2 box, look for a `Dockerfile` in the
root, run `docker build` and then `docker run` with a large set of
hard-coded Amazon shell scripts.
Our Dockerfile exposes port 5100, and Elastic Beanstalk automatically maps
whatever single port is exposed to port 80 and serves it.
# Logs:
Don't use `eb logs`. It will download a static 100 lines of the
`eb-activity.log`, which only contains setup logs (no application logs).
1. `eb ssh`
1. `tail -f current` - This will tail and follow the application logs out of
Docker. Use this to see what the app is doing.
1. `tail -f /var/log/eb-activity.log` - This shows you logs from when the
container builds. See this to see the output of `npm install` and other
setup.
# Diagnosing Deploys
Use `eb ssh` to login to the EC2 instance.
To enter the actual docker container, run:
```
source nylasbash
dockerbash
```
The deploys is copied to `/var/app/current`. Note that this is not the
running code. It's the starting place for `docker build` to run from. The
actual running code is within the docker container.
There are 2 common log files to look at:
1. `/var/log/eb-activity.log`. This will show you the progress of our npm
install and other setup piped from the docker container. These are only
the logs to setup the environment and do not contain application logs
2. `/var/log/eb-docker/containers/eb-current-app/{DOCKERVERSION}-stdouterr.log`
is the location of the application logs of the current docker deploy.
The script Elastic Beanstalk runs when deploying your app can be found
here: `/opt/elasticbeanstalk/hooks/appdeploy/enact/00run.sh`
@@ -6,4 +6,4 @@ reliant on the Metadata services exposed by Cloud API.
For details on how to run Cloud Workers, see the
[cloud-core/README.md](https://github.com/nylas/nylas-mail-all/blob/master/packages/cloud-core/README.md)
and run `npm run start-cloud` from the root of nylas-mail-all
and run `npm run start-cloud` from the root of the repository.

0 comments on commit 5b49a29

Please sign in to comment.