Install Locally#

This document describes how to set up a reference deployment of Inrupt Enterprise Solid Server (ESS) on a local (i.e., single) developer machine. The installation uses Minikube to run a single-node Kubernetes cluster inside a Virtual Machine (VM).

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#

This guide provides installation instructions for the following operating systems:

Ubuntu
macOS

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` (Ubuntu Only)#

For installations on Ubuntu, 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

By default, the unzip command is available in the Terminal.

Java#

Java is used 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

Install OpenJDK (JDK 8) using Homebrew:

To install Homebrew, follow the instructions at https://brew.sh/.
Once you have installed Homebrew, install OpenJDK (JDK 8):
```
brew tap AdoptOpenJDK/openjdk && brew cask install adoptopenjdk8
```
You may be prompted for your password during the install.

Minikube#

This deployment uses Minikube. In addition, you will need both a Hypervisor to run a Minikube virtual machine (VM) 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). Use the directions at https://kubernetes.io/docs/tasks/tools/install-kubectl/.
A Hypervisor as listed on the Minikube Installation page (if not installed). Refer to the specific Hypervisor documentation for installation. This reference tutorial uses VirtualBox.

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#

The Kubernetes cluster runs within a Minikube virtual machine (VM).

Open a Terminal window.

Start Minikube with the recommended resources.

minikube start --vm-driver=virtualbox --cpus 4 --memory 8192 --disk-size=50GB

Verify the status of the Kubernetes cluster:

minikube status

The operation should return output that resembles the following:

minikube
type: Control Plane
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured
timeToStop: Nonexistent

Verify access to Kubernetes:

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), enter y or Y 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 of dev; 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 assumes dev 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, and ess-cluster-ca-cert before creating the new secrets. If they do not exist, the delete operations return secrets <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

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>

Edit the /etc/hosts file on your local machine to map the Minikube Internet Protocol (IP) address with your domains.

Find the IP address of the Minikube VM:
```
minikube ip
```
The operation should return your Minikube IP Address.
Edit the /etc/hosts file to add the service domains. Replace <Minikube IP> and <DOMAIN> with your values:
```
<Minikube IP> <DOMAIN> broker.<DOMAIN>
```
To edit the /etc/hosts file, you need administrator privileges.

Important

If you delete the Minikube VM and rebuild a new VM, your Minikube IP could change and you will need to update the hosts file with the new IP value.

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	Open `https://<DOMAIN>/` in a browser. Accept the certificate. Note A 401 error is displayed. This is expected and indicates the certificate was accepted.
OIDC Broker	Open `https://broker.<DOMAIN>/` in a browser. Accept the certificate. Note A Welcome! page is displayed.

Verify Installation#

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:
1. Identity Provider: URL to the Solid OIDC Broker Service (e.g., https://broker.<DOMAIN>).
2. 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>
```

Delete 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.

Install Locally#

Operating System#

Prerequisites#

Repository Account#

apt (Ubuntu Only)#

Archive Extraction Tool#

Java#

Minikube#

Kustomize#

Installation#

Step 1: Start Kubernetes Cluster#

Step 2: Download the Installer Scripts#

Step 3: Initialize ESS/OIDC Environment Variables#

Step 4: Install ESS Services#

Step 5. Install the OIDC Broker#

Step 6: Add ESS Domains#

Step 7: Accept Self-Signed Certificates#

Verify Installation#

Verify ESS Deployment with Solid OIDC Broker Service#

Access via Application#

Spin Down/Up ESS#

Spin Down/Shut Down ESS#

Spin Up/Restart ESS#

Restart an ESS Microservice#

Delete Solid OIDC Broker Service#

Stop/Start/Delete Minikube#

Stop Minikube#

Start Minikube#

Delete Minikube#

`apt` (Ubuntu Only)#