Difference between revisions of "Cluebase VMS Installation Manual"

From vCloud.ai Documentation
Jump to navigation Jump to search
Line 1: Line 1:
<strong>Installation manual Contents</strong>


== Preparation ==
Use this option when Docker is used by other applications on the server.
Download cluebase.zip from https://vcloud.ai/downloads and unzip the file. Please note that in some versions of Linux the unzip application is not included so you'll need to install it separately with the following command:
sudo apt install unzip
Now unzip the Cluebase VMS installer with the following command:
sudo unzip cluebase.zip
The above command creates a directory containing the installation files.  


Go to CluebaseVMS directory:
=== Everything ===
cd CluebaseVMS
Now you have to provide permissions to the installation script (install.sh):
sudo chmod +x install.sh
You are all set for the installation.


== Automatic installation  ==
This option removes Cluebase VMS and BI and also purges Docker from the server.


It removes:


Docker container framework and Docker-compose extension are required for Cluebase VMS installation and operation.<br>
* Docker Engine
* Docker CLI
* Docker Compose plugin
* Docker data under <code>/var/lib/docker</code>
* Docker configuration under <code>/etc/docker</code>
* Docker socket and related files


=== Installing on Linux ===
<blockquote>⚠️ '''Warning:''' This option destroys all Docker containers, images, and volumes on the host, including containers unrelated to Cluebase VMS. The installer requires typed confirmation before continuing.</blockquote>
Please run the install.sh script to automatically install Cluebase VMS on a clean Linux OS.<br>


To run the script, please go to the folder containing “install.sh” and run the following command: <br>
== Advanced Options ==


$ sudo sh install.sh <br>
=== Force architecture ===


== Installing the SSL version ==
Use <code>ARCH_OVERRIDE</code> to force architecture detection:
Here are the steps to install Cluebase VMS with SSL encryption:


# Download Cluebase VMS SSL installer . Please note that it comes as a separate install package and available at https://vcloud.ai/downloads
<syntaxhighlight lang="bash">
# Prepare SSL certificate and public key that are generated for the required domain name.
ARCH_OVERRIDE=arm64 ./install.sh --dry-run
# Unzip the installation package.
</syntaxhighlight>
# Navigate to 'certs' directory in the installation package.
# Copy the SSL certificate and public key (file should be named as follows: cert.crt - SSL certificate, cert.key - public). The existing files should be replaced or removed before
# Provide permissions to the installation script by this command:


sudo chmod +x install.sh
This is mainly useful for testing.
7. Run the installation script:
  $ sudo sh install.sh


== Manual installation ==
=== Disable colored output ===


=== Installing Docker on Linux ===
Use:
Official Docker installation guide: https://docs.docker.com/engine/install/ubuntu/<br>


Run the following command:<br>
<syntaxhighlight lang="bash">
NO_COLOR=1 ./install.sh
</syntaxhighlight>


$ sudo apt-get update && apt-get install docker-ce docker-ce-cli containerd.io <br>
This disables ANSI color output in the installer menus.


=== Installing docker-compose on Linux ===
== Offline Installation Note ==
Run the following command:<br>


$ sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose <br>
The bundled README references these offline commands:
Grant the necessary access rights by running the following command:<br>


$ sudo chmod +x /usr/local/bin/docker-compose <br>
<syntaxhighlight lang="bash">
sudo ./offline_installer.sh
sudo ./offline_update.sh
</syntaxhighlight>


=== <strong>Preparation for manual VMS installation </strong> ===
The attached installer archive inspected for this manual does not contain <code>offline_installer.sh</code> or <code>offline_update.sh</code>. Offline installation therefore requires a separate offline bundle that includes those scripts, Docker packages, Docker Compose binary, and pre-pulled image tarballs.
You will need to edit the environment variable file, the .env file, to successfully install the VMS.<br>


Please note that this file is hidden in the folder by default. <br>
== Troubleshooting ==


Open the .env file and specify the server's IP address in the following fields: <br>
=== Docker group permissions ===


APP_HOST=0.0.0.0 (the server's public IP address) MACHINE_HOST=0.0.0.0 (local IP address of the server) <br>
After Docker installation, the installer adds the current user to the <code>docker</code> group. The current terminal session may not receive the new group permission immediately.


If the VMS should only be used in the local network, both IP addresses will be the same.  
If Docker commands require sudo after installation, log out and log back in, then try again.


=== Using a custom port for the VMS ===
=== Docker daemon is not ready ===
By default the VMS installs and runs on port 80. However you can configure a different port by amending the .env file.


Open the .env file and add NGINX_PORT variable and it's value (port number) as shown on the screenshot.
If Docker does not become ready, check:
[[File:Editing .env file .jpg|thumb|none|557x557px]]


=== Installing and running VMS ===
<syntaxhighlight lang="bash">
<br>Enter the VMS folder and run the following command: <br>
sudo systemctl status docker
sudo journalctl -u docker -n 50
</syntaxhighlight>


$ sudo docker-compose up -d <br>
=== GPU mode fails ===


This command will automatically download, install and run VMS.
If GPU mode fails, check:


=== Failover ===
<syntaxhighlight lang="bash">
nvidia-smi
docker info | grep -i nvidia
</syntaxhighlight>


===== Description =====
If <code>nvidia-smi</code> does not work, install or repair the NVIDIA driver first, then rerun the installer.
Cluebase VMS supports failover (hot swap) functionality as the following options:


# 1 to 1 - every server in the system has a failover server
=== Port already in use ===
# Many to 1 - several servers can be hot-swapped by 1 failover server
# Many to Many - several servers can be hot-swapped by several failover servers


===== Important =====
If the web interface does not open, check whether required ports are already used:


# In case of using the failover functionality it’s important to make sure that network storage is being used (Object storage or NAS)
<syntaxhighlight lang="bash">
# Failover server hardware should be able to handle the required number of cameras so the failover servers’ hardware should be precisely calculated and configured.
sudo ss -tulpn
# Configuration is automatically sent from main server to failover every 5 minutes
</syntaxhighlight>
#Please note that shutting down the main server manually is considered as maintenance and will not initiate the failover process.
#After switching back from failover server to the main server it is required to reset failover server's configuration or reboot.


===== Setup =====
Free the required port or change the deployment configuration before starting the services again.
To set up a failover system you need to have at least 1 main server and 1 failover server.


Go to the main server user interface and open Failover settings: Settings->Failover->Add Failover Server and fill the fields with Failover server credentials. In the Logic field choose the server or servers that should be hot-swapped by the current Failover server. Then click Save.
=== Database does not become ready ===
[[File:Failover settings.png|none|thumb]]


Check the database logs:


<br>
<syntaxhighlight lang="bash">
docker logs vms-db --tail 200
</syntaxhighlight>


== Sign in ==
The installer waits for the message indicating that MySQL is ready for connections.
Open a web browser (Google Chrome, Mozilla Firefox and Safari are recommended), enter the server's IP address and press Enter. <br>
[[File:Sign in.png|none|thumb]]
<br>
By default login and password: admin/admin.


== Server IP update ==
=== Migrations do not complete ===
sudo sh newIP.sh


== Stopping the VMS  ==
Check migration logs:
Run the following command from the VMS folder to stop the VMS server:<br>


$ sudo sh stop.sh<br>
<syntaxhighlight lang="bash">
docker logs vms-migration --tail 200
</syntaxhighlight>


== Updating VMS  ==
The installer waits for <code>migration success</code> before starting the remaining Cluebase services.
To update VMS version:<br><br>  
$ sudo sh update.sh<br>


== Start VMS ==
=== Check running containers ===
$ sudo sh start.sh<br>


== Uninstall VMS ==
Use:
$ sudo sh uninstall.sh<br>


== Camera settings recommendations ==
<syntaxhighlight lang="bash">
1. Always use the CBR setting, as when using VBR on some camera models, the bitrate may drop to limits, which may cause the video stream to be temporarily shut down. <br>
docker ps
2. Always set the minimum keyframe interval (I Frame interval or Key Frame interval).
</syntaxhighlight>
 
or, if Docker requires sudo:
 
<syntaxhighlight lang="bash">
sudo docker ps
</syntaxhighlight>
 
Expected Cluebase containers may include:
 
* <code>vms-server</code>
* <code>vms-live-server</code>
* <code>vms-web</code>
* <code>vms-db</code>
* <code>vms-nginx</code>
* <code>vms-rtsp-server</code>
* <code>vms-va</code>
* <code>vms-ai</code>, if AI was selected
* <code>vms-lpr</code>, if LPR was selected
 
Expected BI containers may include:
 
* <code>bi-postgres</code>
* <code>bi-redis</code>
* <code>bi-migration</code>
* <code>bi-api</code>
* <code>bi-runner</code>
* <code>bi-streamer</code>
* <code>bi-dispatcher</code>
* <code>bi-ui</code>
* <code>bi-nginx</code>

Revision as of 09:27, 18 May 2026

Use this option when Docker is used by other applications on the server.

Everything

This option removes Cluebase VMS and BI and also purges Docker from the server.

It removes:

  • Docker Engine
  • Docker CLI
  • Docker Compose plugin
  • Docker data under /var/lib/docker
  • Docker configuration under /etc/docker
  • Docker socket and related files

⚠️ Warning: This option destroys all Docker containers, images, and volumes on the host, including containers unrelated to Cluebase VMS. The installer requires typed confirmation before continuing.

Advanced Options

Force architecture

Use ARCH_OVERRIDE to force architecture detection:

<syntaxhighlight lang="bash"> ARCH_OVERRIDE=arm64 ./install.sh --dry-run </syntaxhighlight>

This is mainly useful for testing.

Disable colored output

Use:

<syntaxhighlight lang="bash"> NO_COLOR=1 ./install.sh </syntaxhighlight>

This disables ANSI color output in the installer menus.

Offline Installation Note

The bundled README references these offline commands:

<syntaxhighlight lang="bash"> sudo ./offline_installer.sh sudo ./offline_update.sh </syntaxhighlight>

The attached installer archive inspected for this manual does not contain offline_installer.sh or offline_update.sh. Offline installation therefore requires a separate offline bundle that includes those scripts, Docker packages, Docker Compose binary, and pre-pulled image tarballs.

Troubleshooting

Docker group permissions

After Docker installation, the installer adds the current user to the docker group. The current terminal session may not receive the new group permission immediately.

If Docker commands require sudo after installation, log out and log back in, then try again.

Docker daemon is not ready

If Docker does not become ready, check:

<syntaxhighlight lang="bash"> sudo systemctl status docker sudo journalctl -u docker -n 50 </syntaxhighlight>

GPU mode fails

If GPU mode fails, check:

<syntaxhighlight lang="bash"> nvidia-smi docker info | grep -i nvidia </syntaxhighlight>

If nvidia-smi does not work, install or repair the NVIDIA driver first, then rerun the installer.

Port already in use

If the web interface does not open, check whether required ports are already used:

<syntaxhighlight lang="bash"> sudo ss -tulpn </syntaxhighlight>

Free the required port or change the deployment configuration before starting the services again.

Database does not become ready

Check the database logs:

<syntaxhighlight lang="bash"> docker logs vms-db --tail 200 </syntaxhighlight>

The installer waits for the message indicating that MySQL is ready for connections.

Migrations do not complete

Check migration logs:

<syntaxhighlight lang="bash"> docker logs vms-migration --tail 200 </syntaxhighlight>

The installer waits for migration success before starting the remaining Cluebase services.

Check running containers

Use:

<syntaxhighlight lang="bash"> docker ps </syntaxhighlight>

or, if Docker requires sudo:

<syntaxhighlight lang="bash"> sudo docker ps </syntaxhighlight>

Expected Cluebase containers may include:

  • vms-server
  • vms-live-server
  • vms-web
  • vms-db
  • vms-nginx
  • vms-rtsp-server
  • vms-va
  • vms-ai, if AI was selected
  • vms-lpr, if LPR was selected

Expected BI containers may include:

  • bi-postgres
  • bi-redis
  • bi-migration
  • bi-api
  • bi-runner
  • bi-streamer
  • bi-dispatcher
  • bi-ui
  • bi-nginx
Retrieved from "https://docs.vcloud.ai/index.php?title=Cluebase_VMS_Installation_Manual&oldid=1263"