Set Up
This setup runs the MPS and RPS microservices as Docker* containers, standardized packages containing an application's source code, libraries, environment, and dependencies.
Get the Toolkit¶
To clone the repositories:
-
Open a Terminal or Command Prompt and navigate to a directory of your choice for development:
git clone https://github.com/open-amt-cloud-toolkit/open-amt-cloud-toolkit --branch v2.6.1 --recursive
-
Change to the cloned
open-amt-cloud-toolkit
directory.cd open-amt-cloud-toolkit
Set Environment Variables¶
The .env.template
file is used by docker to set environment variables.
To set the environment variables:
-
Copy the
.env.template
file to.env
:cp .env.template .env
copy .env.template .env
-
In a text editor or IDE of choice, open the new
.env
file to edit. -
Update the following fields for configuring the MPS, Sample Web UI, Vault and Postgres. Save and keep track of the values you choose.
Field Name Required Usage MPS_COMMON_NAME Development System IP Address. For connecting to MPS server via UI or APIs. WARNING: Do not use localhost. Use the development system IP Address. MPS_WEB_ADMIN_USER Username of your choice For logging into the Sample Web UI MPS_WEB_ADMIN_PASSWORD Strong password of your choice For logging into the Sample Web UI MPS_JWT_SECRET A strong secret of your choice (Example: A unique, random 256-bit string. See another example in code snippet below). Used when generating a JSON Web Token (JWT) for authentication. This example implementation uses a symmetrical key and HS256 to create the signature. Learn more about JWT. POSTGRES_PASSWORD Strong password of your choice For logging into the Postgres VAULT_TOKEN Strong token of your choice For logging into the vault Important - Using Strong Passwords
The MPS_WEB_ADMIN_PASSWORD must meet standard, strong password requirements:
-
8 to 32 characters
-
One uppercase, one lowercase, one numerical digit, one special character
-
-
Save the file.
Set Kong JSON Web Token (JWT)¶
Set the shared secret used in Kong for JWT authentication.
-
Open the
kong.yaml
file. -
Update the secret field with your MPS_JWT_SECRET.
jwt_secrets: - consumer: admin key: 9EmRJTbIiIb4bIeSsmgcWIjrR6HyETqc #sample key secret: "Yq3t6w9z$C&E)H@McQfTjWnZr4u7x!A%" #sample secret, DO NOT use for production
-
Save and close the file.
Pull and Run the Docker Images¶
-
Pull the Docker images from Intel's Docker Hub repository.
sudo docker-compose pull
docker-compose pull
Note - Using an ARM-based Device?
ARM-based devices (i.e. newer-generation Mac products and others) will need to build the images rather than use the prebuilt Dockerhub images.
docker-compose up -d --build
Note - Using SSL with Postgres Container
By default in the Getting Started Guide, we do not enable an SSL connection for Postgres for ease of development. See SSL with Local Postgres for how to enable SSL in your local Postgres container. For production environments, using a cloud-hosted database with an SSL connection to MPS/RPS is highly recommended as one step to maintain a secure deployment. Read more about cloud deployments for Azure or AWS here.
-
Start the containers.
sudo docker-compose up -d
docker-compose up -d
-
Check that all the containers are running and healthy.
sudo docker ps --format "table {{.Image}}\t{{.Status}}\t{{.Names}}"
docker ps --format "table {{.Image}}\t{{.Status}}\t{{.Names}}"
Success
IMAGE STATUS NAMES intel/oact-rps:latest Up 2 minutes (healthy) open-amt-cloud-toolkit_rps_1 eclipse-mosquitto Up 2 minutes open-amt-cloud-toolkit_mosquitto_1 vault Up 2 minutes open-amt-cloud-toolkit_vault_1 intel/oact-mpsrouter:latest Up 2 minutes (healthy) open-amt-cloud-toolkit_mpsrouter_1 postgres:14 Up 2 minutes (healthy) open-amt-cloud-toolkit_db_1 intel/oact-webui:latest Up 2 minutes open-amt-cloud-toolkit_webui_1 kong:2.3 Up 2 minutes (healthy) open-amt-cloud-toolkit_kong_1 intel/oact-mps:latest Up 2 minutes (healthy) open-amt-cloud-toolkit_mps_1
Warning - Container Issues
If any of the above containers are not running, walk through the steps again or file a GitHub issue here.
If the kong container reloads repeatedly, verify kong.yaml edits. Misconfiguration of this file will cause the container to reload.
Important - Losing Data without Prod Mode Vault
Because the vault is running in a dev mode, stored secrets will be lost upon a restart, and profiles and configs must be recreated. They are not persistent in this mode. Be sure to run docker-compose down -v
when bringing down the stack, which removes the volumes, and start fresh upon docker-compose up
. To run vault in production mode, follow the guide here.