Installation
This document describes how to set up a deployment of Inrupt Enterprise Solid Server (ESS). To set up a deployment, ESS provides various Kustomize overlays that can act as the base configuration for your deployment.
Important
ESS uses three-element version descriptors for its Kubernetes images, corresponding to the release versions (i.e., semantic versions of Major.Minor.Patch). For example docker.software.inrupt.com/inrupt-kustomizer:2.3.6
.
Prerequisites
CRITICAL SECURITY REQUIREMENT
NEVER commit files containing secrets such as .env
or JWT
to version control. These files must be managed securely.
As part of updating the inputs for your deployment:
Review the template secret files
Set strong secrets for the values, such as strong passwords
Store the secret securely outside your repository using one of these methods:
Cloud secrets management service
Enterprise secrets vault solution
Kubernetes Secrets with encryption at rest
Secure file system with restricted access (development only)
Configure your deployment to retrieve credentials from your secure storage at runtime
Add the secrets files to your
.gitignore
file immediately
Entitlement Token
To login to Inrupt’s private Docker registry and download the ESS Docker images, your enterprise needs to obtain an entitlement token from Inrupt.
For inquiries (including pricing inquiries) about obtaining the token, you can either:
Contact your Inrupt representative; or
Contact Inrupt’s Business Development team.
Docker
The installation uses Linux Docker images. If Docker is not installed, refer to its official documentation to install.
Kubernetes Version
ESS supports Kubernetes versions 1.21+
.
Kubernetes Management Tool
To deploy and manage the Kubernetes cluster, install a Kubernetes deployment tool (if not already installed).
This tutorial uses kubectl
. To install kubectl
, use the directions at https://kubernetes.io/docs/tasks/tools/
Kubernetes Environment
For your Kubernetes Environment, ensure that the following features are enabled:
To enable these features for your Kubernetes environment, refer to your Kubernetes-specific documentation.
For an example, see Prepare a Local Kubernetes Environment to set up a local Kubernetes environment.
OIDC-Compliant Identity Provider
ESS integrates with your OpenID Connect (OIDC) compliant Identity Provider (IdP). In addition, as part of the provided standalone
overlay, ESS includes Keycloak. When using the provided Keycloak, your usernames should be alphanumeric.
To use your OIDC-compliant IdP, refer to your IdP’s official site to set up an OIDC application. When configuring the OIDC application:
Callback/Redirect URL
Set to https://openid.<ESS Domain>/callback
.
OAuth 2.0 Flow
Set to Authorization code grant
. For more information, see The OAuth 2.0 Authorization Framework
OIDC Scopes
Must include openid
and profile
.
Publicly Accessible
ESS services are designed to be accessible from and have access to the Internet. For example,
JSON Web Key Set (JWKS) may be hosted on external services, and ESS services would need access to those when running in an open Solid ecosystem.
If running ESS with certificates from LetsEncrypt, common LetsEncrypt validation challenges require Internet access.
With Internet access, ESS can also integrate with third-party services such as Identity Providers, Cloud Logging, Metrics, Telemetry systems.
Installation
Step 1: Initialize the Installation Directory
Start Docker.
Open a terminal shell and login to Inrupt’s private Docker registry. When prompted for your password, enter your entitlement token:
docker login --username <userid> docker.software.inrupt.com
Get the latest 2.3 version of the
inrupt-kustomizer
:
docker pull docker.software.inrupt.com/inrupt-kustomizer:2.3.6
4. Initialize an empty installation directory with a base overlay for your environment:
The tutorial follows the Infrastructure as Code (IaC) practice for managing the system and assumes the installation directory is under source control. Specifically, since secrets are stored in the configuration files, the tutorial assumes the directory is stored in a private repository and kept secure.
As such, the steps include committing the directory and its files to your source control.
CRITICAL SECURITY REQUIREMENT
NEVER commit files containing secrets such as .env
or JWT
to version control. These files must be managed securely.
As part of updating the inputs for your deployment:
Review the template secret files
Set strong secrets for the values, such as strong passwords
Store the secret securely outside your repository using one of these methods:
Cloud secrets management service
Enterprise secrets vault solution
Kubernetes Secrets with encryption at rest
Secure file system with restricted access (development only)
Configure your deployment to retrieve credentials from your secure storage at runtime
Add the secrets files to your
.gitignore
file immediately
a. Run the inrupt-kustomizer
, specifying the absolute path to the installation directory.
docker run -it -v ${HOME}/ess:/kustomize docker.software.inrupt.com/inrupt-kustomizer:2.3.6
The operation prompts you to select from one of the available overlays provided by Inrupt as a base overlay:
It appears that this environment hasn't been initialized.
You can choose an overlay that you'd like to base this environment on.
For more details please see: https://docs.inrupt.com/ess/2.3/installation/
The available overlays are:
scalable-cloud
ESS Scalable Cloud with external storage, queues and identity provider
standalone
WARNING! ESS Standalone comes bundled with in-cluster storage, queues and identity provider for specific evaluation purposes only. DO NOT deploy ESS Standalone in production environments. Unexpected issues may arise. Inrupt disclaims all liability and responsibility for use of ESS Standalone in a production environment. Contact [email protected] for assistance or inquiries. Your understanding is appreciated.
b. Enter the overlay to use. For example, to use the Scalable Cloud overlay as the base, enter scalable-cloud:
Please enter the overlay you would like to use [scalable-cloud]: scalable-cloud
The operation populates the specified installation directory with various files needed to set up your environment.
Extracting inputs required for overlay "scalable-cloud"...
The inputs for "scalable-cloud" are now in the "inputs" folder
Generating "kustomization.yaml" to allow you to fine-tune your environment...
Please refer to the **`readme.txt`** file that was generated. It contains instructions on how to set up your environment.
c. Place the directory under source control in a private repo.
Ensure that the directory is in a private repo for best security
Step 2: Update Inputs and Build
Inputs may change per versions. For example, a new input file may be added or new input may be required in an existing input file. Always review the contents of the inputs
folder when performing the installation/upgrades.
During the initialization, Inrupt generates a readme.txt
file in the installation directory. The file provides instructions on updating inputs for your deployment and building the deployment file.
Go to the installation directory.
cd ${HOME}/ess
Using the instructions in the
readme.txt
file, update the inputs in the base overlay for your deployment.
WarningCRITICAL SECURITY REQUIREMENT
NEVER commit files containing secrets such as .env
or JWT
to version control. These files must be managed securely.
As part of updating the inputs for your deployment:
Review the template secret files
Set strong secrets for the values, such as strong passwords
Store the secret securely outside your repository using one of these methods:
Cloud secrets management service
Enterprise secrets vault solution
Kubernetes Secrets with encryption at rest
Secure file system with restricted access (development only)
Configure your deployment to retrieve credentials from your secure storage at runtime
Add the secrets files to your
.gitignore
file immediately
Important
Inputs may change per versions. For example, a new input file may be added or new input may be required in an existing input file. Review the contents of your inputs/
folder for your installation/upgrades.
Kafka Message Encryption
ESS’ services communicate with each other by sending messages through Kafka.
By default, Inrupt enables data encryption for all data that pass through the Kafka messaging system.
You MUST set the data encryption key values to a strong password.
For more information on the Kafka configurations in the kafka-credentials.env
file, see
After updating the inputs, build the deployment file per the instructions in the
readme.txt
file.Commit all changes in the directory to source control.
Ensure that the repo is private
Step 3: Optional. Customize Your Deployment Configuration
Optionally, you can further customize your ESS deployment using Kustomize overlays , such as to use certificates from an official Certificate Authority (CA).
For examples on customizing your deployment with overlays, see Customize ESS
Step 4: Deploy
After you have built the deployment file, you can deploy.
If not already, go to the installation directory:
cd ${HOME}/ess
Deploy to your Kubernetes environment:
kubectl apply -f kustomized.yaml
Warning: Self-signed Certificates The provided base overlays create self-signed certificates. These self-signed certificates are for development purposes only . In production, ESS should be run with certificates from an official Certificate Authority (CA). For an example of how you can customize your deployment to use your production certificates, see Use Official Certificate Authority.
You can view the ESS components and services that are running:
kubectl -n ess get all
For local standalone deployments , add the ESS service domains to the
/etc/hosts
file on your local machine.The following steps are specific to Linux operating system.
Get your local Kubernetes cluster IP address:
K8_IP=$(kubectl get nodes -o jsonpath="{.items[*].status.addresses[?(@.type=='InternalIP')].address}")
Get a list of the ESS service domains:
ESS_DOMAINS=$(grep "host: " kustomized.yaml | awk '{print $3}' | sort -u | tr -d '\r' | tr '\n' ' ')
Backup your
/etc/hosts
file:sudo cp /etc/hosts /etc/hosts.bak
Update the
/etc/hosts
:sudo sed -n -e '/# ESS-DOMAINS-BEGIN/,/# ESS-DOMAINS-END/!p' -e '$a# ESS-DOMAINS-BEGIN\n'"$K8_IP $ESS_DOMAINS"'\n# ESS-DOMAINS-END' -i /etc/hosts
To verify, go to
https://start.{ESS DOMAIN}/
.
Appendix
Delete ESS
Because ESS deploys to a namespace ( ess
), you can delete ESS by deleting the ess
namespace:
kubectl delete namespace ess
Ensure that no other components have been deployed to the namespace.
Last updated