Install on a Shared Server#
This document describes how to set up a reference deployment of Inrupt Enterprise Solid Server (ESS) on a single machine that is accessible externally by multiple users.
Pod Spaces (Alpha)
Inrupt provides hosted versions of the Enterprise Solid Server, eliminating the installation overhead. For more information, see Inrupt Pod Spaces.
Operating System#
The recommended deployment environment is Ubuntu Server 20.04 LTS with 4 CPUs, 8 GB RAM, and at least 100GB of free disk space.
Prerequisites#
Repository Account#
The ESS Docker images and install configuration files are hosted on Inrupt’s CloudSmith Repository. To download, you need to obtain the following details from Inrupt:
An entitlement token, and
The version number of the software that you can download with the token.
To obtain the token and associated version number, you can either:
Request them from your Inrupt representative, or
Send an email to distribution@inrupt.com.
apt#
Update the list of available packages and their versions, and upgrade the installed packages:
sudo apt update && sudo apt upgrade
Archive Extraction Tool#
An archive extraction (i.e., unzip) tool is required to extract downloaded .zip files.
To install unzip, run:
sudo apt install unzip
Java#
Java 8 is required by openssl
and keytool
to generate security
certificates and importing them into a Keystore file:
To install the necessary open-source OpenJDK (JDK 8), run:
sudo apt install openjdk-8-jre-headless
Minikube#
This deployment uses Minikube and kubectl
to manage the Kubernetes
cluster within the Minikube VM.
Install:
Minikube (if not installed). Follow the OS-specific instructions at https://minikube.sigs.k8s.io/docs/start/.
kubectl
(if not installed). Follow the directions at https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-on-linux.Optional. You can also install
kubectl
autocompletion. To install, follow the kubectl autocompletion installation instructions at https://kubernetes.io/docs/tasks/tools/install-kubectl/#optional-kubectl-configurations.
Kustomize#
New in version 1.0.9.
The installation scripts use Kustomize to configure the deployment. If Kustomize is not installed, refer to its official site for download instructions.
Installation#
Step 1: Start Kubernetes Cluster#
Open a Terminal window.
Start Minikube:
minikube start --driver=none
If you run the
minikube start
command without sudo, you might get a permission denied error similar toError getting cluster config: read:
. To fix, change the ownership of the~/.minikube
and~/.kube
directories as follows and retry theminikube start
command:sudo chown -R $(whoami):$(whoami) ~/.minikube/ sudo chown -R $(whoami):$(whoami) ~/.kube
If you see the error
Sorry, Kubernetes v1.18.0 requires conntrack to be installed in root's path
when trying to start Minikube, this is a known issue, and you will need to install conntrack and Docker:sudo apt install conntrack sudo apt install docker.io
Once installed, retry the
minikube start
command.Verify the status of the Kubernetes cluster:
minikube status
The operation should return output that resembles the following:
host: Running kubelet: Running apiserver: Running kubeconfig: Configured
To view resources in the default namespace:
kubectl get all
The operation should return output that resembles the following:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 48m
For service routing, enable Kubernetes Ingress Controller to manage external access to the services in the cluster:
minikube addons enable ingress
Step 2: Download the Installer Scripts#
Create the ESS directory and change to the directory. For example, to create the ESS directory under your home directory:
cd ~ mkdir ESS && cd ESS
Download the
.zip
file containing the ESS installation scripts. Replace<TOKEN>
and<VERSION>
with the values provided to you by Inrupt:curl -O https://download.software.inrupt.com/<TOKEN>/release/raw/names/ESS-Scripts/versions/<VERSION>/ess-reference-scripts.zip
Unzip the file:
unzip ess-reference-scripts.zip
Step 3: Initialize ESS/OIDC Environment Variables#
Go to the
deployment
directory:cd deployment
Initialize your Minikube environment, substituting your environment (such as
dev
,testing
, etc.) for<env>
:./scripts/installer.sh -e <env> -p minikube -c init
The script prompts for various values needed to build your deployment configuration files and stores these values in an ESS config file
<environment>.config
. The<environment>
is one of the prompted values; it defaults to the<env>
value specified when calling the script.Initializing ESS for Minikube environment. Enter the ESS version: Enter your token for Inrupts private docker registry: Enter an email for docker credentials: Enter a name for the environment [dev]: Enter the domain where you are hosting ESS [ess.mycompany.com]: Enter your company's 2-letter country [US]: Enter your company's state [Massachusetts]: Enter your company's city [Boston]: Enter your company's organization name [Acme]: Enter your company's organizational unit [Engineering]: Do you want to install the OIDC Broker (y/N)? Enter the OIDC Broker version: Do you want to configure a backend identity provider? (Y/n) Enter issuer URL: Enter issuer Logo URL: Enter application name: Enter client ID: Enter client secret: Do you want to configure another backend identity provider? (Y/n) ... Enter a password for the Postgres server : Enter an admin WebID for the OIDC Broker : Enter an admin email for the OIDC Broker : Enter an admin password for the OIDC Broker : Enter a password for the OIDC Broker TLS Keystore : Enter a password for the OIDC Broker TLS Truststore :
Enter the appropriate values needed to build your deployment configuration files.
Tip
When prompted for the OIDC Broker (
Do you want to install the OIDC Broker
), entery
orY
to enter the OIDC Broker values at this time.Otherwise, you must rerun the whole init script later to initialize for the OIDC Broker installation. That is, for the OIDC Broker installation, you must reenter the ESS values before you can enter the OIDC Broker values.
When configuring the backend identity provider for the OIDC Broker, remove all spaces and new lines when entering the
application name
.
The
init
operation finishes with a message similar to the following, where<environment>
value is substituted with your<environment>
value (e.g.,dev
,testing
):Created ESS config [<environment>.config].
For sake of simplicity, the remaining sections assume the
<environment>
value ofdev
; i.e.Created ESS config [dev.config].
Step 4: Install ESS Services#
Note
For sake of simplicity, this section assumes the <environment>
value of dev
(and the existence of the dev.config
file). If
your environment value differs, pass that value to the script’s
environment -e
option.
Run the
installer.sh
file to download and build your ESS Minikube configuration files for your environment. The example assumesdev
environment../scripts/installer.sh -e dev -p minikube -s ess -c build
Run the
installer.sh
file to deploy ESS:./scripts/installer.sh -e dev -p minikube -s ess -c install
The
installer.sh
prints the following line upon success:ESS deployment installed successfully!
Tip
If the deploy operation does not complete successfully, you can safely retry the operation as it is idempotent.
If the retry also does not succeed, see also Troubleshoot Installation.
Warning: Self-signed Certificates
The script creates 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).
The script deletes any existing certificate and key files in the directory before creating the new files.
The script deletes existing Kubernetes secrets
ess-cluster-tls
,ess-cluster-ca-certs
,ess-jwks-tls
, andess-cluster-ca-cert
before creating the new secrets. If they do not exist, the delete operations returnsecrets <name> not found
error messages that can be ignored.You can view the ESS components and services that are running:
kubectl -n ess get all
Step 5. Install the OIDC Broker#
Note
For sake of simplicity, this section assumes the <environment>
value of dev
(and the existence of the dev.config
file). If
your environment value differs, pass that value to the script’s
environment -e
option.
If you have not initialized the environmental variables for the OIDC Broker installation (see Step 3: Initialize ESS/OIDC Environment Variables step), initialize your Minikube environment . If you have already initialized the values, you can skip this step.
./scripts/installer.sh -p minikube -c init -e dev
When prompted, enter the appropriate values needed to build your deployment configuration files.
When configuring the backend identity provider for the OIDC Broker, remove all spaces and new lines when entering the
application name
.Run the
installer.sh
file to download and build your OIDC Broker configuration files../scripts/installer.sh -e dev -p minikube -s oidc -c build
Run the
installer.sh
file to deploy OIDC Broker:./scripts/installer.sh -e dev -p minikube -s oidc -c install
The
installer.sh
prints the following line upon success:OIDC Broker deployment installed successfully!
You can view the OIDC Broker components and services that are running:
kubectl -n oidc get all
Step 6: Add ESS Domains#
By default, ESS exposes the following services for external access,
where <DOMAIN>
is domain name you configured earlier:
LDP Service:
<DOMAIN>
OIDC Broker:
broker.<DOMAIN>
To access the service, create the DNS entries appropriate to the access level:
Access Level |
|
---|---|
Access Globally |
To allow global access to your ESS deployment from anywhere on the Internet, configure your organization’s globally registered DNS entries. |
From Organization Only |
To allow access to your ESS deployment only from within your organization, configure your organization’s internal DNS server. |
From Local Machine Only |
To allow access to your ESS deployment only from your local machine:
|
Step 7: Accept Self-Signed Certificates#
Warning
The self-signed certificates are for development purposes only. In production, ESS should be run with certificates from an official Certificate Authority (CA).
If you are using self-signed certificates, you must accept them for the
primary services. Replace <DOMAIN>
with your domain name:
Service |
Procedure |
---|---|
LDP |
|
OIDC Broker |
|
Verify Installation#
Note
Replace <DOMAIN>
with the domain name for your deployment (e.g.,
ess.mycompany.com
).
Verify ESS Deployment with Solid OIDC Broker Service#
Open a web browser to
https://<DOMAIN>/verify.html
, substituting your domain for<DOMAIN>
.On the displayed Enterprise Solid Server Deployment Tests page, enter:
Identity Provider: URL to the Solid OIDC Broker Service (e.g.,
https://broker.<DOMAIN>
).LDP Storage Server: URL of the LDP Storage service (e.g.,
https://<DOMAIN>
).
Click the Begin Tests button to run the first set of tests.
When these tests complete, you should see the results.
If all the initial tests pass, click on the Authenticate button. You should be redirected to a Provider selection page.
You may encounter an Authorization page. If so, click Authorize to continue withe the test.
Select a provider with whom you have an existing account and the specific account use for the login.
Once logged in, you are redirected to a standard OIDC Authorization screen.
Click the Authorize button. You should be redirected back to the ESS Server Verification webpage, and the second-phase set of tests should all run automatically.
If all of these checks are green, then the deployment was successful. If there are errors, it will indicate which part of functionality is not working to aid with debugging deployment issues.
Access via Application#
You can validate the installation process by accessing the deployed ESS from an application:
Open a web browser to https://podbrowser.inrupt.com.
In the login dialog that appears, enter
https://broker.<DOMAIN>
.Click the
Log In
button.
Spin Down/Up ESS#
Spin Down/Shut Down ESS#
Go to the
ESS/deployment
directory.cd ~/ESS/deployment
Change the permissions of the
./scripts/ess-shutdown.sh
script, if needed.chmod +x ./scripts/ess-shutdown.sh
To shutdown, run the
ess-shutdown.sh
script, passing in the environment value specified during the installation initialization (e.g.,dev
,testing
, etc.)../scripts/ess-shutdown.sh <env>
To verify that all ESS components and services are gone, run:
kubectl -n ess get all
Only the
service/kubernetes
service should be running.
Spin Up/Restart ESS#
Go to the
ESS/deployment/scripts
directory.cd ~/ESS/deployment/scripts
Change the permissions of the
./scripts/ess-restart.sh
script, if needed.chmod +x ./scripts/ess-restart.sh
To restart all the ESS services after they have been shut down, run the
ess-restart.sh
script:./ess-restart.sh
Restart an ESS Microservice#
To restart a specific ESS Microservice if it is not running, run the following command, specifying the deployment to restart:
kubectl rollout restart <service app deployment>
To check the status of the rollout, run the following command, specifying the deployment:
kubectl rollout status <service app deployment>
Tear Down Solid OIDC Broker Service#
Since the Solid OIDC Broker Service is deployed in its own separate
namespace, if you want to delete the service, you can do so by deleting
the oidc
namespace. The following command will delete the Solid OIDC
Broker Service, Deployment, and the configurations:
kubectl delete namespace oidc
To re-install the service, you can run the installer.sh
:
./scripts/installer.sh -e dev -p minikube -s oidc -c install
Stop/Start/Delete Minikube#
Stop Minikube#
When you’re finished with the environment, to save local resources it can be stopped with the following command:
minikube stop
This command shuts down the Kubernetes cluster and Minikube.
Start Minikube#
To restart Minikube, run:
minikube start
kubectl config set-context --current --namespace=ess
The operation returns a message stating Context "minikube" modified.
Minikube and all related services are booted back up as before.
Delete Minikube#
To fully delete the Kubernetes cluster and Minikube, run the following command:
minikube delete
This command removes everything, and it will require a full rebuild to spin the environment back up again.