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:

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:

  1. To install Homebrew, follow the instructions at https://brew.sh/.

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

Installation

Step 1: Start Kubernetes Cluster

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

  1. Open a Terminal window.

  2. Start Minikube with the recommended resources.

    minikube start --vm-driver=virtualbox --cpus 4 --memory 8192 --disk-size=50GB
    
  3. 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
    
  4. 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
    
  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:

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

  1. Find the IP address of the Minikube VM:

    minikube ip
    

    The operation should return your Minikube IP Address.

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

  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

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>
    

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.