Installing Studio on a Stand-Alone Server

This guide explains how to install SQream Studio on a stand-alone server. A stand-alone server is a server that does not run SQreamd based on binary, Docker, or Kubernetes.

This guide describes how to do the following:

Installing NodeJS Version 12 on the Server

Before installing Studio, you must install NodeJS version 12 on the server.

To install NodeJS version 12 on the server:

  1. Check if a version of NodeJS older than version 12.<x.x> has been installed on the target server.

    $ node -v
    

The following is the output if a version of NodeJS has already been installed on the target server:

bash: /usr/bin/node: No such file or directory
  1. If a version of NodeJS older than 12.<x.x> has been installed, remove it as follows:

    • On CentOS:

      $ sudo yum remove -y nodejs
      
    • On Ubuntu:

      $ sudo apt remove -y nodejs
      
  2. If you have not installed NodeJS version 12, run the following commands:

    • On CentOS:

      $ curl -sL https://rpm.nodesource.com/setup_12.x | sudo bash -
      $ sudo yum clean all && sudo yum makecache fast
      $ sudo yum install -y nodejs
      
    • On Ubuntu:

      $ curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
      $ sudo apt-get install -y nodejs
      

The following output is displayed if your installation has completed successfully:

Transaction Summary
==============================================================================================================================
Install  1 Package

Total download size: 22 M
Installed size: 67 M
Downloading packages:
warning: /var/cache/yum/x86_64/7/nodesource/packages/nodejs-12.22.1-1nodesource.x86_64.rpm: Header V4 RSA/SHA512 Signature, key ID 34fa74dd: NOKEY
Public key for nodejs-12.22.1-1nodesource.x86_64.rpm is not installed
nodejs-12.22.1-1nodesource.x86_64.rpm                                                                  |  22 MB  00:00:02
Retrieving key from file:///etc/pki/rpm-gpg/NODESOURCE-GPG-SIGNING-KEY-EL
Importing GPG key 0x34FA74DD:
 Userid     : "NodeSource <gpg-rpm@nodesource.com>"
 Fingerprint: 2e55 207a 95d9 944b 0cc9 3261 5ddb e8d4 34fa 74dd
 Package    : nodesource-release-el7-1.noarch (installed)
 From       : /etc/pki/rpm-gpg/NODESOURCE-GPG-SIGNING-KEY-EL
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
Warning: RPMDB altered outside of yum.
  Installing : 2:nodejs-12.22.1-1nodesource.x86_64                                                                        1/1
  Verifying  : 2:nodejs-12.22.1-1nodesource.x86_64                                                                        1/1

Installed:
  nodejs.x86_64 2:12.22.1-1nodesource

Complete!
  1. Confirm the Node version.

    $ node -v
    

The following is an example of the correct output:

v12.22.1

Back to Installing Studio on a Stand-Alone Server

Installing Studio

To install Studio:

  1. Copy the SQream Studio package from SQream Artifactory into the target server. For access to the Sqream Studio package, contact Sqream Support.
  1. Extract the package:

    $ tar -xvf sqream-acceleration-studio-<version number>.x86_64.tar.gz
    
  1. Navigate to the new package folder.

    $ cd sqream-admin
    
  1. Build the configuration file to set up Sqream Studio. You can use IP address 127.0.0.1 on a single server.

    $ npm run setup -- -y --host=<SQreamD IP> --port=3108
    

    The above command creates the sqream-admin-config.json configuration file in the sqream-admin folder and shows the following output:

    Config generated successfully. Run `npm start` to start the app.
    

    For more information about the available set-up arguments, see Set-Up Arguments.

  1. If you have installed Studio on a server where SQream is already installed, move the sqream-admin-config.json file to /etc/sqream/:

    $ mv sqream-admin-config.json /etc/sqream
    

Back to Installing Studio on a Stand-Alone Server

Starting Studio Manually

You can start Studio manually by running the following command:

$ cd /home/sqream/sqream-admin
$ NODE_ENV=production pm2 start ./server/build/main.js --name=sqream-studio -- start

The following output is displayed:

[PM2] Starting /home/sqream/sqream-admin/server/build/main.js in fork_mode (1 instance)
[PM2] Done.
┌─────┬──────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
│ id  │ name             │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
├─────┼──────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
│ 0   │ sqream-studio    │ default     │ 0.1.0   │ fork    │ 11540    │ 0s     │ 0    │ online    │ 0%       │ 15.6mb   │ sqream   │ disabled │
└─────┴──────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘

Starting Studio as a Service

Sqream uses the Process Manager (PM2) to maintain Studio.

To start Studio as a service:

  1. Run the following command:

    $ sudo npm install -g pm2
    
  1. Verify that the PM2 has been installed successfully.

    $ pm2 list
    

    The following is the output:

    ┌─────┬──────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
    │ id  │ name             │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
    ├─────┼──────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
    │ 0   │ sqream-studio    │ default     │ 0.1.0   │ fork    │ 11540    │ 2m     │ 0    │ online    │ 0%       │ 31.5mb   │ sqream   │ disabled │
    └─────┴──────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘
    
  1. Start the service with PM2:

    • If the sqream-admin-config.json file is located in /etc/sqream/, run the following command:

      $ cd /home/sqream/sqream-admin
      $ NODE_ENV=production pm2 start ./server/build/main.js --name=sqream-studio -- start --config-location=/etc/sqream/sqream-admin-config.json
      
    • If the sqream-admin-config.json file is not located in /etc/sqream/, run the following command:

      $ cd /home/sqream/sqream-admin
      $ NODE_ENV=production pm2 start ./server/build/main.js --name=sqream-studio -- start
      
  1. Verify that Studio is running.

    $ netstat -nltp
    
  2. Verify that SQream_studio is listening on port 8080, as shown below:

    (Not all processes could be identified, non-owned process info
     will not be shown, you would have to be root to see it all.)
    Active Internet connections (only servers)
    Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
    tcp        0      0 0.0.0.0:22              0.0.0.0:*               LISTEN      -
    tcp        0      0 127.0.0.1:25            0.0.0.0:*               LISTEN      -
    tcp6       0      0 :::8080                 :::*                    LISTEN      11540/sqream-studio
    tcp6       0      0 :::22                   :::*                    LISTEN      -
    tcp6       0      0 ::1:25                  :::*                    LISTEN      -
    
  1. Verify the following:

    1. That you can access Studio from your browser (http://<IP_Address>:8080).
    1. That you can log in to SQream.
  2. Save the configuration to run on boot.

    $ pm2 startup
    

    The following is an example of the output:

    $ sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u sqream --hp /home/sqream
    
  3. Copy and paste the output above and run it.

  1. Save the configuration.

    $ pm2 save
    

Back to Installing Studio on a Stand-Alone Server

Accessing Studio

The Studio page is available on port 8080: http://<server ip>:8080.

If port 8080 is blocked by the server firewall, you can unblock it by running the following command:

$ firewall-cmd --zone=public --add-port=8080/tcp --permanent
$ firewall-cmd --reload

Back to Installing Studio

Maintaining Studio with the Process Manager (PM2)

Sqream uses the Process Manager (PM2) to maintain Studio.

You can use PM2 to do one of the following:

  • To check the PM2 service status: pm2 list

  • To restart the PM2 service: pm2 reload sqream-studio

  • To see the PM2 service logs: pm2 logs sqream-studio

Back to Installing Studio on a Stand-Alone Server

Upgrading Studio

To upgrade Studio you need to stop the version that you currently have.

To stop the current version of Studio:

  1. List the process name:

    $ pm2 list
    

    The process name is displayed.

    <process name>
    
  1. Run the following command with the process name:

    $ pm2 stop <process name>
    
  1. If only one process is running, run the following command:

    $ pm2 stop all
    
  1. Change the name of the current sqream-admin folder to the old version.

    $ mv sqream-admin sqream-admin-<old_version>
    
  1. Extract the new Studio version.

    $ tar -xf sqream-acceleration-studio-<version>tar.gz
    
  1. Rebuild the configuration file. You can use IP address 127.0.0.1 on a single server.

    $ npm run setup -- -y --host=<SQreamD IP> --port=3108
    
The above command creates the sqream-admin-config.json configuration file in the sqream_admin folder.
  1. Copy the sqream-admin-config.json configuration file to /etc/sqream/ to overwrite the old configuration file.
  1. Start PM2.

    $ pm2 start all
    

Back to Installing Studio on a Stand-Alone Server

Installing Studio in a Docker Container

This guide explains how to install SQream Studio in a Docker container.

This guide describes how to do the following:

Installing SQream Studio in a Docker Container

If you have already installed Docker, you can install SQream Studio in a Docker container.

To install Sqream Studio in a Docker container:

  1. Copy the downloaded image onto the target server.
  1. Load the Docker image.

    $ docker load -i <docker_image_file>
    
  1. If the downloaded image is called sqream-acceleration-studio-5.1.3.x86_64.docker18.0.3.tar, run the following command:

    $ docker load -i sqream-acceleration-studio-5.1.3.x86_64.docker18.0.3.tar
    
  1. Start the Docker container.

    $ docker run -d --restart=unless-stopped -p <external port>:8080 -e runtime=docker -e SQREAM_K8S_PICKER=<SQream host IP or VIP> -e SQREAM_PICKER_PORT=<SQream picker port> -e SQREAM_DATABASE_NAME=<SQream database name> -e SQREAM_ADMIN_UI_PORT=8080 --name=sqream-admin-ui <docker_image_name>
    

    The following is an example of the command above:

    $ docker run -d --name sqream-studio  -p 8080:8080 -e runtime=docker -e SQREAM_K8S_PICKER=192.168.0.183 -e SQREAM_PICKER_PORT=3108 -e SQREAM_DATABASE_NAME=master -e SQREAM_ADMIN_UI_PORT=8080 sqream-acceleration-studio:5.1.3
    

Back to Installing Studio in a Docker Container

Accessing Studio

You can access Studio from Port 8080: http://<server ip>:8080.

If you want to use Studio over a secure connection (https), you must use the parameter values shown in the following table:

Parameter Default Value Description
--web-ssl-port 8443  
--web-ssl-key-path None The path of SSL key PEM file for enabling https. Leave empty to disable.
--web-ssl-cert-path None The path of SSL certificate PEM file for enabling https. Leave empty to disable.

You can configure the above parameters using the following syntax:

$ npm run setup -- -y --host=127.0.0.1 --port=3108

Back to Installing Studio in a Docker Container

Docker Container Commands

When installing Studio in Docker, you can run the following commands:

  • View Docker container logs:

    $ docker logs -f sqream-admin-ui
    
  • Restart the Docker container:

    $ docker restart sqream-admin-ui
    
  • Kill the Docker container:

    $ docker rm -f sqream-admin-ui
    

Back to Installing Studio in a Docker Container

Setup Argument Configurations

When creating the sqream-admin-config.json configuration file, you can add -y to create the configuration file in non-interactive mode. Configuration files created in non-interactive mode use all the parameter defaults not provided in the command.

The following table shows the available arguments:

Parameter Default Value Description
--web--host 8443  
--web-port 8080  
--web-ssl-port 8443  
--web-ssl-key-path None The path of the SSL Key PEM file for enabling https. Leave empty to disable.
--web-ssl-cert-path None The path of the SSL Certificate PEM file for enabling https. Leave empty to disable.
--debug-sqream (flag) false  
--host 127.0.0.1  
--port 3108  
is-cluster (flag) true  
--service sqream  
--ssl (flag) false Enables the SQream SSL connection.
--name default  
--data-collector-url localhost:8100/api/dashboard/data Enables the Dashboard. Leaving this blank disables the Dashboard. Using a mock URL uses mock data.
--cluster-type standalone (standalone or k8s)  
--config-location ./sqream-admin-config.json  
--network-timeout 60000 (60 seconds)  
--access-key None If defined, UI access is blocked unless ?ui-access=<access key> is included in the URL.