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:

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:

Installation

Step 1: Start Kubernetes Cluster

  1. Open a Terminal window.

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

  3. 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
    
  4. 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
    
  5. 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

  1. 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
    
  2. 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
    
  3. Unzip the file:

    unzip ess-reference-scripts.zip
    

Step 3: Initialize ESS/OIDC Environment Variables

  1. Go to the deployment directory:

    cd deployment
    
  2. Initialize your Minikube environment.

    ./scripts/installer.sh -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, where <environment> is one of the prompted values.

    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.

Step 4: Install ESS Services

  1. Run the installer.sh file to download and build your ESS Minikube configuration files.

    ./scripts/installer.sh -e dev -p minikube -s ess -c build
    
  2. Run the installer.sh file to deploy ESS:

    ./scripts/installer.sh -e dev -p minikube -s ess -c install
    

    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.

    The installer.sh prints the following line upon success:

    ESS deployment installed successfully!
    
  3. You can view the ESS components and services that are running:

    kubectl -n ess get all
    

Step 5. Install the OIDC Broker

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

    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.

  2. 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
    
  3. 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!
    
  4. 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:

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:

  1. Find the IP address. To determine the ESS server’s IP address, refer to your OS-specific documentation:

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

AWS Deployments

If ESS is being deployed to Amazon Web Services, to allow external access to the EC2 instance running ESS, add a new Incoming Rule:

  1. Select the EC2 instance, under Security groups (from the Description tab).

  2. Select launch-wizard-XXXX.

  3. Click the Edit inbound rules button in the Inbound Rules tab.

  4. Click Add Rule button.

  5. Configure the new rule for HTTPS and add the IP address of your local machine (and any other machines you wish to have access to this ESS deployment).

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

  1. Open https://<DOMAIN>/ in a browser.

  2. Accept the certificate.

    Note

    A 401 error is displayed. This is expected and indicates the certificate was accepted.

OIDC Broker

  1. Open https://broker.<DOMAIN>/ in a browser.

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

  1. Open a web browser to https://<DOMAIN>/verify.html, substituting your domain for <DOMAIN>.

  2. 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>).

  3. Click the Begin Tests button to run the first set of tests.

    When these tests complete, you should see the results.

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

  5. Select a provider with whom you have an existing account and the specific account use for the login.

  6. Once logged in, you are redirected to a standard OIDC Authorization screen.

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

  1. Open a web browser to https://podbrowser.inrupt.com.

  2. In the login dialog that appears, enter https://broker.<DOMAIN>.

  3. Click the Log In button.

Spin Down/Up ESS

Spin Down/Shut Down ESS

  1. Go to the ESS/deployment directory.

    cd ~/ESS/deployment
    
  2. Change the permissions of the ./scripts/ess-shutdown.sh script, if needed.

    chmod +x ./scripts/ess-shutdown.sh
    
  3. 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>
    
  4. 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

  1. Go to the ESS/deployment/scripts directory.

    cd ~/ESS/deployment/scripts
    
  2. Change the permissions of the ./scripts/ess-restart.sh script, if needed.

    chmod +x ./scripts/ess-restart.sh
    
  3. 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

  1. 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>
    
  2. 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.