{"id":15789763,"url":"https://github.com/danielgtaylor/polaris","last_synced_at":"2025-03-31T18:27:08.056Z","repository":{"id":14710581,"uuid":"17430965","full_name":"danielgtaylor/polaris","owner":"danielgtaylor","description":"Lightweight backend utilities for static websites","archived":false,"fork":false,"pushed_at":"2017-10-26T23:12:22.000Z","size":16,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-05T22:03:20.441Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielgtaylor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-05T06:59:01.000Z","updated_at":"2018-11-16T20:32:11.000Z","dependencies_parsed_at":"2022-09-21T19:01:01.168Z","dependency_job_id":null,"html_url":"https://github.com/danielgtaylor/polaris","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgtaylor%2Fpolaris","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgtaylor%2Fpolaris/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgtaylor%2Fpolaris/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgtaylor%2Fpolaris/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielgtaylor","download_url":"https://codeload.github.com/danielgtaylor/polaris/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246516862,"owners_count":20790307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-04T22:03:22.158Z","updated_at":"2025-03-31T18:27:08.030Z","avatar_url":"https://github.com/danielgtaylor.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Polaris\n\n[![Build Status](https://travis-ci.org/danielgtaylor/polaris.png?branch=master)](https://travis-ci.org/danielgtaylor/polaris) [![Dependency Status](https://david-dm.org/danielgtaylor/polaris.png)](https://david-dm.org/danielgtaylor/polaris)\n\nLightweight backend utilities for static websites. Currently implements sending email to configured addresses from HTML forms with optional attachments. Feel free to fork and add more features.\n\nPoint your static website toward the north star.\n\n## Installation\nYou can install `polaris` via NPM, the [Node.js](http://nodejs.org/) package manager.\n\n```bash\nsudo npm install -g polaris\n```\n\n## Usage\nTypically you would run Polaris like any other program, with the first argument being an optional configuration file:\n\n```bash\npolaris /path/to/my/config.json\n```\n\nYou can also use Polaris directly from within Node:\n\n```javascript\nvar polaris = require('polaris');\n\npolaris.config.recipients = {\n  test: {\n    to: ['test@gmail.com'],\n    title: 'Test title',\n    allowFiles: false,\n    redirect: 'http://example.com/success'\n  }\n};\n\npolaris.runServer();\n```\n\nIt's also possible to use the Polaris request handler directly via the `http`, `connect`, or `express` modules. This means you can easily add it to an existing application as a new route:\n\n```javascript\nvar express = require('express');\nvar polaris = require('polaris');\n\nvar app = express();\n\napp.post('/email', polaris.handler);\n\napp.listen(3000);\n```\n\n### Sending Emails\nYou can use `curl` to send a test email:\n\n```bash\ncurl -X POST http://localhost:8080/ -d recipient=test -d from=test@gmail.com -d title=Testing -d message=foo\n```\n\nThe same request as an HTML form would look like:\n\n```html\n\u003cform method=\"post\" action=\"http://localhost:8080/\"\u003e\n  \u003cinput type=\"hidden\" name=\"recipient\" value=\"test\"/\u003e\n  \u003cinput type=\"text\" name=\"from\" placeholder=\"Your email\"/\u003e\n  \u003cinput type=\"text\" name=\"title\" placeholder=\"Email title\"/\u003e\n  \u003ctextarea name=\"message\" placeholder=\"Message\"\u003e\u003c/textarea\u003e\n\u003c/form\u003e\n```\n\n### Parameters\nThe following parameters are available. Some are just shortcuts to adding information into the message body.\n\n| Name      | Required | Description                                      |\n| --------- | -------- | ------------------------------------------------ |\n| from      | \u0026#10003; | The sender's email address                       |\n| location  |          | The sender's physical address (adds to message)  |\n| message   | \u0026#10003; | The email body                                   |\n| name      |          | The sender's real name                           |\n| phone     |          | The sender's phone number (adds to message)      |\n| recipient | \u0026#10003; | The recipient name from your `config.json` file. |\n| title     |          | The email title / subject                        |\n\n### Configuration\nPolaris is configured via a simple JSON file. An example looks like:\n\n```json\n{\n  \"listen\": {\n    \"host\": \"localhost\",\n    \"port\": 8080\n  },\n  \"transport\": {\n    \"name\": \"SMTP\",\n    \"options\": {\n      \"host\": \"smtp.mailgun.org\",\n      \"secureConnection\": true,\n      \"port\": 465,\n      \"auth\": {\n        \"user\": \"USERNAME\",\n        \"pass\": \"PASSWORD\"\n      }\n    }\n  },\n  \"recipients\": {\n    \"test\": {\n      \"to\": [\"test@gmail.com\"],\n      \"title\": \"Email subject title\",\n      \"allowFiles\": false,\n      \"redirect\": \"http://example.com/success\"\n    }\n  }\n}\n```\n\n#### Email\n\nThe `transport` options correspond to [Nodemailer](http://www.nodemailer.com/docs/usage-example) `createTransport` arguments. The configuration above is for [MailGun](https://mailgun.com/), but many possible configurations exist. For example, for [Gmail](https://www.gmail.com/):\n\n```json\n...\n\"transport\": {\n  \"name\": \"SMTP\",\n  \"options\": {\n    \"service\": \"Gmail\",\n    \"auth\": {\n      \"user\": \"USERNAME\",\n      \"pass\": \"PASSWORD\"\n    }\n  }\n},\n...\n```\n\n## Deployment\nSome possible deployement scenarios follow.\n\n### Heroku\n[Heroku](https://devcenter.heroku.com/articles/getting-started-with-nodejs) uses git for deployments and supports NPM dependencies. Make sure to install their tools before continuing. Then, create a new project:\n\n```bash\nmkdir server\ncd server\n\nnpm init\nnpm install --save polaris\n```\n\nCreate the following files:\n\n##### main.js\n```javascript\nvar polaris = require('polaris');\n\npolaris.config.recipients = {\n  test: {\n    to: ['test@gmail.com'],\n    title: 'Test title',\n    allowFiles: false,\n    redirect: 'http://example.com/success'\n  }\n};\n\npolaris.runServer();\n```\n\n##### Procfile\n```\nweb: node main.js\n```\n\nThen set up the git repo and push to deploy:\n\n```bash\ngit init\ngit add .\ngit commit -m 'Initial commit'\n\nheroku create\n\ngit push heroku master\n```\n\n### Nodejitsu\n[Nodejitsu](https://www.nodejitsu.com/getting-started/) is a Node.js application hosting provider similar to Heroku. Make sure you have the `jitsu` command installed:\n\n```bash\nsudo npm install -g jitsu\n```\n\nCreate the new project:\n\n```bash\nmkdir server\ncd server\n\nnpm init\nnpm install --save polaris\n```\n\nModify the `package.json` file to have a start script:\n\n```json\n...\n\"scripts\": {\n  \"start\": \"node main.js\"\n}\n...\n```\n\nThen, create the following file:\n\n##### main.js\n```javascript\nvar polaris = require('polaris');\n\npolaris.config.recipients = {\n  test: {\n    to: ['test@gmail.com'],\n    title: 'Test title',\n    allowFiles: false,\n    redirect: 'http://example.com/success'\n  }\n};\n\npolaris.runServer();\n```\n\nLastly, deploy using `jitsu`:\n\n```bash\njitsu deploy\n```\n\n### Digital Ocean / AWS / Rackspace\nCreate a new virtual server using a recent Ubuntu image and do the following:\n\n```bash\nssh user@yoursever\n\n# Install dependencies\nsudo apt-get install nodejs\nsudo npm install -g polaris\n\n# Create a config\nsudo touch /etc/polaris.json\nsudo vim /etc/polaris.json\n\n# Setup the Upstart script\nsudo cp /usr/lib/node_modules/polaris/polaris-upstart.conf /etc/init/polaris.conf\n\nsudo touch /var/log/polaris.log\nsudo chown www-data /var/log/polaris.log\n\n# Start the service\nsudo service polaris start\n```\n\n## Development\nFeel free to fork and create pull requests. You should edit the `main.coffee` file since the `main.js` file is generated from it. Getting the code and building the Javascript is easy:\n\n```bash\ngit clone https://github.com/path/to/your/clone\n\ncd polaris\nnpm run build\n```\n\n## License\nCopyright \u0026copy; 2014 Daniel G. Taylor\n\nhttp://dgt.mit-license.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielgtaylor%2Fpolaris","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielgtaylor%2Fpolaris","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielgtaylor%2Fpolaris/lists"}