Cluebase VMS Installation Manual

This manual explains how to install Cluebase VMS using the interactive installer package.

The installer deploys Cluebase VMS as a Docker Compose-based system. During installation, it can also install optional components such as the AI module, LPR module, BI service, HTTPS configuration, and GPU runtime support.

Installation Package

The installation package contains the following scripts:

install.sh - main interactive installer

start.sh - runs the VMS after installation

stop.sh - stops the VMS

restart.sh - restarts the VMS

update.sh - updates the VMS

uninstall.sh - uninstalls the VMS completely

After installation, the installer creates the deployment directories in the directory where it is run:

./cluebasevms/ - Cluebase VMS deployment directory.

./bi/ - BI deployment directory, created only if BI is selected.

System Requirements

Minimal requirements depend on the number of cameras, enabled analytics, and archive retention period. For a basic installation, prepare a Linux server with:

- Ubuntu or another compatible Debian-based Linux distribution.

- Bash shell.

- `sudo` access.

- Internet access for downloading Docker packages and Docker images.

- Static IP address.

- Free disk space for Docker images, configuration files, database data, archive files, and optional AI/BI data.

To find out the compatible hardware configuration please refer to https://vcloud.ai/support web page.

For GPU mode:

- NVIDIA GPU.

- Installed NVIDIA driver.

- Working `nvidia-smi` command.

- Internet access for installing NVIDIA Container Toolkit if it is not already installed.

The installer supports the following CPU architectures:

- `x86_64` / `amd64`

- `aarch64` / `arm64`

If the server architecture is not supported, the installer stops before making deployment changes.

Network Ports

Depending on selected options, the following ports may be used:

- `80` - Cluebase VMS web interface when HTTP is selected.

- `443` - Cluebase VMS web interface when HTTPS is selected.

- `8080` - BI web interface when HTTP is selected.

- `8443` - BI web interface when HTTPS is selected.

- `3000` - Cluebase backend local port.

- `3307` - MySQL external local binding.

- `4001` - livestream server local binding.

- `4444` - WebSocket server.

- `4646` - embedded video analytics service.

- `8095` - LPR API port.

- `8565` - RTSP server.

- `9001` - AI service port.

- `32433` - LPR license service port.

Make sure that required ports are not already used by another application.

Preparing the Installer

1. Copy the installer archive to the target server.

2. Extract the archive.

3. Open a terminal in the extracted `installer` directory.

4. Make sure the main script is executable:

chmod +x install.sh

The installer creates deployment files in the current working directory. Run it from the directory where you want the `cluebasevms` and optional `bi` folders to be created.

Starting Installation

Run the installer:

./install.sh

The installer opens an interactive menu. Use the Up and Down arrow keys to move through options and press Enter to select.

Screenshot: Installer welcome screen

Installation Options

AI Module

The installer asks:

`Install AI module (vms-ai)?`

Select `Yes` to install the AI analytics container. This enables additional AI-based video analytics features.

Select `No` if the system should run without the AI analytics container.

LPR Module

The installer asks:

`Install LPR module (vms-lpr)?`

Select `Yes` to install the LPR container and the host LPR license service.

Select `No` if license plate recognition is not required.

If LPR is selected, the installer copies the LPR scripts into `./cluebasevms/lpr-scripts/` and runs the LPR license service installer.

BI Service

The installer asks:

`Install BI (Business Intelligence)?`

Select `Yes` to install the BI API, BI UI, BI runner, BI streamer, BI dispatcher, PostgreSQL, Redis, and BI Nginx gateway.

Select `No` to install only Cluebase VMS.

When BI is selected, the installer creates the `./bi/` directory.

Default BI login after installation:

admin / admin

HTTPS / SSL

The installer asks:

`Enable HTTPS (SSL)?`

Select `No` for HTTP mode:

- Cluebase VMS listens on port `80`.

- BI listens on port `8080`, if BI is installed.

Select `Yes` for HTTPS mode:

- Cluebase VMS listens on port `443`.

- BI listens on port `8443`, if BI is installed.

HTTPS mode uses the bundled self-signed certificates from the installer templates. Browsers may show a certificate warning until a trusted certificate is installed.

CPU or GPU Runtime

The installer asks this question only if AI, LPR, or BI is selected:

`Run AI / LPR / BI services on CPU or GPU?`

Select `CPU` to run without NVIDIA runtime support. This option works on any supported host.

Select `GPU` to enable GPU configuration in the relevant Docker Compose services. In GPU mode, the installer checks `nvidia-smi` and installs/configures NVIDIA Container Toolkit if required.

If GPU mode is selected but no NVIDIA GPU is detected, the installer stops and asks you to install NVIDIA drivers first or rerun the installer in CPU mode.

Installation Summary

Before making changes, the installer shows a summary:

- detected architecture

- AI module selection

- LPR module selection

- BI service selection

- protocol and ports

- CPU or GPU runtime

Screenshot: Installation summary

Select `Yes` to proceed with installation.

Select `No` to abort without installing services.

What the Installer Does

After confirmation, the installer performs the following actions.

1. Installs prerequisites

The installer checks for Docker. If Docker is already installed, it continues.

If Docker is missing, the installer:

- waits for any active `apt` lock to clear

- repairs interrupted `dpkg` state if needed

- updates the package index

- installs required packages such as `ca-certificates`, `curl`, `gnupg`, and `lsb-release`

- adds the Docker repository

- installs Docker Engine, Docker CLI, containerd, Docker Buildx plugin, and Docker Compose plugin

- adds the current user to the `docker` group

- enables and restarts the Docker service

- waits until Docker is ready

If the current shell cannot access Docker without sudo, the installer uses `sudo` for Docker commands and warns that you may need to log out and back in after installation.

2. Installs Docker Compose support

The installer checks for the Docker Compose plugin with:

docker compose version

If the plugin is missing but legacy `docker-compose` exists, it uses the legacy binary.

If neither is available, it installs a legacy Docker Compose binary as a fallback.

3. Configures NVIDIA runtime when GPU mode is selected

When GPU mode is selected, the installer:

- checks that `nvidia-smi` works

- installs NVIDIA Container Toolkit if it is missing

- registers the NVIDIA runtime with Docker

- restarts Docker

- verifies that the `nvidia` runtime appears in `docker info`

4. Builds the Cluebase VMS deployment directory

The installer creates:

./cluebasevms/

If the directory already exists, the installer asks whether it should overwrite it.

The directory contains:

- Docker Compose file

- `.env` file

- Nginx configuration

- MySQL configuration

- RTSP server configuration

- bundled certificates

- service scripts

- LPR scripts if LPR was selected

The installer selects the correct Docker Compose template based on the selected options:

- no AI/LPR: `docker-compose-noai.yml`

- AI and/or LPR: `docker-compose-ai.yml`, with unused services removed

For ARM servers, the installer rewrites selected image tags to ARM-compatible tags.

For HTTPS mode, the installer copies the HTTPS Nginx template and switches the Compose port mapping from HTTP to HTTPS.

For GPU mode with AI selected, the installer enables the GPU directives in the `vms-ai` service.

5. Builds the BI deployment directory

If BI is selected, the installer creates:

./bi/

The BI directory contains:

- Docker Compose file

- `.env` file

- PostgreSQL configuration

- Nginx configuration

- BI service scripts

- bundled certificates when HTTPS is selected

If GPU mode is selected, the installer enables GPU directives for BI runner and streamer services.

6. Installs LPR license service

If LPR is selected, the installer runs:

sudo bash ./lpr-scripts/install-lpr-lic.sh

This installs the host-side LPR license service used by the LPR container.

7. Creates common management scripts

The installer writes these scripts in the directory where installation was started:

start.sh

stop.sh

restart.sh

update.sh

uninstall.sh

These scripts control both Cluebase VMS and BI when BI is installed.

8. Pulls images and starts services

For Cluebase VMS, the installer:

1. Pulls Docker images.

2. Starts `vms-db`.

3. Waits for the database to become ready.

4. Starts `vms-migration`.

5. Waits for migration success.

6. Starts the remaining Cluebase services.

For BI, the installer:

1. Pulls Docker images.

2. Starts all BI services with Docker Compose.

Accessing the System

When installation finishes, the installer displays the access URL.

For HTTP mode: Cluebase: http://<server-ip> BI: http://<server-ip>:8080

For HTTPS mode: Cluebase: https://<server-ip> BI: https://<server-ip>:8443

BI is shown only when BI was selected during installation.

Screenshot: Installation complete screen

Open the displayed Cluebase URL in a supported web browser.

Managing Services

Run the following commands from the installation directory.

Start services

./start.sh

Starts Cluebase VMS and BI if they are installed.

Stop services

./stop.sh

Stops Cluebase VMS and BI if they are installed.

Restart services

./restart.sh

Stops and starts Cluebase VMS and BI.

Update services

./update.sh

Pulls the latest Docker images, stops the services, and starts them again.

Changing the Server IP Address

The installer creates:

./cluebasevms/new-ip.sh

Use this script if the server IP address changes after installation.

Recommended procedure:

1. Stop Cluebase VMS:

./stop.sh

2. Run the new IP script from the Cluebase directory:

./new-ip.sh

3. Start the services again:

./start.sh

The server should use a static IP address to avoid repeated reconfiguration.

Dry Run Mode

Use dry run mode to preview installation actions without pulling Docker images or installing packages:

./install.sh --dry-run

Dry run mode is useful for checking selected options and generated file operations before installing on a production server.

Uninstalling Cluebase VMS

The installer supports interactive uninstall:

./install.sh --uninstall

You can also use the generated uninstall script:

./uninstall.sh

Services only

This option:

- stops Cluebase VMS and BI containers

- removes Docker Compose volumes for these services

- deletes `./cluebasevms`

- deletes `./bi`

- removes the LPR license service if it was installed

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:

ARCH_OVERRIDE=arm64 ./install.sh --dry-run

This is mainly useful for testing.

Disable colored output

Use:

NO_COLOR=1 ./install.sh

This disables ANSI color output in the installer menus.

Offline Installation Note

The bundled README references these offline commands:

sudo ./offline_installer.sh

sudo ./offline_update.sh

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:

sudo systemctl status docker

sudo journalctl -u docker -n 50

GPU mode fails

If GPU mode fails, check:

nvidia-smi

docker info | grep -i nvidia

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:

sudo ss -tulpn

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

Database does not become ready

Check the database logs:

docker logs vms-db --tail 200

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

Migrations do not complete

Check migration logs:

docker logs vms-migration --tail 200

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

Check running containers

Use:

docker ps

or, if Docker requires sudo:

sudo docker ps

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`