improve setup instriuctions (redbrick#201)

* add details on mail setup

* seperate development from production instructions

* add env variables

* formatting

README.md

@@ -1,4 +1,5 @@
 # Static-Site
+
 [![CircleCI](https://circleci.com/gh/redbrick/static-site.svg?style=svg)](https://circleci.com/gh/redbrick/static-site)
 
 A Static Site for [redbrick](http://redbrick.dcu.ie) generated with [hexo](https://hexo.io/) using a theme
@@ -8,52 +9,101 @@ based off [icarus](https://github.com/redbrick/hexo-theme-icarus)
 
 1. **Node** : v6.9(LTS)  Download [Node](https://nodejs.org/download/)
 
-## Setup
-
-To set up run:
-  - `yarn` this will install all the dependencies
-
-You will also need to create three files:
-  - `mailing_list` a newline-separated list of email addresses
-  - `email_update_log` a newline-separated reverse-chronological list of times email updates were sent
-  - `.env` by copying `.env.example` and **modifying values (*important*)**
-
-`mailing_list` and `email_update_log` can be left blank, though updates for every post in history will be sent if no previous send date is specified.
+## Development
 
-## Generate
-- To demo the site run `npm start`. This will create a server that runs on localhost:3000
-- To work on css and have it auto regenerate use `yarn hexo`. This will create a server that runs on localhost:4000
+To set up the for development
 
-## Generate via API
-- While the server is live, a visit to `http://[sitehost]/api/regenerate?token=your_secret_token` will run `hexo generate` and send emails for any new posts so long as that process is not already underway.
+- `yarn` this will install all the dependencies
+- copy `.env.example` to `.env`
+- `yarn start` to create start the serve
 
-## Development
 - To generate new posts
-  - Run `yarn posts [title]` This will create a new post in source/_post/[title].md
+  - Run `yarn posts [title]` This will create a new post in `source/_post/[title].md`
 - To generate new pages:
-  - Run `yarn page [title]` this will create a new page in source/[title]/index.md
+  - Run `yarn page [title]` this will create a new page in `source/[title]/index.md`
 - To edit the sidebar:
-  - Edit themes/redbrick-theme/_config.yaml - this is where all the theme configuration is controlled from.
+  - Edit `themes/redbrick-theme/_config.yaml` - this is where all the theme configuration is controlled from.
+
+### Docker
+
+Theres a `docker-compose.yml` for development.
+
+- Copy `.env.example` to `.env`
+- Run `docker-compose up`
+
+### Generate
+
+- To demo the site run `yarn start`. This will create a server that runs on `localhost:3000`
+- To work on css and have it auto regenerate use `yarn hexo`. This will create a server that runs on `localhost:4000`
 
 ### CSS and Templates
-- You can edit the css for the theme in themes/redbrick-theme/source/css
-- You can edit the templates in themes/redbrick-theme/layout
+
+- You can edit the css for the theme in `themes/redbrick-theme/source/css`
+- You can edit the templates in `themes/redbrick-theme/layout`
 
 ### Google analytics
-Analytics can be enabled by adding your analytics key to theme/redbrick/_config.yaml
 
-## Deployment
+Analytics can be enabled by adding your analytics key to `theme/redbrick/_config.yaml`
+
+## Production
+
+### Setup
+
 To deploy to a server run:
-  - `yarn`
-  - modify _config.yml with mailhost info
-  - `yarn start`
 
-Then using apache or nginx proxy traffic to port 3000. 
-And done. 
-You can create a service to run the server on startup if you want refer to express docs and using a service for this
+- `yarn` this will install all the dependencies
+- modify `_config.yml` as needed
+- copy `production/website.service` to `/etc/systemd/system`
+- `yarn generate` to create initial site
+- `systemctl start website` to start the express server
+
+You will also need to create three files:
+
+- `mailing_list` a newline-separated list of email addresses
+- `email_update_log` a newline-separated reverse-chronological list of times email updates were sent
+- `.env` by copying `.env.example` and **modifying values (*important*)**
+- Set any Environment Variables through the env file
+
+`mailing_list` and `email_update_log` can be left blank, though updates for every post in history
+will be sent if no previous send date is specified.
+
+Then using apache or nginx proxy traffic to port 3000.
+
+And done.
 
 ### Docker
-There is a docker file if you want to generate a container that runs in production mode.
- - To build just run `docker build . -t redbrick/site`
- - Then to start just run `docker run -it --rm -p=3000:3000 -v source:/usr/src/app/source --name redbrick-site redbrick/site`
- - Source volume needs to be specified otherwise it wont have anything to generate Or Just run `docker-compose up`
+
+To use docker in production theres a `docker-compose.yml` in the production folder.
+- Copy the `.env.example` to `.env` relative to the `docker-compose.yml`.
+- Modify `.env`
+- Create a file called `mailing_list` and add email addresses for announce
+- run `docker-compose up -d`
+
+### Generate via API
+- While the server is live, a visit to `http://[sitehost]/api/regenerate?token=your_secret_token`
+  will run `hexo generate` and send emails for any new posts so long as that process is not already underway.
+
+### Mail Options
+
+To use sendmail rather then SMTP in the `_config.yml` set `useSendMail` to `true`.
+
+To disable auth on SMTP leave `auth.user` and `auth.pass` as empty.
+
+Modify the host, and port options as needed for SMTP either in the config or using the env
+variables.
+
+## Environment Variables
+
+| Variable               | Example                    | Description                                                      |
+| :---                   | :---:                      | ---:                                                             |
+| `SECRET_API_TOKEN`     |                            | API key for regenerating the site                                |
+| `RECAPTCHA_SECRET_KEY` |                            | Recaptcha server key from Google                                 |
+| `RECAPTCHA_SITE_KEY`   |                            | Recaptcha site key same as the on in the theme                   |
+| `LOG_ROTATE`           | `24h`                      | When to rotate logs                                              |
+| `SMTP_HOST`            | `mailhost.redbrick.dcu.ie` | SMTP host address                                                |
+| `SMTP_PORT`            | `25`                       | SMTP port for server                                             |
+| `SMTP_SECURE`          | `false`                    | if using SSL or not                                              |
+| `SMTP_USER`            | `no-reply`                 | redbrick username for SMTP auth leave off the `@redbrick.dcu.ie` |
+| `SMTP_PASS`            |                            | account password                                                 |
+| `SMTP_AUTH_METHOD`     | `plain`                    | auth method to use with SMTP. Defaults to plain                  |
+| `PORT`                 | `3000`                     | port to run the server on defaults to 3000                       |

_config.yml

@@ -231,7 +231,6 @@ server:
     port: 25
     secure: false
     authMethod: plain
-    disableAuth: false
     auth:
       user: ''
       pass: ''

docker-compose.yml

@@ -6,6 +6,7 @@ services:
     volumes:
       - $PWD/logs:/usr/src/app/logs
       - $PWD/public:/usr/src/app/public
+      - $PWD/mailing_list:/usr/src/app/public/mailing_list
     ports:
       - '3000:3000'
     env_file: .env

lib/smtpTransport.js

@@ -5,17 +5,13 @@ const yaml       = require('js-yaml');
 const configFile = fs.readFileSync('./_config.yml', 'utf8');
 const config     = yaml.safeLoad(configFile).server;
 
-const smtp  = config.email;
-smtp.host   = process.env.SMTP_HOST   || config.email.host;
-smtp.port   = process.env.SMTP_PORT   || config.email.port;
-smtp.secure = process.env.SMTP_SECURE || config.email.secure;
-if (process.env.SMTP_DISABLE_AUTH     || config.email.disableAuth) {
-  smtp.auth = null;
-} else {
-  smtp.authMethod = process.env.SMTP_AUTH_METHOD || config.email.authMethod;
-  smtp.auth.user  = process.env.SMTP_USER        || config.email.auth.user;
-  smtp.auth.pass  = process.env.SMTP_PASS        || config.email.auth.pass;
-}
+const smtp      = config.email;
+smtp.host       = process.env.SMTP_HOST        || config.email.host;
+smtp.port       = process.env.SMTP_PORT        || config.email.port;
+smtp.secure     = process.env.SMTP_SECURE      || config.email.secure;
+smtp.authMethod = process.env.SMTP_AUTH_METHOD || config.email.authMethod;
+smtp.auth.user  = process.env.SMTP_USER        || config.email.auth.user;
+smtp.auth.pass  = process.env.SMTP_PASS        || config.email.auth.pass;
 
 const smtpTransport = nodemailer.createTransport(smtp);