OCI Designer Toolkit Installation Guide

OCI Connection Information

If you already have the OCI sdk/cli installed on you machine you can use the previously generated pem key and config file we will assume that this exists in <USER HOME DIR>/.oci

Key File

If you do not have a previously generated private key you will need to create a private/public key pair for use with OKIT and OCI. These keys can be generated using the following commands as defined in Required Keys and OCIDs.

openssl genrsa -out <USER HOME DIR>/.oci/oci_api_key.pem 2048   
openssl rsa -pubout -in <USER HOME DIR>/.oci/oci_api_key.pem -out <USER HOME DIR>/.oci/oci_api_key_public.pem

Upload the generated oci_api_key_public.pem to OCI through the console and record the associated fingerprint following upload.

Config File

Create the OCI cli config file in the directory <USER HOME DIR>/.oci with contents similar to that below. The key_file is a fixed value because the contents of the <USER HOME DIR>/.oci will be mounted to the appropriate users home directory, as ~/.oci, during the run process.

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaak6z......
fingerprint=3b:7e:37:ec:a0:86:1....
key_file=~/.oci/oci_api_key.pem  
tenancy=ocid1.tenancy.oc1..aaaaaaaawpqblfem........
region=us-phoenix-1

Further information on the config file can be found on the OCI sdk page SDK and CLI Configuration File.

Git Connection

GIT Repositories File

If Git integration is required you will need to create a git_repositories file within the directory <USER HOME DIR>/.oci with contents similar to that below.

[OKIT Community Templates]
branch=main
url=git@github.com:username/okit-community-templates.git
  
[Example Repo]
branch = master
url = git@url1.git

[Internal]
branch = BRANCHNAME
url = git@url2.git

This properties file contains a list of the Git repositories you want to access. It assumes that you are using public/private key access and the key files exist within your <USER HOME DIR>/.ssh directory and the <USER HOME DIR>/.ssh/config defines the key/url mapping.

MacOS

Package Install

Install the following packages using Homebrew

brew install git
brew install python3
brew install libmagic

Install

export OKIT_DIR=${HOME}/okit
export OKIT_GITHUB_DIR=${HOME}/okit_github
export OKIT_BRANCH='master'
mkdir -p ${OKIT_DIR}
mkdir -p ${OKIT_GITHUB_DIR}
# Create Python Virtual Environment
python3 -m venv ${OKIT_DIR}/.venv
# Activate Virtual Environment
source ${OKIT_DIR}/.venv/bin/activate
# Update python modules
python3 -m pip install -U pip
python3 -m pip install -U setuptools
# Clone OKIT 
git clone -b ${OKIT_BRANCH} https://github.com/oracle/oci-designer-toolkit.git ${OKIT_GITHUB_DIR}/oci-designer-toolkit
# Install OKIT Required python modules
python3 -m pip install --no-cache-dir -r ${OKIT_GITHUB_DIR}/oci-designer-toolkit/requirements.txt
# Create OKIT Required Directories
mkdir -p ${OKIT_DIR}/{log,instance/git,instance/local,instance/templates/user,workspace,ssl}
# Link Directories
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/config ${OKIT_DIR}/config
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/okitweb ${OKIT_DIR}/okitweb
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/visualiser ${OKIT_DIR}/visualiser
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/okitweb/static/okit/templates/reference_architecture ${OKIT_DIR}/instance/templates/reference_architecture

Run

export OKIT_DIR=${HOME}/okit
export OKIT_LOGFILE=${OKIT_DIR}/log/okit.log
export PYTHONPATH=:${OKIT_DIR}/visualiser:${OKIT_DIR}/okitweb:${OKIT_DIR}
# Activate Virtual Environment
source ${OKIT_DIR}/.venv/bin/activate
# Run Server
${OKIT_DIR}/.venv/bin/gunicorn okitweb.wsgi:app --config ${OKIT_DIR}/config/gunicorn_http.py

Windows 10 / WSL (Ubuntu)

This installation procedure assumes you have previously installed Windows Subsystem for Linux 2.

Package Install

sudo apt install git
sudo apt install python3
sudo apt install libmagic-dev
sudo apt install python3-venv

Install

export OKIT_DIR=${HOME}/okit
export OKIT_GITHUB_DIR=${HOME}/okit_github
export OKIT_BRANCH='master'
mkdir -p ${OKIT_DIR}
mkdir -p ${OKIT_GITHUB_DIR}
# Create Python Virtual Environment
python3 -m venv ${OKIT_DIR}/.venv
# Activate Virtual Environment
source ${OKIT_DIR}/.venv/bin/activate
# Update python modules
python3 -m pip install -U pip
python3 -m pip install -U setuptools
# Clone OKIT 
git clone -b ${OKIT_BRANCH} https://github.com/oracle/oci-designer-toolkit.git ${OKIT_GITHUB_DIR}/oci-designer-toolkit
# Install OKIT Required python modules
python3 -m pip install --no-cache-dir -r ${OKIT_GITHUB_DIR}/oci-designer-toolkit/requirements.txt 
# Create OKIT Required Directories
mkdir -p ${OKIT_DIR}/{git,local,log,instance/git,instance/local,instance/templates/user,workspace,ssl}
# Link Directories
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/config ${OKIT_DIR}/config
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/okitweb ${OKIT_DIR}/okitweb
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/visualiser ${OKIT_DIR}/visualiser
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/okitweb/static/okit/templates/reference_architecture ${OKIT_DIR}/instance/templates/reference_architecture

Run

export OKIT_DIR=${HOME}/okit
export OKIT_LOGFILE=${OKIT_DIR}/log/okit.log
export PYTHONPATH=:${OKIT_DIR}/visualiser:${OKIT_DIR}/okitweb:${OKIT_DIR}
# Activate Virtual Environment
source ${OKIT_DIR}/.venv/bin/activate
# Run Server
${OKIT_DIR}/.venv/bin/gunicorn okitweb.wsgi:app --config ${OKIT_DIR}/config/gunicorn_http.py

Note: You may need to replace "localhost" in the OKIT URL with the IP Address of you WSL2 Virtual Machine.

Oracle Linux (OL8)

If you have a Linux machine and would like to install OKIT directly without the need for Docker or Vagrant then this can be achieved using the following simple instructions. We assume that you have already created the appropriate OCI SDK config file in, root users ~/.oci and associated ssh keys/config in ~/.ssh.

The instructions below give 2 options for the server either HTTP or HTTPS and it is up to the user to choose the appropriate command based on their requirements.

These instructions will install OKIT in the root directory /okit. If you would like OKIT in an alternative directory modify the OKIT_DIR environment variable. In addition the /etc/systemd/system/gunicorn.service and ${OKIT_DIR}/config/gunicorn_http*.py files will need to modified to reflect this new location.

NOTE: The service will run as root and hence will require the oci config and associated key files to be below roots home directory

export OKIT_DIR=${HOME}/okit
export OKIT_GITHUB_DIR=${HOME}/okit_github
export OKIT_BRANCH='master'
mkdir -p ${OKIT_DIR}
mkdir -p ${OKIT_GITHUB_DIR}
# Install Required Packages 
sudo bash -c "yum update -y"
sudo bash -c "yum install -y git"
sudo bash -c "yum install -y openssl"
sudo bash -c "yum install -y oci-utils"
# This is not required for OL8
sudo bash -c "yum install -y python-oci-cli"
# Update Python Modules
sudo bash -c "python3 -m pip install -U pip"
sudo bash -c "python3 -m pip install -U setuptools"
# Clone OKIT
git clone -b ${OKIT_BRANCH} https://github.com/oracle/oci-designer-toolkit.git ${OKIT_GITHUB_DIR}/oci-designer-toolkit
# Install OKIT Required python modules
sudo bash -c "python3 -m pip install --no-cache-dir -r ${OKIT_GITHUB_DIR}/oci-designer-toolkit/requirements.txt"
# Create OKIT Required Directories
mkdir -p ${OKIT_DIR}/{log,instance/git,instance/local,instance/templates/user,workspace,ssl}
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/config ${OKIT_DIR}/config
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/okitweb ${OKIT_DIR}/okitweb
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/visualiser ${OKIT_DIR}/visualiser
ln -sv ${OKIT_GITHUB_DIR}/oci-designer-toolkit/okitweb/static/okit/templates/reference_architecture ${OKIT_DIR}/instance/templates/reference_architecture
# Link to root level okit directory
sudo bash -c "ln -sv ${OKIT_DIR} /okit"
# Open Firewall
sudo firewall-offline-cmd  --add-port=80/tcp
sudo firewall-offline-cmd  --add-port=443/tcp
sudo systemctl restart firewalld
# Add additional environment information 
sudo bash -c "echo 'export OKIT_DIR=:${OKIT_DIR}' >> /etc/bashrc"
sudo bash -c "echo 'export PYTHONPATH=:${OKIT_DIR}/visualiser:${OKIT_DIR}/okitweb:/okit' >> /etc/bashrc"
sudo bash -c "echo 'export PATH=$PATH:/usr/local/bin' >> /etc/bashrc"
# Generate ssl Self Sign Key
sudo bash -c "openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${OKIT_DIR}/ssl/okit.key -out ${OKIT_DIR}/ssl/okit.crt -subj '/C=GB/ST=Berkshire/L=Reading/O=Oracle/OU=OKIT/CN=www.oci_okit.com'"

##################################################################################################################
#####                        If HTTPS / 443 Is required                                                      #####
##### Copy GUnicorn Service File (HTTPS)                                                                     #####
##################################################################################################################
sudo bash -c "cp -v ${OKIT_GITHUB_DIR}/oci-designer-toolkit/containers/services/gunicorn.https.service /etc/systemd/system/gunicorn.service"
##################################################################################################################
#####                        If HTTP / 80 Is required                                                        #####
##### Copy GUnicorn Service File (HTTP)                                                                      #####
##################################################################################################################
sudo bash -c "cp -v ${OKIT_GITHUB_DIR}/oci-designer-toolkit/containers/services/gunicorn.http.service /etc/systemd/system/gunicorn.service"

# Enable Gunicorn Service
sudo systemctl enable gunicorn.service
sudo systemctl start gunicorn.service
sudo systemctl status gunicorn.service

Container

Docker / Rancher Desktop

The docker image can be built and started using the scripts in the docker sub directory. It should be noted that the current Docker script is designed for development purposes and mounts the source directories at runtime.

Prerequisites

Install Docker Desktop or Rancher Desktop.
Create local directory ~/okit/user/templates for storage of custom templates.
Copy Config & Key Files

Docker Build

cd oci-designer-toolkit
docker build --tag okit --file ./containers/docker/Dockerfile --force-rm .

Docker Update

cd oci-designer-toolkit
docker rmi okit
docker build --tag okit --no-cache --file ./Dockerfile --force-rm .

Start Docker Container

cd oci-designer-toolkit
docker run -d --rm -p 80:80 
        --name okit \
        --hostname okit \
        --volume <USER HOME DIR>/.oci:/root/.oci \
        --volume <USER HOME DIR>/.ssh:/root/.ssh \
        --volume <PATH TO USER TEMPLATES DIR>:/okit/instance/templates/user \
        --volume <PATH TO GIT DIR>:/okit/instance/git \
        --volume <PATH TO LOCAL DIR>:/okit/instance/local \
        okit

Quick Start Runtime

Docker is the recommended runtime container for OKIT and the project contains a top-level Dockerfile to facilitate direct building, of the runtime environment, from the docker command line.

Build Docker Container

docker build --tag okit --no-cache --force-rm https://github.com/oracle/oci-designer-toolkit.git

Run Container

docker run -d --rm -p 80:80 --volume <USER HOME DIR>/okit/user/templates:/okit/templates --volume <USER HOME DIR>/.oci:/root/.oci --volume <USER HOME DIR>/.ssh:/root/.ssh --name okit okit

Once started the Designer BUI can be accessed on http://localhost/okit/designer

Lima (MacOS)

Lima is an alternative option to Docker Desktop to run a container based OKIT installation on MacOS. It will build a container based on the existing Dockerfile without any modifications.

Install Lima using Homebrew

brew install lima

Lima runs a Linux VM in the background that is used for running the containers, to start the Lima VM service run

limactl start

Lima uses containerd as its container run-time and nertctl as the Docker-compatible CLI for containerd. As containerd is running in the VM, not on the Mac directly the lima command passes the nerdctl commands to the VM.
For most docker commands the equivalent is to run lima nerdctl

With Lima installed and running we need to build the OKIT container, replacing the regular docker build with

cd oci-designer-toolkit
lima nerdctl rmi okit
lima nerdctl build --tag okit --no-cache --file ./Dockerfile .

Run OKIT using the container run command, adjust or add additional required volume mounts as required

lima nerdctl run --rm -p 80:80 \
        --name okit \
        --hostname okit \
        --volume <USER HOME DIR>/.oci:/root/.oci \
        --volume <USER HOME DIR>/.ssh:/root/.ssh \
        --volume <PATH TO USER TEMPLATES DIR>:/okit/instance/templates/user \
        --volume <PATH TO GIT DIR>:/okit/instance/git \
        --volume <PATH TO LOCAL DIR>:/okit/instance/local \
        okit

To stop the OKIT container

lima nerdctl stop okit

To stop the Lima service VM

limactl stop

Vagrant / VirtualBox

Prerequisites

Install Oracle VM VirtualBox
Install Vagrant
Create local directory ~/okit/user/templates for storage of custom templates.
Copy Config & Key Files

Vagrant Build

MacOS / Linux

cd oci-designer-toolkit/containers/vagrant
vagrant up; vagrant reload; vagrant ssh

Windows

cd oci-designer-toolkit\containers\vagrant
vagrant up & vagrant reload & vagrant ssh

NOTE: This step takes about 30 minutes on my mac when you build the VM, a little longer the first time as the Vbox image is downloaded from github. Once the VM is built the vagrant up should just take a few seconds.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Installation.md

Installation.md

OCI Designer Toolkit Installation Guide

Table of Contents

OCI Connection Information

Key File

Config File

Git Connection

GIT Repositories File

MacOS

Package Install

Install

Run

Windows 10 / WSL (Ubuntu)

Package Install

Install

Run

Oracle Linux (OL8)

Container

Docker / Rancher Desktop

Prerequisites

Docker Build

Docker Update

Start Docker Container

Quick Start Runtime

Build Docker Container

Run Container

Lima (MacOS)

Vagrant / VirtualBox

Prerequisites

Vagrant Build

MacOS / Linux

Windows

Files

Installation.md

Latest commit

History

Installation.md

File metadata and controls

OCI Designer Toolkit Installation Guide

Table of Contents

OCI Connection Information

Key File

Config File

Git Connection

GIT Repositories File

MacOS

Package Install

Install

Run

Windows 10 / WSL (Ubuntu)

Package Install

Install

Run

Oracle Linux (OL8)

Container

Docker / Rancher Desktop

Prerequisites

Docker Build

Docker Update

Start Docker Container

Quick Start Runtime

Build Docker Container

Run Container

Lima (MacOS)

Vagrant / VirtualBox

Prerequisites

Vagrant Build

MacOS / Linux

Windows