Skip to content

Latest commit

 

History

History
executable file
·
151 lines (113 loc) · 6.61 KB

install-guide.md

File metadata and controls

executable file
·
151 lines (113 loc) · 6.61 KB

Shuffle Logo

Shuffle Installation

Installation of Shuffle is currently available for docker and kubernetes.

This document outlines an introduction environment which is not scalable. Read here for information on production readiness and scalability. This also includes system requirements and configurations for Docker Swarm or Kubernetes.

Docker - *nix

The Docker setup is the default setup, and is ran with docker compose. This is NOT a scalable build without changes.

PS: if you're setting up Shuffle on Windows, go to the next step (Windows Docker setup)

  1. Make sure you have Docker installed, and that you have a minimum of 2Gb of RAM available.
  2. Download Shuffle
git clone https://github.com/Shuffle/Shuffle
cd Shuffle
  1. Fix prerequisites for the Opensearch database (Elasticsearch):
mkdir shuffle-database                    # Create a database folder
sudo chown -R 1000:1000 shuffle-database  # IF you get an error using 'chown', add the user first with 'sudo useradd opensearch'

sudo swapoff -a                           # Disable swap
  1. Run docker-compose.
docker-compose up -d
  1. Recommended for Opensearch to work well
sudo sysctl -w vm.max_map_count=262144             # https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html

When you're done, go to the After installation step below.

Windows with WSL

This step is for setting up with Docker on windows from scratch.

  1. Make sure you have Docker and docker-compose installed. WSL2 may be required.

  2. Go to https://github.com/frikky/shuffle/releases and download the latest .zip release (or install git)

  3. Unzip the folder and enter it

  4. Open the .env file and change the line with "OUTER_HOSTNAME" to contain your IP:

OUTER_HOSTNAME=YOUR.IP.HERE
  1. Run docker compose
docker compose up -d

Configurations (high availability, scale, proxies, default users etc.)

https://shuffler.io/docs/configuration

architecture

After installation

  1. After installation, go to http://localhost:3001 (or your servername - https is on port 3443)
  2. Now set up your admin account (username & password). Shuffle doesn't have a default username and password.
  3. Sign in with the same Username & Password! Go to /apps and see if you have any apps yet. If not - you may need to configure proxies
  4. Check out https://shuffler.io/docs/configuration as it has a lot of useful information to get started

Admin account setup

Useful info

  • Check out getting started
  • The default state of Shuffle is NOT scalable. See production setup for more info
  • The server is available on http://localhost:3001 (or your servername)
  • Further configurations can be done in docker-compose.yml and .env.
  • Default database location is in the same folder: ./shuffle-database

Local development installation

Local development is pretty straight forward with ReactJS and Golang. This part is intended to help you run the code for development purposes. We recommend having Shuffle running with the Docker-compose, then manually running the portion that you want to test and/or edit.

PS: You have to stop the Backend Docker container to get this one working

PPS: Use the "main" branch when developing to get it set up easier

Frontend - ReactJS /w cytoscape

http://localhost:3000 - Requires npm/yarn/your preferred manager. Runs independently from backend.

cd frontend
yarn install
yarn start

Backend - Golang

http://localhost:5001 - REST API - requires >=go1.13

export SHUFFLE_OPENSEARCH_URL="https://localhost:9200"
export SHUFFLE_ELASTIC=true
export SHUFFLE_OPENSEARCH_USERNAME=admin
export SHUFFLE_OPENSEARCH_PASSWORD=StrongShufflePassword321!
export SHUFFLE_OPENSEARCH_SKIPSSL_VERIFY=true
cd backend/go-app
go run main.go walkoff.go docker.go

WINDOWS USERS: Follow this guide to add environment variables in your machine.

Large portions of the backend is written in another repository - shuffle-shared. If you want to update any of this code and test in realtime, we recommend following these steps:

  1. Clone shuffle-shared to a local repository
  2. Open the Shuffle backend's go.mod file (./shuffle/backend/go.mod) (NOT in shuffle-shared)
  3. Change the following line to point to your directory AFTER the =>
//replace github.com/frikky/shuffle-shared => ../../shuffle-shared
  1. Make the changes you want, then restart the backend server!
  2. With your changes made, make a pull request 🔥

Database - Opensearch

Make sure this is running through the docker-compose, and that the backend points to it with SHUFFLE_OPENSEARCH_URL defined.

What it means:

  1. Make sure you have docker compose installed
  2. Make sure you have the docker-compose.yml file from this repository
  3. Run docker-compose up opensearch -d

Orborus

Execution of Workflows: PS: This requires some specific environment variables

cd functions/onprem/orborus
go run orborus.go

Environments (modify for Windows):

export ORG_ID=Shuffle
export ENVIRONMENT_NAME=Shuffle
export BASE_URL=http://YOUR-IP:5001
export DOCKER_API_VERSION=1.40

AND THAT's it - hopefully it worked. If it didn't please email frikky@shuffler.io