Stand-Alone

Both the Community Edition (CE) and Enterprise Edition (EE) versions of RegScale can be installed in stand-alone mode. What this means is that the application can be installed on a single machine; whether laptop, desktop, Virtual Machine (VM), or physical server.

This version is perfect for test and evaluation, small businesses, individual auditors, or other use cases where high availability and scalability are not requirements for the system.

This document provides installation files and instructions for deploying RegScale in stand-alone mode.

Local Docker

RegScale created a convenient and straightforward way to run RegScale locally, even without connecting to a remote database. This guide will allow a customer to spin up a local SQL container, connect to the database, initialize the database, and run RegScale; all within their stand-alone environment (laptop, desktop, or VM). This approach allows our customers to quickly and easily test and evaluate the product without external dependencies on infrastructure (which can take a long time to provision in Enterprise environments) and with no up-front costs for the evaluation.

NOTE: Stand-alone RegScale can also be used for Production purposes but RegScale recommends installing a production grade SQL Server database on a separate machine/environment.

In order to setup the stand-alone environment, the customer should take the following steps:

Pre-requisites

You need to have Docker and Docker Compose installed; the free version of Docker Desktop is sufficient
- We recommend installing on Ubuntu using the Docker Installation Guide and Docker Compose Installation Guide
You need to have a user account and access to Docker Hub to pull the image
You can review the docker container here: RegScale Docker Hub
- If you want to test, you can manually pull the image (NOTE: We recommend pulling the latest image from the repository):
```
docker pull regscale/regscale:latest
```

Architecture

Stand Alone Architecture

The overall components of this architecture are described below:

RegScale Core Platform - Linux Docker Container that runs on a Virtual Machine (VM) based on Red Hat Enterprise Linux (RHEL) or Ubuntu. It can also be installed locally on a Mac laptop or Windows workstation (using the Windows Subsytem for Linux) for test and evaluation purposes. This container is the core of the application and contains the Angular front end and middle tier of C# Application Programming Interfaces (APIs)
Docker Hub - repository that contains all published releases of RegScale containers which can be pulled for installations or upgrades
APIs - Representational State Transfer (REST) APIs that are well defined with a published Swagger interface for developing automations and integrations
Command Line Interface (CLI) - sidecar for bulk data processing via the command line (OPTIONAL and only available for Enterprise Customers). It should run on RHEL or Ubuntu in a separate VM which can schedule CRON jobs or other means to batch update large amounts of data.
SQL Server - relational database for storing RegScale data. It is typically installed into an existing database cluster or a cloud Relational Database Service (RDS). For test and evaluation, you can also install a local SQL Server Express instance on the same VM but this is not recommended or supported for Production use. NOTE: SQL Server containers for a local instance do not currently support Mac M1 chips due to a known Microsoft issue. If on a new Mac, you will need to provide a connection string to a remote SQL Server database.
File Storage - RegScale allows customers to upload and encrypt evidence inside of the platform. Storage is needed to hold this data and is typically thin provisioned to allow expansion over time.
Backups - both the database and file storage should be routinely backed up. The container does not need to be backed up as it is immutable and stateless.

Easy Mode Installation

The RegScale team has built an installer script to make loading RegScale as easy and fast as possible. Typical installation times are 8 - 10 minutes (NOTE: There will be a wait time while the database is seeded. The database connection will typically need a few minutes to finish the seeding process before it becomes available to serve the application. During this period, you will see connection reset errors until the process completes).

The following steps are required to install in easy mode:

The installation script requires Python ( versions >= 3.9.0 & <=3.11) (download here)
Recommend using a python virtual environment: See here for instructions
The installation script requires pip (How to install pip)
Download the installation script
Download the teardown script
Install Docker Python library via pip: pip install docker
Run the installer based on Operating System:
- Windows - py standalone.py
- Mac/Linux - python3 standalone.py
Within 8 - 10 minutes, the application should be installed and running. NOTE: During this time, the web page will show blank and will not load. Keep refreshing every few minutes until the page comes up and you see the RegScale login.
See Post-Deployment Steps to continue
To remove the application:
- Windows - py teardown.py
- Mac/Linux - python3 teardown.py

NOTE 1: Windows may require a manual install of "pip3" if it is not present on the system

NOTE 2: Easy mode installer does not currently support providing an external database connection string but this is on the roadmap

NOTE 3: For Linux installs, only RHEL and Ubuntu have been tested and are supported

NOTE 4: For Linux installs, some commands may require sudo for permissions

NOTE 5: For Mac installs, enter sudo password if prompted

NOTE 6: The JWT key should be set explicitly by the user and use of the default key is not recommended. Also, RegScale recommends the user rotate this key periodically for security purposes.

NOTE 7: The Encryption key should be set explicitly by the user and the default password should not be used. This key cannot be changed so use of a long key (64 characters) is recommended.

Manual Installation

Download all of the configuration files below:
- RegScale Configurations
  - or pull via command line at wget https://atlasity-io.web.app/assets/kb/yaml/stand-alone/atlas.env
- RegScale Database Configurations
  - or pull via command line at wget https://atlasity-io.web.app/assets/kb/yaml/stand-alone/db.env
- Docker Compose Configurations
  - or pull via command line at wget https://atlasity-io.web.app/assets/kb/yaml/stand-alone/docker-compose.yml
- All files should in the same directory. Perform a ls command to verify that they are downloaded correctly.
Edit db.env using nano db.env
- Set SA_PASSWORD to a secure value of your choosing. Avoid most special characters as they will potentially cause issues (allowed special characters are listed below). NOTE: this password is stored locally with the customer and is not available or retrievable by RegScale.
- NOTE This password needs to meet the built-in complexity requirements of SQL Server:
  - At least 8 characters.
  - The password does not contain the account name of the user.
  - The password is at least eight characters long.
  - The password contains characters from three of the following four categories:
    - Latin uppercase letters (A through Z)
    - Latin lowercase letters (a through z)
    - Base 10 digits (0 through 9)
    - Non-alphanumeric characters such as: exclamation point (!), dollar sign ($), number sign (#), or percent (%)
  - Passwords can be up to 128 characters long. Use passwords that are as long and complex as possible.
Edit atlas.env using nano atlas.env
- StoredFilesPath: This is the location where the persistent storage will be mounted. You should not need to change this value, unless you change the mount point in your docker-compose file
  - Default value: /atlas/files
- FileSizeLimit: The file size limit per file in bytes. Please note the overall limit is 120 MB, even if you set this variable larger than that. This variable is optional and will be set to 100 MB by default if nothing is provided.
  - Default value: 104857600
- DB_SERVER: Name of the database server. DO NOT CHANGE IF USING docker-compose
  - Default value: atlas-db
- DB_PORT: Port for the database. DO NOT CHANGE IF USING docker-compose
  - Default value: 1433
- JWTSecretKey: This is your JWT Secret Key. This can be any random value that is 32, 64, or 128 characters/bytes in length (or 256, 512, or 1024 bits respectively).
  - For setting keys, we recommend this Online Encryption Key Generator (256 bit) for quickly generating random security keys.
  - You can use any other mechanism to create this key. However, we recommend a minimum of a 256-bit secure key as it will be changed infrequently (or never) as it will invalidate all open sessions after being deployed.
  - Default value: JWTSecretKeyFromSomeWhere6789012
- EncryptionKey: This is your Encryption Key for encrypted files and data in the database. This can be any random value that is 32, 64, or 128 characters/bytes in length (or 256, 512, or 1024 bits respectively).
  - For setting keys, we recommend this Online Encryption Key Generator (256 bit) for quickly generating random security keys.
  - You can use any other mechanism to create this key. However, we recommend a minimum of a 256-bit secure key as it will be changed infrequently (or never) as it will invalidate all encrypted files after being deployed.
  - Default value: YourEncryptionKeyFromSomeWhere12
  - WARNING: Once this key is used, it should not be changed as it can result in data becoming unreadable.
- SQLConn: This is the SQL Connection string from above.
  - If using the container-hosted DB, simply configure the password to match the one configured in db.env. All other components should stay the same. NOTE: If you wish to connect to an external database, you can provide a full connection string and avoid provisioning a local SQL Server Express database.

Run RegScale

If you want to stand up the database container and RegScale, navigate into the directory where the docker-compose.yml file is located
- Type:
```
docker-compose up
```
  - This command will start the atlas-db container
  - Once the database is running, it will start the atlas container
  - The atlas container will wait for the database container to start and be listening on port 1433
  - NOTE: Through this process, if you receive any permission errors, prefix commands with sudo to ensure appropriate permissions
- To run this command in the background you can alternately run:
```
docker-compose up -d
```
If you have a database you want to point to, edit the atlas.env with your database connection string and ensure your DB server is listening on port 1433
- Simply run:
```
docker run --env-file atlas.env -v atlasvolume:/atlas/files -p 81:8080 regscale/regscale:latest
```
- To run any version < 5.27, expose port 80 by running:
```
docker run --env-file atlas.env -v atlasvolume:/atlas/files -p 81:80 regscale/regscale:5.26.1
```
RegScale should now be running locally on a single container.
- Point your browser to http://localhost:81
- (NOTE: Ubuntu and other OS run local firewalls by default. You may need to open port 81 on your host OS.)
See Post-Deployment Steps to continue
When you are done, you can shutdown the containers with:
```
docker-compose down
```
- This will still leave the data in the database and on the volumes

Add Certificates (Stand-Alone)

When configuring the system in Stand-Alone mode, RegScale has the ability to support SSL certificates for secure/encrypted communications. These certificates can be self-signed, signed by an internal CA, or signed by an external CA. Self-signed should ONLY be used in test environments

Make sure RegScale is stopped:
```
docker-compose down
```
In order for this to work, you need a certificate in PFX format. These directions should walk you through how to generate a self-signed cert on Linux or Mac
- Download the https.config file from here: HTTPS Config File
- Run the following command to generate a private key and a certificate signing request:
```
openssl req -config https.config -new -out csr.pem
```
- Run the following command to create a self-signed certificate:
```
openssl x509 -req -days 365 -extfile https.config -extensions v3_req -in csr.pem -signkey key.pem -out https.crt
```
- Run the following command to generate a pfx file containing the certificate and the private key that you can use with RegScale. Remember the password, as we will use it later. You can also choose to not password protect this file if you desire.
```
openssl pkcs12 -export -out https.pfx -inkey key.pem -in https.crt -password pass:<<Password>>
```
Copy to the https.pfx file to its own directory to be mounted inside the RegScale container.
- For this example, I am using /atlas/ssl
Edit the docker-compose.yml file:
- Under the atlas container:
- In ports:, under the line - "81:8080", add:
```
- "8443:443"
```
- In volumes:, under the line - atlasvolume:/atlas/files, add:
```
- /atlas/ssl:/atlas/ssl
```
- The FIRST /atlas/ssl is the directory on your Linux/Mac. Modify this to be the location where you have the https.pfx file.
- The SECOND /atlas/ssl is the location within the container. DO NOT CHANGE THIS.

Edit the atlas.env file and add the following lines to the end of the file (where PASSWORD should be changed to the password you set up earlier):

ASPNETCORE_URLS=https://+:443;http://+:80
Kestrel__Certificates__Default__Path=/atlas/ssl/https.pfx
Kestrel__Certificates__Default__Password=PASSWORD

Start RegScale again:
```
docker-compose up -d
```
Point your browser to https://localhost:8443

Remove Volumes

Please note, the Docker volumes are created and are persistent so your data will remain. If you want to REMOVE all the data or start fresh, run the following commands:

Verify your volume names:
```
docker volume ls
```

You should see output similar to(or exactly like) the following:

DRIVER              VOLUME NAME
local               docker_standalone_atlasvolume
local               docker_standalone_sqlvolume

Remove both of the volumes, using the names from the command above:

docker volume rm docker_standalone_atlasvolume docker_standalone_sqlvolume

Back up and Restore Volumes

To backup the database volume for security or migration, use the docker volume commands. The following assumes that the names and labels in docker-compose.yml have not been changed.

Backup the volume from the atlas-db container:

sudo docker run --rm --volumes-from atlas-db -v $(pwd):/backup busybox tar cvf /backup/backup.tar /var/opt/mssql

This creates a tar file backup.tar in the current directory.

To restore or overwrite a atlas-db container. Run the following from the directory where the backup.tar file resides:

sudo docker run --rm --volumes-from atlas-db -v $(pwd):/backup busybox tar xvf /backup/backup.tar