|
43 | 43 | * [Install](#install) |
44 | 44 | * [Usage](#usage) |
45 | 45 | * [Continuous Integration and Code Coverage](#continuous-integration-and-code-coverage) |
| 46 | + * [Configuration](#configuration) |
46 | 47 | * [Tutorials](#tutorials) |
47 | 48 | * [Community](#community) |
48 | 49 | * [Related](#related) |
@@ -451,6 +452,113 @@ Here are the simple steps required to setup [SemaphoreCI][] with [Codecov][]: |
451 | 452 | 7. Run a test build ("Rebuild last revision") on SemaphoreCI and check to make sure your code coverage report uploads properly on Codecov |
452 | 453 | 8. Ensure your `README.md` file has the build status and code coverage badges rendered properly (you will need to use a different badge link from each provider if your GitHub repository is private) |
453 | 454 |
|
| 455 | +### Configuration |
| 456 | + |
| 457 | +#### Environment Variables |
| 458 | + |
| 459 | +We have made configuration of your Lad project easy through a [dotenv][] configuration, per [Twelve-Factor][twelve-factor]. |
| 460 | + |
| 461 | +We use the following three packages to manage configuration: |
| 462 | + |
| 463 | +* [dotenv-extended][] - allows us to craft a `.env` definition (otherwise known as a "schema") in a file named `.env.schema` |
| 464 | +* [dotenv-mustache][] - allows us to use the [Mustache templating language][mustache] in our `.env` and `.env.defaults` confguration files |
| 465 | +* [dotenv-parse-variables][] - automatically parses variable types from `process.env` (e.g. `FOO=4` will set `process.env.FOO = 4` with a `Number` variable type instead of a `String`) |
| 466 | + |
| 467 | +Configuration is managed by the following, in order of priority: |
| 468 | + |
| 469 | +1. Contents of the file at `config/index.js` (reads in `process.env` environment variables) |
| 470 | +2. Contents of the files in directories under `config/environments/` (sets defaults per environment, e.g. you can pass `NODE_ENV=staging` and it will load the file at `config/environments/staging.js`) |
| 471 | +3. Environment variables used to override defaults or set required ones (e.g. `NODE_ENV=production`) |
| 472 | +4. Environment configuration in `.env` |
| 473 | +5. Environment configuration in `.env.defaults` |
| 474 | + |
| 475 | +Precedence is taken by the environment configuration files, environment variables, then the `.env` file. |
| 476 | + |
| 477 | +Basically [dotenv][] won't set an environment variable if it already detects it was passed as an environment variable. |
| 478 | +
|
| 479 | +Take a look at the [config](template/config) folder contents and also at the defaults at [.env.defaults](template/.env.defaults). |
| 480 | +
|
| 481 | +#### Outbound Email Configuration |
| 482 | +
|
| 483 | +> By default in the development environment we simply render the email in your browser. |
| 484 | +
|
| 485 | +However in other environments such as production, you definitely want emails to be sent. |
| 486 | +
|
| 487 | +We built-in support for Postmark by default (though you can swap in your own `transport` provider in the `jobs/email.js` file): |
| 488 | +
|
| 489 | +1. Go to [https://postmarkapp.com](https://postmarkapp.com?utm_source=lad) – Start Free Trial |
| 490 | +2. Create a free trial account, then click Get Started, and proceed to create a "Server" and "Sender Signature" |
| 491 | +3. Copy/paste the "Server API token" under "Credentials" in your `.env` file (example below) |
| 492 | +
|
| 493 | + ```diff |
| 494 | + -POSTMARK_API_TOKEN= |
| 495 | + +POSTMARK_API_TOKEN=ac6657eb-2732-4cfd-915b-912b1b10beb1 |
| 496 | + ``` |
| 497 | +
|
| 498 | +4. Modify the `SEND_EMAIL` variable in `.env` from `false` to `true` |
| 499 | +
|
| 500 | +#### Favicon and Touch Icon Configuration |
| 501 | +
|
| 502 | +You can customize the favicon and touch icons – just generate a new set at <https://realfavicongenerator.net> and overwrite the existing in the [assets](template/assets) folder. |
| 503 | +
|
| 504 | +Just make sure that any relative paths match up in the `assets/browserconfig.xml` and `assets/manifest.json` files. |
| 505 | +
|
| 506 | +#### Authentication Methods |
| 507 | +
|
| 508 | +##### Google Auth |
| 509 | +
|
| 510 | +> In order to add Google sign-in to your app (so users can log in with their Google account): |
| 511 | +
|
| 512 | +1. Go to <https://console.developers.google.com> – Create a project (and fill out your project information – if you need a 120x120px default image, [you can use this one](media/lad-120x120.png) |
| 513 | +2. Under your newly created project, go to Credentials – Create credentials – OAuth client ID – Web application |
| 514 | +3. Set "Authorized JavaScript origins" to `http://yourdomain.com` (replace with your domain) and also `http://localhost:3000` (for local development) |
| 515 | +4. Set "Authorized redirect URIs" to `http://yourdomain.com/auth/google/ok` (again, replace with your domain) and also `http://localhost:3000/auth/google/ok` (again, for local development) |
| 516 | +5. Copy and paste the newly created key pair for respective properties in your `.env` file (example below) |
| 517 | +
|
| 518 | + ```diff |
| 519 | + -GOOGLE_CLIENT_ID= |
| 520 | + +GOOGLE_CLIENT_ID=424623312719-73vn8vb4tmh8nht96q7vdbn3mc9pd63a.apps.googleusercontent.com |
| 521 | + -GOOGLE_CLIENT_SECRET= |
| 522 | + +GOOGLE_CLIENT_SECRET=Oys6WrHleTOksqXTbEY_yi07 |
| 523 | + ``` |
| 524 | +
|
| 525 | +6. In `config/index.js`, make sure that `AUTH_GOOGLE_ENABLED=true` to enable this authentication method. |
| 526 | +
|
| 527 | +#### Amazon S3 and CloudFront Asset Setup |
| 528 | +
|
| 529 | +> In order for your assets to get properly served in a production environment, you'll need to configure AWS: |
| 530 | + |
| 531 | +1. Go to <https://console.aws.amazon.com/iam/home#security_credential> ‐ Access Keys – Create New Access Key |
| 532 | +2. Copy and paste the newly created key pair for respective properties in your `.env` file (example below) |
| 533 | + |
| 534 | + ```diff |
| 535 | + -AWS_IAM_KEY= |
| 536 | + +AWS_IAM_KEY=AKIAJMH22P6W674YFC7Q |
| 537 | + -AWS_IAM_SECRET= |
| 538 | + +AWS_IAM_SECRET=9MpR1FOXwPEtPlrlU5WbHjnz2KDcKWSUcB+C5CpS |
| 539 | + ``` |
| 540 | + |
| 541 | +3. Enable your API by clicking on Overview and then clicking the Enable button |
| 542 | +4. Go to <https://console.aws.amazon.com/s3/home> – Create Bucket |
| 543 | +5. Create a bucket and copy/paste its name for the property in `.env` (example below) |
| 544 | + |
| 545 | + ```diff |
| 546 | + -AWS_S3_BUCKET= |
| 547 | + +AWS_S3_BUCKET=lad-development |
| 548 | + ``` |
| 549 | + |
| 550 | +6. Go to <https://console.aws.amazon.com/cloudfront/home> – Create Distribution – Get Started |
| 551 | +7. Set "Origin Domain Name" equal to your S3 bucket name (their autocomplete drop-down will help you find it) |
| 552 | +8. Leave the remaining defaults as is (some fields might be blank, this is OK) |
| 553 | +9. Copy/paste the newly created Distribution ID and Domain Name for respective properties in your `.env` file (example below) |
| 554 | + |
| 555 | + ```diff |
| 556 | + -AWS_CF_DI= |
| 557 | + +AWS_CF_DI=E2IBEULE9QOPVE |
| 558 | + -AWS_CF_DOMAIN= |
| 559 | + +AWS_CF_DOMAIN=d36aditw73gdrz.cloudfront.net |
| 560 | + ``` |
| 561 | + |
454 | 562 | ### Tutorials |
455 | 563 |
|
456 | 564 | * [Writing Your App](https://github.com/koajs/koa#getting-started) |
@@ -490,7 +598,7 @@ If you are seeking permission to use these trademarks, then please [contact us]( |
490 | 598 | [MIT](LICENSE) © [Nick Baugh](http://niftylettuce.com) |
491 | 599 |
|
492 | 600 |
|
493 | | -## |
| 601 | +## |
494 | 602 |
|
495 | 603 | <a href="#"><img src="media/lad-footer.png" alt="#" /></a> |
496 | 604 |
|
@@ -567,3 +675,13 @@ If you are seeking permission to use these trademarks, then please [contact us]( |
567 | 675 | [nodemailer]: https://nodemailer.com/ |
568 | 676 |
|
569 | 677 | [email-templates]: https://github.com/niftylettuce/node-email-templates |
| 678 | +
|
| 679 | +[mustache]: https://github.com/janl/mustache.js/ |
| 680 | +
|
| 681 | +[dotenv-extended]: https://github.com/keithmorris/node-dotenv-extended |
| 682 | +
|
| 683 | +[dotenv-mustache]: https://github.com/samcrosoft/dotenv-mustache |
| 684 | +
|
| 685 | +[dotenv-parse-variables]: https://github.com/niftylettuce/dotenv-parse-variables |
| 686 | +
|
| 687 | +[dotenv]: https://github.com/motdotla/dotenv |
0 commit comments