Introduction

This document is for designed for all those deploying a self-hosted instance of statscloud on a server following a licence agreement with us. It will guide you through the requirements for hosting the application, the installation process, and how to configure the application for your needs.

Deploying your own instance of statscloud is designed to be as simple as possible and requires only a basic understanding of terminal commands. Because the server does not involve any high-level statistical computations (these are computed on the client), the demands of running the application are also very small; a single server would suffice for hosting an application for a fairly large (e.g., 1000) number of users.

Requirements

To deploy statscloud, we would recommend a Linux-based machine (e.g., Ubuntu v20.04) with a minimum of 2Gb RAM and a single CPU core.

The base files for deploying statscloud are very small (approximately 25Mb in total), but we would suggest allowing plenty of space for the database file. For this, we would generally suggest storage space of approximately 32Mb per user. Of course, you can adjust this based on your use case.

For reference, a typical CSV file with 1000 rows and 500 columns would be approximately 50-100Kb on disk, and statscloud will store roughly this (with a small overhead) for a project of this size.

Preparation

To install statscloud, you wil need the following key files and folders (provided to you as part of your licence agreement):

File	Description
statscloud-server	The binary used to run the statscloud server
config/default.yml	A configuration file to set up the instance of statscloud
ui/	A folder containing the static assets for the user-interface of statscloud

You should copy all of these files to your server maintaining the following folder structure:

statscloud
├── config
│   ├── default.yml
├── ui
│   ├── [ ui folder content ]
└── statscloud-server

Once all of these files are in place, you can simply start the statscloud server by running the following command from the root statscloud folder:

$ statscloud-server --config config

If you navigate to http://localhost:8080, you'll find your instance of statscloud is now up and running!

You can perform a (graceful) shutdown of the server at any time by using your terminal's 'stop' command (CTRL + C).

Database (data.statscloud)

When you run statscloud-server for the first time, a new file will be created in the root statscloud directory: data.statscloud. When the file is created, your folder structure should now look like this:

statscloud
├── config
│   ├── default.yml
├── ui
│   ├── [ ui folder content ]
└── statscloud-server
└── data.statscloud # < -- New file added

The data.statscloud file is an SQLite file and contains the entire database used by the application (including user information, user-interface configurations, all users projects, and all data associated with them).

We would strongly encourage you to keep this file stored on the same server as the server binary. While it may technically be possible to store the database file on a separate server, this is not something we would recommend. SQLite is not designed for network access (as it doesn't have a built-in network protocol). This may cause latency issues too, so you'll get the best performance from the app by hosting it local to the server binary.

Backing up your database

Please note that you will be responsible for creating your own backups of the data.statscloud file and can do so at your convenience using your preferred method.

Forunately, having a single file for the database means that backing up the database for your application should be quite straightforward. The data.statscloud file can be backed up (even while in use) by using a command like this:

sqlite3 statscloud.data ".backup 'statscloud.data.backup'"

For more guidance on backing up an SQLite database, please see this thread.

Configuration

Before deploying your instance of statscloud to your users widely, there are some important configurations that should be made to your deployment. These can be found in the default.yml file. The contents of this file appears as follows:

port: 8080
address: 127.0.0.1
base_url: http://localhost:8080/
admin_token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
data: ../data.statscloud
static_files: ../ui/
license_key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
license_server:
  url: https://licence.statscloud.app
oauth: {}

As you can see, this file provides some fundamental information on how the instance of statscloud should run on your server. The attribute names should be quite self-explanatory, but a brief summary of these is provided for your reference below:

Attribute	Description
port	The designated port running the statscloud UI
address	The designated address running the statscloud UI
base_url	The designated base URL running the statscloud UI
admin_token*	The master password by the admin superuser
data	The path to the statscloud database file
static_files	The path to the statscloud UI folder
license_key*	The 32-character licence key that was provided to as part of the licence agreement
license_server: url	The address of the statscloud licence server
oauth*	Configuration options for OAuth providers. Please see the section on OAuth below for more details

Mostly, this file will not need editing and the values should remain as they are. However, there are some important changes that should be made to this file before deploying more widely to your users, as summarised below:

Admin token (admin_token)

This is the master password your admin superuser will use to log into the user-interface to set up your instance. We will provide an initial password for you, but you can change this value to any strong password that only you and your administrative team have access to.

Licence key (license_key)

This is the licence key that would have been provided to you as part of your licence agreement. This is a 32-character string in the format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. You will need to ensure this is entered correctly in order for your instance of statscloud to function.

OAuth (oauth)

Using OAuth in your application is optional. If you do not need to use OAuth in your instance of statscloud, you can simply keep this value as it is ({}). If, however, you would like to make use of OAuth services to facilitate user logins, you can provide that information here.

Note: if you provide details for OAuth services, these will be displayed on the login screen in the user-interface underneath the main 'Login' button.

oauth:
  github:
    type: github
    client_id: x123
    client_secret: x456
  google:
    type: google
    client_id: x123
    client_secret: x456
  myopenidprovider:
    type: openid
    client_id: x123
    client_secret: x456
    scope:
      - openid
      - profile
      - email

Setting up

Now that your instance of statscloud has been set up, you can now log into statscloud as an admin superuser to set up your instance through the user-interface. To make the setup as simple as possible, we have created a user-friendly wizard that will guide you through this process.

http://localhost:8080/setup.

You can enter your Admin token into this field to begin the process. The wizard will help you add and set up your users, and set up options in the user-interface for all users on your instance. For more information on this, please see the Setting up your instance of statscloud article

Running statscloud behind an HTTP proxy

It is strongly recommended to serve statscloud over HTTPS to properly secure user requests and responses. The simplest way to do this is to run statscloud behind an HTTP proxy (i.e., nginx), which can be configured to support TLS (among many other things).

To install nginx, you can use the following commands:

$ sudo apt-get update
$ sudo apt-get install nginx

You should then edit the nginx cofiguration file (usually /etc/nginx/sites-available/default) using a text-editing app such as nano:

$ sudo nano /etc/nginx/sites-available/default

You should then see a file that looks similar to text below. You should replace statscloud.your-domain.com with your full domain name.

server {
    listen 80;
    server_name statscloud.your-domain.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header 
 X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Note: In accordance with the licence agreement, you must ensure that any public domain hosting your instance of statscloud contains the phrase "statscloud" in the URL. Ideally, this would be simply be your domain with 'statscloud' as the the subdomain (e.g., statscloud.your-domain.com).

Next, you should create a symbolic link to the nginx configuration file in the /etc/nginx/sites-enabled directory:

$ sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/

You should then check nginx for any possible errors using the following command:

$ sudo nginx -t

If no errors are found, you can then restart nginx with the following command:

$ sudo systemctl reload nginx

Finally, you will need to edit the DNS records from your registrar to ensure that this domain points to the public IP address of your Linux server.

SSL/TLS Certification

If you require an SSL certificate for your domain, we would recommend using a tool such as Let's Encrypt to obtain this. You can then configure nginx to use HTTPS.

To install and configure an SSL certificate, we would recommend using certbot. To install certbot, simply run the following commands:

$ sudo apt-get update
$ sudo apt-get install certbot

You can then run the following command to obtain an SSL certificate for your domain (being sure to replace your_domain.com with your own domain name).

$ sudo certbot --nginx -d your_domain.com

Certbot will automatically configure nginx to use this SSL certificate, but you can view the changes made to your file by viewing the /etc/nginx/sites-available/your_domain.com file. For reference, it should appear like the following:

server {
    listen 80;
    server_name your_domain.com;
    return 301 https://<span class="katex"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>h</mi><mi>o</mi><mi>s</mi><mi>t</mi></mrow><annotation encoding="application/x-tex">host</annotation></semantics></math></span>request_uri;
}

server {
    listen 443 ssl;
    server_name your_domain.com;

    ssl_certificate /etc/letsencrypt/live/your_domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your_domain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'EECDH+AES128:EECDH+AES256:ECDH+AES128:ECDH+AES256:DHE-RSA-AES128:DHE-RSA-AES256';
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://localhost:8080;
        # ... other proxy settings ...
    }
}

Finally, just restart nginx again using the following command:

$ sudo systemctl reload nginx

By using certbot, your SSL certificate should renew automatically before it expires.

Support

If you encounter any issues with your deployment of statscloud, please feel free to get in touch with the team at contact@statscloud.app.