Administrator's Guide

1. Purpose of the document and administrator roles

The document is intended for specialists who configure and maintain CShark software at the customer’s site.

Daily work with the system is described in a separate document "User Guide", deployment - in the document “Instructions for installing a copy of the software”.

Rights are delineated by role model (section 12); the division into roles above is organizational.

2. Software composition and placement of components

The observability profile is included in the verification kit; published by Grafana on 13000/tcp, its remaining services are available only within the Compose network.

All services run in containers within a closed network perimeter of the facility. Calls to external services are not executed during operation.

3. Service management

Working directory: /opt/cshark-stand.

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

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

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

# restart one service
sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml restart core

# service logs
sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml logs -f core

4. Settings

The parameters are set by environment variables (file .env next to the service description file). After changing the settings, the service must be restarted.

5. Initial setup of the object

When you log in for the first time, the Initial Setup Wizard is available. Sequence:

1. Change the password for the built-in administrator account.
2. Create an object (parking), levels, zones, parking spaces.
3. Load the graphic background of the level and place objects on the diagram.
4. Register cameras and link them to parking spaces.
5. Create templates and devices for information boards.
6. Set up a graph of reachability zones and entry points.
7. Create operator roles and accounts.
8. Configure event processing rules.

6. Setting up topology and circuit

Section “Administration” → “Topology”.

Hierarchy: organization → parking → level → zone → parking space.

Parking space codes are displayed to users and must correspond to the markings on the site.

7. Setting up video analytics cameras

Section "Equipment".

1. Configure the camera to send events to the device gateway address (vendor protocol over HTTP). The address and port are specified in the camera settings.
2. The camera that accesses the system appears in the list of undetected devices.
3. Register a camera: set the name, network address, location.
4. Link the camera to the parking spaces it serves.
5. Check the arrival of events: the status of the associated parking space should change when the situation changes.

Performance monitoring is performed automatically based on periodic presence signals. The device status is displayed in the “Equipment” section and on the site diagram. The history of state changes is saved.

For devices that support control, command transmission via the command channel is available.

8. Setting up information boards

Section "Scoreboard".

8.1. Templates

The template describes the layout of the frame and consists of regions:

The font size is automatically adjusted to the size of the region; If the region's capacity is insufficient, a warning is issued when saving the template.

8.2. Display devices

1. Create a device, select a class: text LED panel (EK07, TCP/RS-485 protocol) or web kiosk on a high-resolution monitor.
2. Specify connection parameters.
3. Link template, zone and entry point.
4. Check the result by previewing the generated frame.

A public address of the form is generated for the web kiosk /kiosk/display/<identifier>?token=<token>; the monitor opens this page in kiosk mode. The token restricts access to content.

8.3. Content Priorities

Emergency → manual replacement → schedule → staffing. Emergency content (fire or shelter mode) supersedes any other content and cannot be replaced manually.

8.4. Addressee of texts

The reasons for unavailability are divided into public (displayed to the driver) and administrative (available only to staff). Administrative texts are not physically present in the public kiosk response and in the WebSocket stream. The diagnostic status of the display is available at /api/displays/{id}/state for authenticated personnel only.

9. Navigation settings

Section “Administration” → “Zones”, connections tab.

1. Specify the edges of the reachability graph between zones (which zones are reachable from which).
2. Indicate entry points to the site.
3. Attach the board guides to the entry points.

The system calculates the number of available spaces relative to a specific entry point and the direction of movement to them. The “data unavailable” state is displayed on the display with a symbol different from the value “zero” - the driver should not mistake the malfunction for a lack of seats.

10. Setting object modes and zones

Zone and object states: staff, fire, shelter, maintenance.

Changing the mode instantly changes: the availability of parking spaces in the zone, the contents of information boards (emergency content receives the highest priority), the rules for processing events, and the composition of notifications.

The administrator returns to normal mode manually after eliminating the cause.

11. Setting up event processing rules

Section “Administration” → “Rules”.

The rule is set according to the following scheme:

trigger (event type) × region (object, zone, group of places, specific place) × condition (time, status, other signs) → actions

Available actions: notify the operator, create an incident, change the status, send a command to the device.

The rule takes effect without restarting services. The order in which rules are applied is determined by their priority.

Examples: “violation of markings in an area for people with limited mobility → create a critical level incident”; “The parking space at the entrance has been occupied for more than 10 minutes without permission → notify the shift supervisor.”

12. Managing users, roles and rights

Section “Administration” → “Users” and “Roles”.

• Permissions are set in a single space of the form “resource:action” (for example, displays:manage, users:manage).
• A role is a named set of permissions. The user is assigned a role; Additionally, individual permits may be issued.
• Sections of the interface that are not accessible to the user due to rights are not displayed in the navigation.
• User actions are recorded in the action log.

Password requirements: at least 6 characters. Passwords are stored in the form of hashes (bcrypt algorithm); they are not stored or transmitted in clear text.

Sessions are implemented by signed tokens; the signature secret is specified by the parameter CSHARK_AUTH_SECRET. Changing the secret ends all active sessions.

13. Setting up integration with external systems

Section “Administration” → “Integrations”.

Interaction with a partner automated parking system (entrance group) is performed through these mechanisms.

14. Data retention and retention policies

The storage period is set by policies in the system settings section. Footage is only available via limited-time links; direct public access to storage facilities is closed.

15. Backup and restore

15.1. Backup

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

A database dump and media manifest are generated. Storage objects are copied separately using synchronization tools - the command is issued by the script. Recommended frequency: database - daily (according to the schedule on the host), media materials - weekly. The storage depth of copies is not less than the period of data storage in the system.

15.2. Checking the copy

Restoring to a temporary database without risk to the working one:

tools/backup/restore.sh backups/cshark-XXXX.dump cshark_restore_check

The script displays control counters (car spaces, visits, incidents, users) for reconciliation.

15.3. Recovery

Stop before recovery core and gateway via Compose file /opt/cshark-stand/compose.yml, execute the standard recovery script from the delivery and then start the same services. The commands and path to the backup copy are recorded in the work log; the restoration is first tested on a separate stand.

Media materials are restored by synchronization into an object container with verification against the manifest.

16. Monitoring and diagnostics

The software generates metrics, logs and traces according to the OpenTelemetry standard. When the observability profile is enabled, Grafana panels are available.

Key indicators:

Personal and sensitive data are automatically excluded from the logs.

17. Software update

The update is initiated by the customer administrator. There are no mechanisms for forced updating and remote control from outside the perimeter of the facility.

The current release does not include automatic remote update. Before the implementation of a promising managed mechanism, the update is performed as a separate regulatory delivery: accept the signed offline kit, verify the SHA-256 and foreign key signature, create and verify a backup copy, execute the release-specific instructions and a full smoke-test. The operation is carried out by the administrator during the agreed maintenance window.

Migrations follow the expansion-compression principle: breaking schema changes are released in a release following the release of the code that runs without them. Therefore, reverting to a previous version of the code is safe and does not require a schema rollback.

Returns are only allowed on a previously saved and tested set of the previous version after assessing the compatibility of the data scheme. Arbitrarily changing the container tag in an installed instance is not a standard update.

18. Typical faults and solutions

19. Location of files and components

Access inside the container:

sudo docker compose --env-file /opt/cshark-stand/.env \
  -f /opt/cshark-stand/compose.yml exec core sh
docker run --rm cshark-core:<version> cat /etc/os-release    # base OS of the image

20. Technical support

The procedure for processing requests, priorities and response times are given in the document “Description of processes ensuring maintenance of the software life cycle”.