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 to Error getting cluster config: read:. To fix, change the ownership of the ~/.minikube and ~/.kube directories as follows and retry the minikube 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), 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>

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: Find the IP address. To determine the ESS server’s IP address, refer to your OS-specific documentation: For Ubuntu, see https://help.ubuntu.com/stable/ubuntu-help/net-findip.html.en. On AWS, the <ESS Server IP> is the IPv4 public IP value of the EC2 instance into which you deployed ESS. Edit the `/etc/hosts` file on the local machine to add the following line, substitute in the `<ESS Server IP>`: <ESS Server IP> <DOMAIN> broker.<DOMAIN>

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:

Find the IP address. To determine the ESS server’s IP address, refer to your OS-specific documentation:
- For Ubuntu, see https://help.ubuntu.com/stable/ubuntu-help/net-findip.html.en.
- On AWS, the <ESS Server IP> is the IPv4 public IP value of the EC2 instance into which you deployed ESS.
Edit the /etc/hosts file on the local machine to add the following line, substitute in the <ESS Server IP>:
```
<ESS Server IP> <DOMAIN> broker.<DOMAIN>
```

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#

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:
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>
```

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.