This repository has been archived. There will likely be no further development on the project and security vulnerabilities may be unaddressed.

NGINX Microservices Reference Architecture: Pages Service

This repository contains a simple PHP application which is used to provide the user interface for the NGINX Ingenious application. The Ingenious application has been developed by the NGINX Professional Services team to provide a reference architecture for building your own microservices based application using NGINX as the service mesh for the services.

The pages application is configured to retrieve data from other components in the NGINX Microservice Reference Architecture:

• Album Manager Service
• Content Service
• Photo Uploader Service
• User Manager Service

The default configuration for all the components of the MRA, including the Pages service, is to use the Fabric Model Architecture. Instructions for using the Router Mesh or Proxy Model architectures will be made available in the future.

Quick start

As a single service in the set of services which comprise the NGINX Microservices Reference Architecture application, Ingenious, the Pages service is not meant to function as a standalone service. Once you have built the image, it can be deployed to a container engine along with the other components of the Ingenious application, and then the application will be accessible via your browser.

There are detailed instructions for building the service below, and in order to get started quickly, you can follow these simple instructions to quickly build the image.

0. (Optional) If you don't already have an NGINX Plus license, you can request a temporary developer license here. If you do have a license, then skip to the next step.
1. Copy your licenses to the /mra-pages/nginx/ssl directory
2. Run the command docker build . -t <your-image-repo-name>/pages:quickstart where is the username for where you store your Docker images
3. Once the image has been built, push it to your image repository with the command docker push -t <your-image-repo-name>/pages:quickstart

At this point, you will have an image that is suitable for deployment on to a Kubernetes installation, and you can deploy the image by creating YAML files and uploading them to your Kubernetes installation.

To build a customized image for different container engines or to set other options, please follow the directions below.

Building a Customized Docker Image

The Dockerfile for the Pages service is based on the php:7.0.5-fpm image, and installs NGINX open source or NGINX Plus. Note that NGINX Plus includes features which make discovery of other services possible, include additional load balancing algorithms, create persistent SSL/TLS connections, and provide advanced health check functionality.

Please refer to the comments in the Dockerfile for details about each command which is used to build the image.

The command, or entrypoint, for the Dockerfile is the php-start.sh script. This script sets some local variables, then starts PHP FPM and NGINX in order to handle page requests. Configuration for PHP FPM is found in the php5-fpm.conf file

1. Build options

The Dockerfile sets some ENV arguments which are used when the image is built:

• USE_NGINX_PLUS
  The default value is true. When this value is set to false, NGINX open source will be built in to the image and several features, including service discovery and advanced load balancing will be disabled. See installing nginx plus

• USE_VAULT
  The default value is false. Setting this value to true will cause install-nginx.sh to look for a file named vault_env.sh which contains the VAULT_ADDR and VAULT_TOKEN environment variables to retrieve NGINX Plus keys from a vault server.

  #!/bin/bash
  export VAULT_ADDR=<your-vault-address>
  export VAULT_TOKEN=<your-vault-token>
  

  You must be certain to include the vault_env.sh file when USE_VAULT is true. There is an entry in the .gitignore file for vault_env.sh

  In the future, we will release an article on our blog describing how to use vault with NGINX.

• CONTAINER_ENGINE
  The container engine used to run the images in a container. CONTAINER_ENGINE can be one of the following values

  • kubernetes (default): to run on Kubernetes When the nginx.conf file is built, the fabric_config_k8s.yaml will be used to populate the open source version of the nginx.conf template
  • mesos: to run on DC/OS When the nginx.conf file is built, the fabric_config.yaml will be used to populate the open source version of the nginx.conf template
  • local: to run in containers on the machine where the repository has been cloned When the nginx.conf file is built, the fabric_config_local.yaml will be used to populate the open source version of the nginx.conf template

2. Decide whether to use NGINX Open Source or NGINX Plus

Installing NGINX Open Source

Set the USE_NGINX_PLUS property to false in the Dockerfile

Installing NGINX Plus

Before installing NGINX Plus, you'll need to obtain your license keys. If you do not already have a valid NGINX Plus subscription, you can request developer licenses here

Set the USE_NGINX_PLUS property to true in the Dockerfile

By default USE_VAULT is set to false, and you must manually copy your nginx-repo.crt and nginx-repo.key files to the /mra-pages/nginx/ssl/ directory.

Download the nginx-repo.crt and nginx-repo.key files for your NGINX Plus Developer License or subscription, and move them to the root directory of this project. You can then copy both of these files to the /nginx/ssl directory of each microservice using the command below:

cp nginx-repo.crt nginx-repo.key <repository>/nginx/ssl/

If USE_VAULT is set to true, you must have installed a vault server and written the contents of the nginx-repo.crt and nginx-repo.key file to vault server. Refer to the vault documentation for instructions configuring a vault server and adding values to it.

3. Decide which container engine to use

Set the CONTAINER_ENGINE variable

As described above, the CONTAINER_ENGINE environment variable must be set to one of the following three options. The install-nginx.sh file uses this value to determine which template file to use when populating the nginx.conf file.

• kubernetes
• mesos
• local

4. Build the image

Replace <your-image-repo-name> with the username for where you store your Docker images, and execute the command below to build the image. The <tag> argument is optional and defaults to latest

docker build . -t <your-image-repo-name>/pages:<tag>

5. Runtime environment variables

In order to run the image, some environment variables must be set so that they are available during runtime.

Variable Name	Description	Example Value
AWS_ACCESS_KEY_ID	Your AWS Access Key ID	ABCD12345ABCD12345ABCD12345
AWS_REGION	The AWS Region	us-west-1
AWS_SECRET_ACCESS_KEY	Your AWS Secret Access Key	ABCD12345ABCD12345ABCD12345
PHOTOMANAGER_ALBUM_PATH	The URI of the album manager albums	/album-manager/albums
PHOTOMANAGER_CATALOG_PATH	The URI of the album manager catalogs	/album-manager/albums
PHOTOMANAGER_ENDPOINT_URL	The URL of the album manager service	http://localhost
PHOTOMANAGER_IMAGES_PATH	The URI for the photouploader images	/album-manager/images
PHOTOUPLOADER_ALBUM_PATH	The URI for the photouploader albums	/uploader/album
PHOTOUPLOADER_ENDPOINT_URL	The port and host of the photo uploader service	http://localhost
PHOTOUPLOADER_IMAGE_PATH	The URI to the image uploader service	/uploader/image
REDIS_CACHE_PORT	The redis cache port	6379
REDIS_CACHE_URL	The hostname of the redis cache service	redis.service
S3_BUCKET	The name of the S3 bucket where images are stored
USERMANAGER_ENDPOINT_URL	The URL of the user manager service	http://localhost
USERMANAGER_LOCAL_PATH	The local URI for the user manager service	/user-managear/v1/users
USERMANAGER_USER_PATH	The URI to the user manager service	/user-manager/v1/users
CONTENTSERVICE_ENDPOINT_URL	The port and host of the content service	http://localhost
CONTENTSERVICE_ARTICLE_PATH	The URI to the article content service	/content-service/v1/content

6. Service Endpoints

Method	Endpoint	Description	Parameters
GET	/	Render the home page
GET	/about	Render the about page
GET	/account	Render the account page. Must be authenticated
GET	/login	Renders the login page
POST	/login	Sends username and password for authentication	username, password
GET	/myphotos	Render the albums and photos for the user. Must be authenticated
GET	/photos/{catalogID}/{albumName}/{albumID}	Renders photos for a specific album. Must be authenticated	catalogID, albumName, albumID
GET	/stories/{articleID}	Renders the posts for the user. Must be authenticated	articleID

Disclaimer

In this service, the nginx/ssl/dhparam.pem file is provided for ease of setup. In production environments, it is highly recommended for secure key-exchange to replace this file with your own generated DH parameter.

You can generate your own dhparam.pem file using the command below:

openssl dhparam -out nginx/ssl/dhparam.pem 2048