Orchesto installation

This guide provides a walk-through of the required steps to launch the Orchesto Data Management Solution.

Topics covered:

  • Prerequisits
    • Setting up a Postgres database
  • Starting Orchesto
    • Mandatory start flags
  • Installation on Linux
  • Installation in a Docker environment

Prerequisites

  • Access to the Orchesto customer portal at https://portal.orchesto.io/user/login
  • A license activation key for the Orchesto product, retrieved from the Customer Portal or other alternative distribution mechanism
    • Stored localy in a license activation file named license.json
  • The Orchesto binary or Docker image, suitable for your platform.

    • Download links available from Customer Portal
      • Linux binary: AMD, ARM64 or ARM32
      • Mac OS-X binary
      • Windows binary
    • Either use the donwload link in the portal to download locally, or pick the download link and use wget <URL> on the target machine.
    • A Docker image is available from Docker Hub * Requires that a Docker environment is running on the host
  • A Postgres database instance, accessible from the host running Orchesto

    • See the Postgres installation Appendix.
  • A write-back cache directory location, writable / owned by the user running the Orchesto instance

    • For a production environment perspective, consider redundancy, performance and scaleability
      • Do not use the same filesystem as "/"
      • A physical disk protected by RAID mirroring
      • LVM or equivalent to be able to expand or move the logical volume
    • Example: For a test setup when running Orchesto from the logged in users home dir.

      mkdir ~/wbc
      chmod 740 ~/wbc

  • The format of the license activation file (license.json) is as in the following example:

{
   "orchestoLicense": "HE954-E2D414-N64CA2-R45183-IASE0B-K0SSADD"    
}

Description of the Orchesto start flags

This can be used as a reference for starting Orchesto. Some flags are mandatory or optional, while others are just needed when starting Orchesto for the first time.

orchesto [FLAGS]

The FLAGS can be checked with orchesto --help

NAME:
  orchesto - Start object storage gateway.

DESCRIPTION:
  Orchesto is a Amazon S3 compatible object storage gateway.

USAGE:
  orchesto [FLAGS]

FLAGS:
  --listen value               Listen to address:port. An address may also be a hostname. Overrides listen value in config file.
  --conf-path value, -c value  Path to configuration directory. (default: "C:\\Users\\Zebware\\.orchesto")
  --dsn-file value             File containing PostgreSQL DSN that specifies the database to connect to (e.g postgres://user@localhost:5432/database)
  --wbc value                  Path to write cache directory
  --enable-edp                 Enable the use of event driven policies.
  --disable-edp                Disable the use of event driven policies.
  --tika-url value             Tika server URL (e.g http://localhost:9998/)
  --accept-eula                Accept the orchesto EULA
  --create-certificates        Create self issued endpoint certificates in the configuration directory. Will not overwrite existing certificate files. Ignored if --hostnames is used.
  --hostnames value            Comma separated list of hostnames. Orchesto will use Let's Encrypt to automatically obtain and refresh certificates for these hostnames (instead of certificate in config dir).
  --accept-le-sa               Accept current Let's Encrypt Subscriber Agreement, required to get automatically managed HTTPS certificates from Let's Encrypt.
  --version                    Print application version
  --fs-lockdown                Prevent the addition of new File System backends.
  --disable-fs-lockdown        Disable the File System lockdown.
  --activate value             Activate orchesto with a product license JSON file.
  --deactivate                 Deactivate the current orchesto product license and exit.
  --auto-deactivate            Deactivate the current license when the product exits.
  --renew                      Renew the lease on the current license.
  --license                    Print the current product license details and exit.
  --vault-config value         Path to JSON file containing vault settings.
  --help, -h                   show help

Mandatory start flags

  • --wbc <path> select a writable directory, to be used for the write-back cache
  • --dsn-file <path/file_name>A file containing the connection parameters to the Postgreql database instance

    • An example of the contents of the DSN-file:

      • postgres://orchesto:SecretPassword@localhost:5432/orchesto?sslmode=disable

      • With the following meaning:

        • database_type://User:Password@HostName:Port/Database_name?sslmode
  • The first time Orchesto is started, the flag --accept-eula and --activate <path/file-name> is needed, but can be excluded in later restarts

  • --conf-path <path> A path to the configuation directory. The default is a directory .orchesto in the users' home folder

Installation and starting Orchesto on Linux OS

  1. Place the Orchesto binary (file name = orchesto) in the user's home folder, or somwhere in the PATH environment, and make it executable
  2. Place the license activation file in the users home dir, or the configuration directory (see below)
  3. Follow the procedures to install the PostgreSQL database. either nativly in the host or as a Docker container (see apendix 2, Postgress Installation)
  4. Check the access to the Postgresql server
    • psql -h localhost -U orchesto -W -l NOTE: requires that the Postgres client packages are installed on the host
      • where -U is the database username configured i Postgres, -W will prompt for the password and -l will list existing databases
  5. Create the database connection file, named dsnFile
  6. Run the commands below to get started
    • Create directories for config and cache, owned by the user running the Orchesto gateway
mkdir ~/.orchesto
mkdir ~/wbc
  • Create the database connection file

echo "postgres://orchesto:SecretPassword@localhost:5432/orchesto?sslmode=disable" > dsnFile

  • Copy the config files to the config directory
cp license.json ~/.orchesto/license.json
cp dsnFile ~/.orchesto/dsnFile
  • Starting Orchesto for the first time

The first start will prepare the database and activate the license

orchesto --c ~/.orchesto  \
--wbc ~/wbc --dsn-file ~/.orchesto/dsnFile  \
--accept-eula --activate ~/.orchesto/license.json

Tip

This will start the Orchesto gateway in the foregound, showing the login credentials for the admin account.
Make a copy of the credentials to a safe place.

  • Press CTRL-C to kill the running Orchesto process

  • Subsequent launches of Orchesto Additional startflags can be added as described above. Or continue with the standard setings, follow this:

orchesto --c /home/orchesto/.orchesto  \
--wbc ~/wbc --dsn-file ~/.orchesto/dsnFile 

Installation and starting in a Docker environment

Note

The following description is valid if running the Docker environment in a Linux OS. Special considerations are needed for running a Docker environment on MAC OSX or Windows using the DockerDesktop
The major differences are related to sharing persistant volumes with the OSX/Windows OS rather than the docker host, and network configuration when multiple containers should share the same network in the same time as beeing accessible from the OSX/Windows OS.

Tip

The easiest way to run Docker containers in these OS'es is to launch a Linux Virtual machine using Virtual Box or Virtual PC, and follow the instructions below.

  1. The Postgres instance should already be installed and configured. (see Appendix 2, Postgres installation)
  2. Pull the Orchesto image
  3. Set up a persistent environment for the ORCHESTO docker environment
  4. Create the dsnFile and license.json file and copy to the persistent data directory
  5. Start the Orchesto docker instance once to activate the license and accept the EULA
  6. Restart the Orchesto instance

Pull the Docker image

sudo docker pull zebware/orchesto

  • Check the result
    sudo docker images

Create two persistent volumes for the Orchesto Docker instance

sudo docker volume create orchesto-data
sudo docker volume create orchesto-cache
  • The deafult location is /var/lib/docker/volumes/

Create the dsnFile for the Postgres connection

  • Check which connection parameters that are required for Your Postgres database
    • If following the examples in this guide, this is how a file named dsnFile shoud be created:
    • postgres://orchesto:SecretPassword@localhost:5432/orchesto?sslmode=disable
  • Copy the file to the Orchesto Docker persistant volume orchesto-data
    • sudo cp dsnFile /var/lib/docker/volumes/orchesto-data/_data/dsnFile

Create the license.json file for the Orchesto instance

  • The Prerequisites section in tis appendix describe how to get the license file from the Orchesto Customer portal.
    • sudo cp license.json /var/lib/docker/volumes/orchesto-data/_data/license.json

Start the Orchesto instance accepting the EULA and activate the license

Tip

If the postgres database is running as a container in the same Docker host, the containers need to be attached to the same Docker network. Add the following to connect the container via the Docker hosts network. It should be added on both the Orchesto and the Postgres containers.
--network host

  • Starting the Orchesto together with a Docker Postgres container in the same host
sudo docker run \
--network host \
--name orchesto-gateway \
-v orchesto-data:/root/.orchesto \
-v orchesto-cache:/root/wbc \
-p 9090:9090 \
zebware/orchesto \
--wbc /root/wbc \
--dsn-file /root/.orchesto/dsnFile  \
--activate /root/.orchesto/license.json \
--accept-eula
  • Starting Orchesto when the postgres database is NOT running as a Docker container in the same host
sudo docker run \
--name orchesto-gateway \
-v orchesto-data:/root/.orchesto \
-v orchesto-cache:/root/wbc \
-p 9090:9090 \
zebware/orchesto \
--wbc /root/wbc \
--dsn-file /root/.orchesto/dsnFile  \
--activate /root/.orchesto/license.json \
--accept-eula

Note

When starting the Orchesto container using the procedures described above, it will run in the foreground.
The reasson is that it will display the login credentials etc to be used when connecting to the Orchesto web gui console.

Orchesto Community Trial 1-5 Virtual Buckets running and accessible at:

  http://10.100.100.84:9090
  http://172.17.0.1:9090
  http://172.19.0.1:9090
  http://127.0.0.1:9090
  listening on all interfaces (0.0.0.0:9090)

------------------------------------------------------------
- TLS is disabled
    See http://docs.orchesto.io/2.0/2.0-tls/

- File System lockdown is disabled
    See http://docs.orchesto.io/2.0/3.0-multipoint-gateway/#filesystem


Admin user information:

  Username:            admin
  Access Key:          AIKAFFSHIJO3EJ60U0S1
  Secret Key/Password: BPF6peTk4ApehCR@ra+VyXXFSwseTlCDw@NA6T/h

┌────────────────────────────────────────────────────────┐
│                                                        │
│   CAUTION: These credentials are printed only once.    │
│            Make sure to save them somewhere safe.      │
│                                                        │
└────────────────────────────────────────────────────────┘

Stop the Orchesto container and start again in the bakground

Since the container is running in the forground, stop it with CTRL-C

Starting the Orchesto container

sudo docker container start orchesto-gateway

Stopping the Orchesto container

sudo docker container stop orchesto-gateway