CShark Software User's Guide

Identification of the provisioned instance

Current on 2026-08-06.

1. Purpose

The manual contains information necessary for daily use of CShark after installation. The document refers to the provided demo copy for Ubuntu Server 24.04 LTS AMD64.

Installation is carried out according to separate instructions. The commands in this tutorial assume a directory /opt/cshark-stand and Compose project cshark-stand.

2. Operating conditions

To work you need:

• working Ubuntu Server 24.04 LTS AMD64 server;
• at least 8 GB of RAM and 30 GB of free space;
• correct date, time and time zone;
• user access to port 8088/tcp;
• administrator access to the server via a secure channel;
• backup storage separated from the production instance.

External access to PostgreSQL and NATS is not required and should not be published.

3. Start and stop

Check status:

sudo docker compose \
  --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml \
  --profile obs ps

Run:

sudo docker compose \
  --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml \
  --profile obs up -d

Stop without deleting data:

sudo docker compose \
  --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml \
  --profile obs down

4. Readiness check

After launch, run:

curl -fsS http://127.0.0.1:8088/api/health

Additionally check:

• containers have state running or healthy;
• The web interface is available via http://<IP-OR-DNS>:8088;
• Grafana is available at http://<IP-OR-DNS>:13000;
• free disk space is not below the operational threshold;
• server time is synchronized.

5. First entry

Primary details are in the file:

sudo cat /opt/cshark-stand/INITIAL-CREDENTIALS.txt

Log in as an administrator and create personal user accounts. Do not use one common account for several operators: personal records are necessary for correct auditing.

6. Workspaces and roles

After logging in, the user sees only the sections allowed to him. Main workspaces:

If a section is unavailable, the administrator checks the assigned role and permissions rather than transferring someone else's account to the user.

7. Initial state demo

After installation, the administrator checks:

1. the “Severny” Demo parking facility does not contain a real address;
2. there is a level 1;
3. there are zones Blue Sector and Green Sector;
4. exactly 50 places created DEMO-01–DEMO-50;
5. there are places for MGN, EV, moto and service;
6. a demonstration camera, three gate devices and a scoreboard are registered;
7. Demo incident available;
8. mock APS has state running or healthy;
9. an emulator event changes the state of the associated location;
10. There is no real camera footage until a separate media package is connected.

The demo object is not data from a real customer and is intended only for testing and demonstrating the functions of the system.

8. Working with the circuit

The operator opens the “Scheme” section, selects an object and level, then:

• evaluates the summary status;
• moves from overview to sector and location;
• uses search;
• opens a place card;
• views status history;
• reviews related incidents;
• includes only the necessary additional layers.

Changing the operational status of a place is carried out only with permission. For a group operation, you must check the number of affected locations before confirming.

9. Incident handling

Recommended order:

1. open a queue of active incidents;
2. check the object, level, place, time and materials;
3. take the incident into action;
4. perform an action according to the facility regulations;
5. add the necessary information;
6. end or reasonably ignore the incident;
7. make sure the status is updated.

The incident is not deleted to hide the error: the operator's decision must remain in history and audit.

10. Journal and analytics

The visit log uses filters based on available parameters. Access to vehicle IDs is limited to roles that need it.

In analytics, check the selected object and level before interpreting metrics. You cannot compare the values ​​of different data areas without taking into account the context.

11. Equipment

The technical specialist controls:

• condition online or offline;
• time of last event;
• history of availability changes;
• binding to an object and zone;
• driver parameters;
• the result of a safe command.

Before sending a command to a gate or other actuator, you must make sure that the command is acceptable by the facility regulations and does not create a danger.

Emulators are used for functional testing without connecting real hardware.

12. Scoreboards and templates

In the scoreboard section, the administrator or authorized technical specialist:

1. creates a screen recording;
2. specifies its class and parameters;
3. creates or edits a template;
4. checks preview;
5. assigns a template to a screen;
6. checks the actual display;
7. revokes the screen token if necessary.

The template and purpose are saved on the server. The screen should not depend on the operator's open session. The priority emergency message takes precedence over regular information content.

Managing shift templates and copying operator personal layouts is a future development; An approved set of server-side scoreboard templates is used prior to their release.

13. Users and rights

Administrator:

• creates personal accounts;
• assigns the minimum required roles;
• disables the accounts of terminated or transferred employees;
• periodically checks the composition of roles;
• analyzes the audit log;
• does not share service secrets with regular users.

Resetting the administrator password using a separate command with physical access to the server is a planned feature. Before its release, access restoration is carried out only according to the approved maintenance procedure with a backup copy and logging of actions.

14. Shift control

At the beginning of the shift, the operator checks:

• accessibility of the Web interface;
• correctness of the object and level;
• number of active incidents;
• availability of offline devices;
• relevance of information screens;
• no system warnings.

During shift handover, unfinished incidents, temporarily disabled locations, faulty devices, and applied emergency messages are recorded.

15. Backup

Create a copy of the database:

tools/backup/backup.sh /path/to/backups

Media is copied to separate S3-compatible storage with SHA-256 verification. Backup storage details are transmitted through a protected env file with the rights 0600rather than via command line arguments.

It is recommended to copy the database daily and media weekly. Restoration to a temporary environment is performed periodically and the control counters are checked.

16. Update

Before update:

1. agree on the work window;
2. commit the current version;
3. check health and free space;
4. create a verified backup;
5. get the new version kit;
6. check SHA-256 and release notes.

The update is performed by the system administrator according to separate instructions for a specific version. You cannot update the system using a command with the tag latest without identifying images and database schema.

There is no automatic update from the interface in the current version.

17. Logs and diagnostics

Latest magazines:

sudo docker compose \
  --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml \
  --profile obs logs --no-color --tail 200

Installation log:

sudo cat /opt/cshark-stand/install.log

When contacting support, they save the version, time, sequence of actions, error, state of containers and relevant logs. Secrets and personal data are removed or masked before transmission.

18. Typical faults

19. Actions in case of failures

19.1. NATS not available

Restart NATS and check /healthz. Do not delete the volume Gateway outbox: after recovery, the Gateway must send the saved events.

19.2. Camera not available

Check the camera's power and network, last heartbeat time and device log. Until restoration, its places may remain in their last known state.

19.3. Disk is full

Identify the source of growth. Observability history can be cleared using a separate procedure, but PostgreSQL, S3 or Gateway outbox cannot be deleted without a backup copy and assessment of the consequences.

19.4. Data corruption

Stop data-modifying components, save logs and the current state, then restore only from a verified copy. Don't run repeat migrations blindly.

20. Shelf life

Default values:

Actual timing is determined by the facility owner's policies and applicable requirements. The impact on investigations and reporting is reviewed before the deadline is reduced.

21. Safety requirements

• use personal accounts;
• apply the principle of least privilege;
• restrict network access with a firewall;
• store env files and backups in closed directories;
• do not publish PostgreSQL and NATS;
• synchronize system time;
• check the audit log regularly;
• do not enable public search for a car without a separate privacy acceptance;
• Do not delete data to resolve a symptom without diagnosing it.

22. Completion of operation

Before decommissioning a unit:

1. stop accepting new events;
2. create a final backup;
3. check the readability of the copy;
4. export the necessary reports;
5. revoke API keys and screen tokens;
6. stop containers;
7. delete data only according to the approved act;
8. record the result and storage location of the archives.