Skip to main content

Hosting your own SA Studio Environment

This is a step-by-step guide that explains how to get an SA Studio Environment up and running on a Linux machine as systemd services with secure TLS communication and external access through HTTPS. The Linux machine can either be located on premises or in your proprietary cloud.

Requirements

For this guide to work you need the following:

  1. Download sas_config_v3.tar.gz with the SA Server configuration files. The compressed package contains the following files (referred to as the sas_config_files):

    README.md
    nginx/
    nginx/nginx.conf
    sa.server.service
    sa.studio.service
    sas_config.osql
    sas_config.sh

    The sa.*.service files are systemd service specification files, and the sas_config.* files are for configuring TLS certificates and starting the SA Studio and SA Server instances with the correct parameters.

  2. Ensure that you have administrative rights for your firewall and DNS settings for the subdomain on which you wish to run the services.

You can download a tarball with these files from https://assets.streamanalyze.com/sas_config/sas_config_v3.tar.gz

Running SA Studio Environment as systemd services​

  1. Put the files sa.server.service, sa.studio.service, sas_config.osql, and sas_config.sh in a local folder on the linux machine.

    For example:

    /home/<user>/sas_config/
        README.md
        nginx/
        nginx/nginx.conf
        sa.server.service
        sa.studio.service
        sas_config.osql
        sas_config.sh

  2. Download and unpack sa_engine_linux_x64_prebuilt.tar.gz from https://studio.streamanalyze.com/download/#tlinux.

  3. Set environment variable SA_ENGINE_HOME for the user that will be running the service to the path where the sa.engine folder you unpacked is located (include the sa.engine folder in the path).

    For example:

    export SA_ENGINE_HOME=/home/<user>/sa.engine

    Alternatively you can alter sas_config.sh to set SA_ENGINE_HOME there. The same goes for all configuration variables.

  4. Know what public IP or DNS name the server will be reachable on.

  5. Set the environment variable SA_HOSTNAME to the public IP address.

    For example:

    export SA_HOSTNAME=123.123.123.123

  6. Decide what folder you want SA_HOME to be by setting environment variable SA_HOME.

    For example:

    export SA_HOME=/home/<user>/SA

  7. Generate a secret for authentication with your federation and set the environment variable SA_FEDERATION_AUTH_SECRET to this secret.

    For example:

    export SA_FEDERATION_AUTH_SECRET=a_long_secret_string

  8. Generate cryptographic certificates for communication between SA Engine instances, including edge devices:

    cd /home/<user>/sas_config
    ./sas_config.sh gen_cert

    You should now have a folder ${SA_HOME}/tls with certificates and keys.

  9. Replace all placeholders in sa.server.service and sa.studio.service with correct values.

    PlaceholderDescription
    <path-to-sas-config-files>The full path to the folder where you unpacked the sas_config_files, e.g., /home/<user>/sas_config/.
    <path-to-sa-home>The full path to SA_HOME, e.g., /home/<user>/SA.
    <desired-user>The user you want to run the services.
    <public-address>The public address (IP or hostname) of the machine.
    <path-to-sa.engine>The full path to SA_ENGINE_HOME, e.g., /home/<user>/sa.engine.

  1. Install services sa.server.service and sa.studio.service:

    cd /home/<user>/sas_config
    sudo systemctl link $(pwd)/sa.server.service
    sudo systemctl link $(pwd)/sa.studio.service

  2. Reload daemon and enable services:

    sudo systemctl daemon-reload
    sudo systemctl enable sa.server.service     # make service start on boot
    sudo systemctl enable sa.studio.service
    sudo systemctl start sa.server.service      # start service right now
    sudo systemctl start sa.studio.service
    Troubleshooting

    If for some reason the services does not start you can check their logs with journalctl

    journalctl -u sa.server.service

    journalctl -u sa.studio.service

  3. Verify that services were started:

    sudo systemctl status sa.server.service
    sudo systemctl status sa.studio.service

  4. Verify that you can access SA Studio by opening up a web browser on the machine and typing in the URL localhost:3001.

    Firewall

    Remember to open up port 3001 for incoming TCP traffic. If you wish to connect edge devices to your server you also need to open port 35021 for incoming TCP traffic.

The SA Studio Environment now use TLS encryption for communication between SA Engine instances, including edge devices. Next we will enable HTTPS so external browsers can communicate safely with SA Studio.

Enabling HTTPS on the studio server​

To enable HTTPS, SA Studio requires a server key, a CA certificate and a server certificate signed by the CA. If you already have that, or if you wish to use the same certificates generated for the SA Federation, you can skip to Step 3 below.

Step 1 - Make an entry in the DNS​

To enable HTTPS you first need to add a subdomain for the machine in the DNS. In this guide we use Amazon Route 53 for DNS configuration.

This guide shows how to generate SSL certificates using SSL For Free. This assumes that you have DNS admin rights to your subdomain -- to the extent that SSL For Free is able to verify ownership.

If you don't have such admin rights, you can still generate SSL keys for your HTTPS using other tools than SSL For Free. However, if your server certificate is not signed by an official CA, your browser will show certificate warnings.

Note that your SA Studio instance does not have to be reachable on the internet. SSL For Free just needs to verify domain ownership using e.g. DNS or email as described below.

  1. Go to your hosted zones in Route 53, select the "Records" tab and click the "Create record" button.

    Step_0-1_Route_53_DNS_config.png

  2. In the "Choose routing policy" dialog that appears, select "Simple routing" and click "Next".

    Step_0-2_Simple_record.png

  3. In the "Define simple record" dialog, write the name of your subdomain, select record type "A" and write the public IP address in the "IP address or another value..." textbox. Finalize the record setup by clicking the "Define simple record" button.

    Step_0-3_Specify_A_record.png

You should now have a DNS record that you can use for your SSL certificate.

Step 2 - Generate a certificate for the subdomain​

Now we are going to generate an SSL certificate for the subdomain we set up in the previous step. In this guide we use SSL For Free to generate a free ZeroSSL certificate.

  1. Go to sslforfree.com, type in the name of your subdomain and click the "Create Free SSL Certificate" button.

    Step_1-1_Go_to_sslforfree.com.png

  2. In the dashboard, click the "New Certificate" button.

    Step_1-2_create_certificate.png

  3. In the "New Certificate" dialog that appears there are four separate steps to complete.

    1. Domains: Enter the subdomain from the DNS record (and click the "Next Step" button).

      Step_1-3_new_certificate.png

    2. Validity: Choose 90 days validity.

    3. CSR & Contact: Select "Auto-generate CSR".

    4. Finalize Your Order: Select the free tier and click the "Next Step" button.

      Step_1-4_Finalize.png

  4. Now you need to verify the ownership of your domain. This will require you to add a CNAME record to your DNS. In this step we will illustrate how to do this by switching back-and-forth between SSL For Free and Route 53. Ensure you keep each of them open in a separate tab to enable easy copying and pasting between them.

    1. In the "Verify Domain" dialog that appeared after previous step, select the "DNS (CNAME)" option. This provides you with a CNAME record that you need to add to your DNS. Keep this dialog open and do not click the "Next Step" button before you have added the record to your DNS.

      Step_1-5_DNS_CNAME.png

    2. Go to Route 53 and click the "Create record" button (just like you did when you added the DNS record).

    3. Select "Simple routing".

    4. In the "Define simple record" dialog:

      • Set "Record name" to the value from "Name" in the "Verify Domain" dialog in the SSL For Free tab.

      • Choose CNAME as record type

      • Choose "IP address or another value" under "Value/Route traffic to".

      • In the textbox under "IP address or another value" you paste the value from "Point To" in the "Verify Domain" dialog in the SSL For Free tab.

      • Finish the definition by clicking the "Define simple record" button.

        Step_1-6_CNAME_record.png

    5. In the "Configure records" dialog that appears, create the record you have just defined by clicking the "Create records" button.

      Step_1-7_CNAME_record_created.png

    6. Go back to the "Verify Domain" dialog in the SSL For Free tab and go to "Finalize" by clicking the "Next Step" button.

    7. Verify your subdomain by clicking the "Verify Domain" button. This will contact the domain and verify that it redirects to the right URL.

      Step_1-9_automatic_domain_verification.png

  5. Now that you have verified your domain a "Install Certificate" dialog will appear. Here you download your certificate as a .zip file by selecting "Default Format" in the drop-down list and click the "Download Certificate (.zip)" button. The other steps in the dialog ("Install Certificate" and "Installation Complete") are not required.

    Step_1-10_verification_success_download_cert.png

    The .zip file should contain the following files:

    ca_bundle.crt
    certificate.crt
    private.key

Step 3 - Configure SA Studio to use SSL​

This section details how you can communicate securely with SA Studio using SSL. It can be done in one of two ways:

  • Alternative 1: Setup SSL-communication with SA Studio startup parameters.

  • Alternative 2: Setup SSL-communication with the third-party tool NGINX.

Alternative 1 - Enable SSL communication with SA Studio startup parameters​

If you created certificates according to step 2 above. Copy the downloaded certificate .zip file to the machine that runs SA Studio and Unzip it and put the files in ${SA_ENGINE_HOME}/visual_analyzer/webssl/.

  1. Update sas_config.sh to start SA Studio with HTTPS. This is done by replacing the existing call to node index.js near the bottom of the file from

    node index.js -csvoc=0 \
       -lisp="(load-osql \"${SCRIPTPATH}/sas_config.osql\")" \
       -lisp='(osql "configure_security()")' \
       -lisp='(cd (sa-home))' \
       -conStr=node@localhost -p=3001

    to

    node index.js -csvoc=0 \
        -ca=${SA_ENGINE_HOME}/visual_analyzer/webssl/ca_bundle.crt \
        -key=${SA_ENGINE_HOME}/visual_analyzer/webssl/private.key \
        -cert=${SA_ENGINE_HOME}/visual_analyzer/webssl/certificate.crt \
        -httpsPort=3002 \
        -lisp="(load-osql \"${SCRIPTPATH}/sas_config.osql\")" \
        -lisp='(osql "configure_security()")' \
        -lisp='(cd (sa-home))' \
        -conStr=node@localhost -p=3001
    Using the self signed certificates for the SA Federation services.

    To use the self signed certificates for the SA Federation service you can simply point to the files under ${SA_HOME}/tls/:

    node index.js -csvoc=0 \
        -ca=${SA_HOME}/tls/ca.crt \
        -key=${SA_HOME}/tls/private.key \
        -cert=${SA_HOME}/tls/cert.crt \
        -httpsPort=3002 \
        -lisp="(load-osql \"${SCRIPTPATH}/sas_config.osql\")" \
        -lisp='(osql "configure_security()")' \
        -lisp='(cd (sa-home))' \
        -conStr=node@localhost -p=3001

  1. Open port 3002 in your firewall and close port 3001.

  2. Restart the SA Studio service.

    sudo systemctl restart sa.studio.service

Alternative 2 - Enable SSL-communication via NGINX​

Notice!

If you tried alternative 1 above you need to undo your changes before trying this alternative.

  1. Install NGINX on the machine that runs SA Studio.

    sudo apt update
    sudo apt install nginx

  2. Copy and unzip the downloaded certificate .zip file into /home/<user>/sas_config/nginx.

    Using the self signed certificates for the SA Federation services.

    The certificate generation routine has already created the merged file. It is copied into your sas_config/nginx dir cert_and_ca.crt You can also skip step 3. below.

  3. The SSL configuration of NGINX requires your CA-bundle and certificate files to be merged.

    cat certificate.crt ca_bundle.crt >> cert_and_ca.crt

  1. Edit the default NGINX-configuration file nginx.conf (in <path-to-sas-config-files>/nginx/) and replace the following placeholders:

    PlaceholderDescription
    <sa-studio-public-port>The public port where SA Studio will be accessed, e.g., 3002.
    <path-to-cert>The absolute path to the previously created certificate file cert_and_ca.crt, e.g., /home/sa/sas_config/nginx/cert.crt.
    <path-to-private-key>The absolute path to the the private key file private.key, e.g., /home/sa/sas_config/nginx/private.key
    <sa-studio-internal-port>The port of the running SA Studio instance, e.g., 3001.
    <sa-server-port>The port of the running SA sever instance, e.g., 35021.
    <path-to-sa-home>The path to SA_HOME set in previous steps

  1. Ensure that <sa-studio-public-port> is open for incoming traffic in your firewall.

  2. Reload NGINX

    sudo nginx -s stop
    sudo nginx -c <path-to-sas-config-files>/nginx/nginx.conf

  3. If you are using another port than 3002 for the <sa-studio-public-port> you'll need to update the line in sas_config.sh that sets SA_ADDRS:

    ```bash
    export SA_ADDRS=${SA_HOSTNAME}:3002
    ```
    You'll also need to restart the services:
    ```bash
    sudo systemctl restart sa.server.service
    sudo systemctl restart sa.studio.service
    ```

Step 4 - Verify that you can access SA Studio through HTTPS​

  1. Open a browser and go to the URL https://<your_subdomain>:3002.

    Step_2-1_go_to_https_URL.png

  1. Check that the padlock next to the URL is locked and click it to check that the connection is secure and that the certificate is valid. In the screen shots we use Chrome, but any modern browser should show icons with similar functionality.

    Step_2-2_verify_security.png
    Notice

    When using the self signed certificates the padlock will not be valid.

  2. You can click on "Certificate is valid" to get more information about the certificate.

    Step_2-3_Certificate_information.png

That is it, you now have access to SA Studio through HTTPS with a valid SSL certificate.

(Optional) Only allow authenticated users to access SA Studio​

If you have setup SSL with NGINX according to Step 3 (Alt. 2) above you can easily add basic authentication to only allow authenticated users to access your SA Studio instance.

  1. Install htpasswd in apache2-utils

    sudo apt install apache2-utils

  2. Create a new htpasswd-file with the initial user credentials

    cd /home/<user>/sas_config/nginx
    sudo htpasswd -c ./.htpasswd <username>

    To create more users, omit the -c file.

    sudo htpasswd ./.htpasswd <username>

  3. Add the following content to the nginx.conf file (in /home/<user>/sas_config/nginx/), replacing placeholders with correct values.

    PlaceholderDescription
    <path-to-htpasswd-file>The absolute path to the .htpasswd-file, e.g., /home/<user>/sas_config/nginx/.htpasswd.
    ...
    location ~ ^.*$ {
        proxy_pass http://localhost:3001;
        auth_basic              "Authentication required";
        auth_basic_user_file    /home/ubuntu/sas_config/nginx/.htpasswd;
      }

  4. Reload NGINX

    sudo nginx -s stop
    sudo nginx -c <path-to-sas-config-files>/nginx/nginx.conf

  5. Verify that you get a basic authentication prompt when you try to access https://<your-hostname>:<your-public-port>.