ibm-cloud / nodejs-mean-stack

Solution tutorial: Modern Web Application using MEAN stack on IBM Cloud

Modern Web Application using MEAN stack

This is a basic boilerplate for the MEAN stack (MongoDB, Express, AngularJS and Node.js) on IBM Cloud.

This application uses Databases for MongoDB and Code Engine on IBM Cloud.

The code and detailed steps are discussed in the IBM Cloud solution tutorial titled Modern web application using MEAN stack.

Features

• MVC project structure
• Create, edit and delete user accounts
• Authentication with username/password
• Protected routes that can only be accessed by authenticated users
• Bootstrap CSS framework
• HTTPS built-in if deployed to IBM Cloud
• Mongoose for MongoDB interactions.
• PassportJS for authentication, with over 300 authentication strategies to pick from.

Application Requirements

• Node.js & NPM
• IBM Cloud Databases for MongoDB
• Code Engine Command Line Tool

Files & Folders

File	Description
.env.example	Set custom environment variables for your application. This is the proper way to store credentials and other sensitive values.
server.js	Main server file that the Node.js runtime uses. It contains all the server logic.
/server	Folder for files used by the Node.js server
/server/models/user.model.js	Model for storing users in MongoDB
/public	Folder for files delivered to users, such as html and css files
/public/js/app.js	Angular application for manipulating and rendering data in browser

Application

• MongoDB stores user account information and persists sessions (so that a server crash does not log out all users.)
• Express functions Node.js middleware to handle all HTTP requests and routing.
• Angular handles HTML templating and data manipulation.
• Node.js is the runtime for the application.

There is also generous commenting throughout the application which helps explain critical parts of the application.

Running locally

1. Clone or download this repo onto your machine.
2. Install application requirements if not done so already.
3. Open application directory in your terminal and run npm install
4. If you don't have an account, create a free one here.
5. Login to your account via the command line: ibmcloud login
6. Target your desired region ibmcloud target -r ca-tor
7. Create the instance of Databases for MongoDB on IBM Cloud: ibmcloud resource service-instance-create mean-starter-mongodb databases-for-mongodb standard ca-tor
8. Copy .env.example file to .env. Edir .env to fill it the required values. You can run ibmcloud resource service-key-create mean-starter-mongodb-key --instance-name mean-starter-mongodb to obtain the MONGODB_URL and CERTIFICATE_BASE64. Choose your own SESSION_SECRET.
9. Run node server.js to start your app
10. Open a browser to the link provided in the terminal prompt to view your app

Note that the code assumes a secured connection to MongoDB using SSL and a certificate. This way you can run the app locally but connect to IBM Cloud Databases for MongoDB.

An alternative way of running locally is using the provided Dockerfile.

• Install docker on your machine and build the docker image

   docker build . -t mean-stack:v1.0.0
  

• Run the app locally

   docker run -p 8080:8080 --env-file .env -ti mean-stack:v1.0.0 
  

Provision with Terraform

The steps of creating the resouces (database, code engine project, secret, application, .env file, ...) described in Modern web application using MEAN stack are captured in the terraform file main.tf.

Getting started with solution tutorials has a description of how to get started with terraform on a workstation.

terraform init
terraform apply

Provision with Schematics

Schematics is a cloud based Infrastructure as Code runner with cloud based state. It leverages the Terraform configuration described in the previous section.

Create a Schematics Workspace from this github repository

The link above should have opened a Schematics workspace in the create dialog with the github repository pre-configured and terraform 1.4 selected. Change the Workspace name, Resource group, and Location as desired. This will be the resource group of the workspace. The resource group of the resources created will be configured in schematics. Click Create.

In the Schematics workspace you can configure the variables before clicking Apply plan to provision the resources. Check out the Jobs tab - scroll to about the end of the Logs to see the endpoint URL that can be used to access the application.

Create private catalog product for a Deployable Architecture

In the IBM Cloud console create a private catalog and then add a product to the catalog:

• Product type: Deployable architecture.
• Deliver method: Terraform.
• Public repository: Open the releases and right click on the source.code.tar.gz file and paste in the string. Example: https://github.com/IBM-Cloud/nodejs-MEAN-stack/archive/refs/tags/1.0.3.tar.gz.
• Variation: Standard.
• Rest of the values are clear.

Click on the Version in the Version list. It will walk through a wizard where the defaults are correct, just click Next in each page till you reach Validate version, and click Validate, to create a schematics workspace and resources.

After validation is complete create/configure or open the Security and Compliance and run a scan over the entire account using the IBM Cloud Security Best Practices version 1.2.0 profile by opening the profile and click Attach in the action menu. Frequency can be set to 30 days since the first scan will be run presently and that will provide the results that are required.

Create a Project

Create a project and then create a configuration in the project using the private catalog DA product version created in the previous step.

Contribute

Please create a pull request with your desired changes.

Troubleshooting

The primary source of debugging information for your app running in the cloud are the logs. To see them, use the Code Engine web interface.

For more detailed information on troubleshooting your application, see the Troubleshooting apps section in the documentation.

License

See LICENSE.MD for license information.

nodejs-mean-stack's Issues

How to specify target node version in manifest.yml file?

Could you please help,
How to specify target node version in manifest.yml file?

By default Bluemix is taking node version as v0.10.40
My application requires v0.12.x

Could you please help, how to configure them in manifest.yml file

Test Suite for App's Critical Functions Created

Success looks like:
To automate the testing of our apps to ensure they work, a test suite covering the application's critical functions (which will vary by application) needs to pass before the app is initially released, as any new features are added and periodically to ensure an app does not break due to changing services/the like.

It's not about % of code covered by the tests but instead coverage of the 'critical functions', which if not working (i.e. connecting to a database, processing a form, etc.) the app can't be used.

Failure looks like:
Critical features of the app relying purely on manual testing to ensure they work, or not testing our apps at all.

Please add a /healthz check endpoint which checks db connection

Please add an /healthz check which indicates successful application state.

add new controller but it is Error: [$injector:unpr]

License File Included

Success looks like:
Apache 2.0 license documented in your app. Example

Failure looks like:
No license defined, thereby making it ambiguous to the user if/how they can use the code we publish.

Please add this as a template repository

ref: https://help.github.com/en/articles/creating-a-template-repository

App Can Used Without Any Setup/Coding/Development

Success looks like:
App can be run by non-technical person, such as a tech seller in front of a client or a quick demo at a trade show. This can be accomplished by having an example version of the app running on Bluemix that a user can click on to use the app without setting up a Bluemix account, coding something, or the like.

Failure looks like:
App requires a Bluemix account, 15 setup steps, in-depth coding knowledge, installing binaries on their machine or similar hoops to jump through just to experience the app.

Text is Free of Grammar and Spelling Issues

Success looks like:
Properly spelling and grammar for all text.

Failure looks like:
Bad grammers and spelings.

README Has Proper Structure & Content

Success looks like:
Guidelines outlined here for the structure and content of your repo's README file need to be met, based on what type of repo it is (demo, boilerplate, etc.).

Failure looks like:
A messy, misspelt, incomplete document that is out of date or otherwise leaves the user stranded in their experience understanding and using your app.

HTTPS Support

Since this app handles credentials for user accounts, implementing HTTPS is critical

Application Credentials Accessible to Team

Success looks like:
Application credentials (such as for accessing services) are accessible to the entire dev advocate team so that changes can be made as necessary by team members.

They can be stored in app's environment variables, a separate credentials file or any other way that keeps them secure yet available to the team.

Failure looks like:
App credentials are kept secret and when the app's developer is out of touch on vacation, a service stops working and the team cannot access/troubleshoot the issue.

Create a terraform implementation and deployable architecture for the solution tutorial

• an optional prefix. If set, it is used. If empty a default random prefix is generated like in https://github.com/l2fprod/simple-da/blob/7c35363613ca7fb2c9440bf2a7160ece5b284465/main.tf#L30
• an optional use_default_resource_group set to true, that will create the resources in the resource group marked as default https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/data-sources/resource_group#is_default. If false, a resource group is created using the local.basename (derived from prefix)
• an optional region

App Name is Not Copyrighted

Success looks like:
Name of app can't be copyrighted, trademarked, etc. Documentation on how to determine compliance TBD. In the mean time, avoid the obvious.

Failure looks like:
Naming your app 'Facebook'

Bluemix App is Hosted in 'Dev Advocates' Org

Success looks like:
The application's runtime, container and/or services need to hosted in the Bluemix 'dev-advocates' organization so that they are accessible to the entire team.

Failure looks like:
App is hosted in an advocates' private organization and when it goes offline, no one on the team can access it to troubleshoot/fix the error.

Links/Buttons/User Interactions Work

(THIS ISSUE DOES NOT APPLY TO AN OPEN WHISK REPO)

Success looks like:
All links, buttons, and other user interactions (i.e. forms) work and are not broken.

Failure looks like:
Broken user interactions of any kind

Source Code Has Proper Format & Documentation

Success looks like:
Source code that follows conventions like OOP, KISS, DRY, etc. and is documented clearly enough (inline with the code ideally) that it a developer can understand it without serious effort.

Failure looks like:
Shit code that is not documented, can only be figured out by the author and looks like it was written after being awake for 100hrs straight.

Conforms to IBM Design Language

(THIS ISSUE DOES NOT APPLY TO AN OPEN WHISK REPO)

Success looks like:
Follows IBM Design Language guidelines and uses its assets.

Need help meeting these standards? Contact Ben or Anton for assistance.

Failure looks like:
App full or UI and UX problems, or that is inconsistent with our brand.

Proper Licensing of Visual Assets

(THIS ISSUE DOES NOT APPLY TO AN OPEN WHISK REPO)

Success looks like:
If any visual assets (logos, images, icons, etc.) are used, they must be properly licensed/owned by IBM. If you did not create it or IBM does not own it already, it needs to be purchased from a stock image provider or similar means. DO NOT randomly grab stuff off the web.

Failure looks like:
Grabbing random stuff off the web that doesn't belong to us then getting sued for breaking copyright laws.

Running locally, server.js says it is running on the wrong port

When I run the server, it says it is listening on port 6003. But it is it actually running on localhost:6020, which is the value in the .env file. Example:

$ node server.js
Your MongoDB is running at mongodb://ibm_cloud_e=admin&replicaSet=replset
Node server running on http://localhost:6003
Connected to mongodb instance

User Testing Completed Prior to Public Use/Release

Success looks like:
To ensure errors/issues are not missed and get feedback on our app's experience, a fresh set of eyes (someone unfamiliar with the app) needs to review the entire end-to-end experience to make sure that 1) the experience works as is intended and 2) obvious errors are caught.

The minimum requirement is one testing session, but ideally this would occur multiple times throughout the development process by multiple people.

Checkout this simple guide to get started with user testing

Failure looks like:
Releasing code untested by outside eyes prior to public use, thereby finding out about issues from the public that should have been caught by us.

User Can Find Help & Report Bugs

Success looks like:

1. README has a clear instructions on how to report bugs/issues (such as the Github issue tracker).

2. How to get help during the business day if the app is not working (an email address, slack group, etc.).

Failure looks like:

• User has no idea how to report bugs in the app, so they are not reported and can go unnoticed by our team for weeks or months
• A user (such as an IBMer) need to show the app to a customer but the app is not working (maybe because a service name changed that the app uses) and they have no idea how to get help.

Create database wipe function for production-sample branch

Since the production-sample branch hosts an app that is live to the public, create a function to wipe the database of guest entries every 24 hours (or less). Prevents it from becoming bloated, spammed, etc.

Source Code Accessible to Team

Success looks like:
Code is hosted in publicly accessible repo (i.e. public repo on Github.com) or if in a private repo, entire dev advocate team has access to it.

Failure looks like:
Storing your code someplace that is not accessible to the team, making it impossible to fix issues if you are unavailable to do so yourself (i.e. your out on vacation).

Proper Error Feedback in App's UI & Dev Console

Success looks like:
In the event the application fails, such as a form fails to submit or to connect to a back-end database, the application's UI alerts user to the error and description of what happened(i.e. 'Error - can't connect to database'). Relevant error output is also available in the dev console so it can be diagnosed/fixed by the developer.

Failure looks like:
The application fails silently or generically (i.e. no message or a generic 'error'), leaving the user clueless as to what happened and where to start looking to diagnose/fix the error.

App's UI Does Not Break In Its Context

(THIS ISSUE DOES NOT APPLY TO AN OPEN WHISK REPO)

Success looks like:
The application's user interface must be cross-browser compatible (for a web based UI) and not break when viewed on a certain web browser (like IE), or whatever the context for the application is (i.e. iOS app that works on iOS 8, 9, etc.) UNLESS stated specifically in the README that a certain client is required (such as Chrome 48+). We don't know what context our users will be viewing our content in and therefore need to have a decent level of compatibility to ensure their experience does not break.

Failure looks like:
Application's UI breaks across clients (Chrome, Firefox, IE, etc.) and context's (mobile, desktop, etc.), thereby destroying the user experience. Or if a certain client is required (i.e. Chrome 48+), it is not documented and therefore the user is setup to fail.

Link to App's Source Code in Conspicuous Place in App's UI

Success looks like:
If a user lands on the live app's URL and therefore doesn't know where the code is hosted, it is important we make it accessible to them by exposing it to them via a link in the app's footer or other conspicuous place (like a banner in the top corner).

Failure looks like:
A user wants to see the source code of an app but cannot since it is not linked in the app or easily found by searching the web.