Prerequisites

The following must be installed before installation of the Policy Server can begin:

You must also acquire a set of SHAID API keys. These are made available to level 4 OEM members through the developer portal.

NOTE: Be careful not to use sets of SHAID API keys from multiple vendors. Some Policy Server actions (like changing the auto-approval status of an app) will attempt to send information back to SHAID and if the wrong SHAID API keys are used then the action may fail.

Setup Guide

Download the project to your current directory.

git clone https://github.com/smartdevicelink/sdl_server.git
cd sdl_server

The recommended branch to use is master, which should be used by default. Install dependencies.

npm install

The Policy Server requires a SQL database, and currently the only supported implementation is PostgreSQL. In the next section, we will cover how to get one running locally.

PostgreSQL Installation (Mac)

To install PostgreSQL on a Mac with Homebrew, run the following command in a Terminal window:

brew install postgresql

Then run the following command to start PostgreSQL, and ensure that you won't need to start it again in case your system resets:

pg_ctl -D /usr/local/var/postgres start && brew services start postgresql

You can run the following command to know if you have PostgreSQL and also check that you are running the most recent version:

psql -V

PostgreSQL Installation (Ubuntu)

To install PostgreSQL in Ubuntu, run the following commands from the PostgreSQL documentation:

# Create the file repository configuration:
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# Import the repository signing key:
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# Update the package lists:
sudo apt-get update

# Install the latest version of PostgreSQL.
# If you want a specific version, use 'postgresql-12' or similar instead of 'postgresql':
sudo apt-get -y install postgresql

You can run the following command to know if you have PostgreSQL and also check that you are running the most recent version:

psql -V

Logging in to PostgreSQL

In order to start creating users and databases, you will have to log in to PostgreSQL. It comes with a postgres user that should have no password by default. Run the following command to log in as the postgres user:

psql -U postgres

If you're prompted for a password but have not yet set one, you'll have to locate and modify your pg_hba.conf file. Find the line that contains

local  all      postgres     peer

Update it to contain

local  all      postgres     trust

Then restart postgres and attempt to log in to postgres again

sudo service postgresql restart
psql -U postgres

Creating the PostgreSQL Database

You should now be in the postgres command-line interface. You can type help to get more info. If you want to continue using the postgres user, you can add a password with the following command:

ALTER USER postgres WITH PASSWORD '<password>';

If you want to create a new user, run the following commands to create one with a password and give them super user access:

CREATE USER <username> WITH PASSWORD '<password>';
ALTER USER <username> WITH SUPERUSER;

Alternatively you can use the GRANT command to limit the user's permissions. In the future, you can log in to PostgreSQL using this new user. Next, you'll need to run the following command to add a new database for the Policy Server to manage:

CREATE DATABASE <database_name>;

This database will be where the Policy Server stores all of its data pertaining to policy table generation. Remember to save your PostgreSQL username, password, and database name so you can use them in the next section. To exit the PostgreSQL CLI, simply type quit and hit Enter.

Environment Variables

Once you set up a database (locally or remotely) you'll need to supply the Policy Server with some environment variables. This Policy Server uses the dotenv module, meaning you can write all your environment variables in a .env file located in the root directory of the Policy Server. The Policy Server will load the variables at .env. .env files will not be tracked by Git.

There are several settings that can be configured for Policy Server usage. See below for explanations on the purpose of each of them.

Basic Environment Variables

SHAID Environment Variables

Caching Environment Variables

Emailing Environment Variables

Mandatory Certificate and Encryption Environment Variables

Optional Certificate and Encryption Environment Variables

Miscellaneous Environment Variables

Deprecated Environment Variables

Production/Staging environment variables for the database are now deprecated. Please use the corresponding DB_ values in place of them (ex. DB_USER instead of PRODUCTION_PG_USER or STAGING_PG_USER).

The Policy Server comes with migration scripts that can be run using npm scripts. You can see a list of all the possible scripts by looking in package.json, but these are the most important ones:

• start-server: Runs the migration up script which initializes data in the database and starts the Policy Server
• dev or start: Starts the dev server with hot reloading so any changes made to the UI are instantly updated in the browser

NOTE: Using the dev server can cause CORS issues when connecting to the API so it should only be used when testing UI changes.

• build: Generates a new staging/production build using webpack. This command should only be run if you made front-end modifications to the UI.
• lint: Parses the Policy Server code and checks for syntactical or stylistic errors.
• start-pg-staging DEPRECATED: Runs the migration up script which initializes data in the database, sets the environment to staging and starts the Policy Server
• start-pg-production DEPRECATED: Runs the migration up script which initializes data in the database, sets the environment to production and starts the Policy Server
• db-migrate-reset-pg-staging DEPRECATED: Runs the migration down script which drops all the data and tables in the staging database

Production/Staging scripts are now deprecated. Please use start-server instead of start-pg-staging or start-pg-production.

Run the following command to finalize set up and start the server.

npm run start-server

Verify that it started properly by navigating to your configured host and port, or to the default address: http://localhost:3000/

Now you have a Policy Server running!

• If you wish to enable caching with an unofficially supported datastore, you may create a custom cache module. Do so by creating a folder inside custom/cache with the name of your module. Put your implementation in a file named index.js inside of your module's folder. Your module should export the following functions:
  • get(key, callback): Receives a value from the cache stored at key.
  • set(key, value, callback): Sets a value in the cache stored at key.
  • del(key, callback): Deletes a value from the cache stored at key.
  • flushall(callback): Deletes all data previously set in the cache.
• Set your CACHE_ environment variables to correspond with your new datastore solution and access information.