Description of CShark software lifecycle maintenance processes

Identification of the provisioned instance

1. Purpose of the document

The document describes the processes for developing, delivering, maintaining, troubleshooting and improving CShark software, as well as the personnel competencies required to carry out these processes.

1.1. Organizational details

The functions of development, testing, DevOps and system administration, as well as technical support are performed by specialists from COMPETENCE LLC. The combination of functions is taken into account when planning work and separating development, verification and release operations in time.

2. Life cycle stages

Life cycle includes:

1. collection and analysis of requirements;
2. change design;
3. code development and review;
4. version generation;
5. assembly and control of the delivery set;
6. installation or update;
7. operational monitoring;
8. processing requests and defects;
9. release of fixes and improvements;
10. discontinuation of version support and migration.

Each change must have an identifier, a description of its purpose, acceptance criteria, and a link to the delivery version.

3. Requirements and change management

Sources of requirements include contractual obligations, operational requests, safety requirements, test results and product plan.

Change before implementation:

• described as a specific testable result;
• classified by priority and risk;
• tested for compatibility with current data and integrations;
• receives acceptance criteria;
• included in the version plan.

4. Development

The source code is stored in a version control system. Development is carried out in isolated changes with mandatory analysis of the affected components.

For changes use:

• static analysis and formatting;
• unit tests;
• integration tests with real PostgreSQL and NATS;
• contract API and event tests;
• checking database migrations;
• interface tests;
• backup and recovery scenarios;
• checking the installation kit.

A change is not considered complete just by running it locally; reproducible checks are required to match its risk.

5. Quality control

Before releasing a version, the following is performed:

1. checking a full set of automated tests;
2. checking the assembly of container images;
3. checking OpenAPI and the generated client;
4. scanning for secret leaks;
5. checking migrations on a clean and existing database;
6. Quick testing of a deployed instance;
7. visual inspection of modified user scripts;
8. checking the delivery archive and checksums;
9. updating documentation.

A blocking defect found stops the release until a fix or a formal decision to port with a fixed limitation is made.

6. Versioning and delivery set

Version links:

• source code identifier;
• versions of container images;
• database schema revision;
• archive manifest;
• checksums;
• installer;
• documentation and list of changes.

For a closed loop, an offline kit is created with local Docker images and APT dependencies. The kit is tested on a clean Ubuntu Server 24.04 LTS AMD64 without access to external repositories.

7. Delivery and installation

Delivery is carried out through a secure server or by transferring an offline archive. SHA-256 is checked before unpacking. The installer re-validates the internal manifest, installs dependencies, applies migrations, and performs quick testing.

Installation results and logs are saved for diagnostic purposes. If an error occurs, the containers stop and the data is not automatically deleted.

8. System update

The current update process is a controlled administrative operation:

1. commit installed version;
2. check free space and system status;
3. create and check a backup copy;
4. obtain an identified set of the new version;
5. check checksums and release notes;
6. check data schema compatibility;
7. apply migrations in a separate step;
8. switch containers to a new version;
9. perform health-check and smoke-test;
10. record the result of the update.

Automatic updating from the user interface is a promising feature. Before its release, the update is performed by the system administrator according to approved instructions.

9. Managing migrations and rollbacks

Core runs only with a compatible database schema. If the schema is behind the application version, startup is blocked until the migrations are applied.

Before updating, the possibility of a reversible rollback is determined. For expand-narrow changes (compatible migrations), the previous version may temporarily run on the new schema. For an incompatible change, rollback is performed only using a separate plan, restoring a verified backup.

10. Operation monitoring

The system state is monitored by:

• /api/health;
• container statuses;
• publishing and event processing metrics;
• Gateway queue depth;
• NATS state;
• Availability of PostgreSQL and S3;
• Core, Gateway and Infrastructure magazines;
• free disk space;
• device status.

Threshold values and alert routing are set in the operational regulations of a specific facility.

11. Registration and classification of requests

The hit should include time, version, user role, sequence of actions, actual and expected results, logs and screenshots if necessary.

Specific time frames for response and recovery are established by the support agreement.

12. Troubleshooting

The elimination process includes:

1. registration of appeal;
2. saving the original state and logs;
3. influence classification;
4. playback on a safe stand;
5. localization of the cause;
6. preparing a fix;
7. regression tests;
8. release of a revised version;
9. installation according to an agreed window;
10. confirmation of the result by the user;
11. updating the knowledge base.

Manual changes to data are allowed only according to an agreed procedure with a backup copy, command log and subsequent verification.

13. Backup and restore

Business data includes a PostgreSQL database and media in S3-compatible storage.

Recommended baseline schedule:

• database - daily;
• full copy of media - weekly;
• test restoration - after changing the procedure and periodically according to operational regulations.

The copy is considered verified only after restoration to a temporary environment and verification of control counters. Media is verified against SHA-256 and the final manifest digest.

14. Security management

The support process includes:

• updating base images and dependencies;
• vulnerability analysis;
• rotation of secrets;
• checking user rights;
• audit of administrative actions;
• control of data storage periods;
• exclusion of secrets and personal data from public reports;
• documenting security patches.

Critical security updates may be released outside of the scheduled cycle.

15. Software improvements

Improvements are generated from user requests, observability results, interface and product plan audits. For each improvement, the user's problem, target result, limitations, and verification method are recorded.

Future development areas include automated updates, development of home screen templates, additional integrations, charging infrastructure and commercial modules. They are not considered features of the current version until a separate release.

16. Documentation

When behavior changes, the following are updated:

• installation instructions;
• description of functional characteristics;
• instruction manual;
• runbook for administrators;
• OpenAPI and event contracts;
• release notes;
• backup and restore instructions.

The documentation stores the current date and the version identifier to which it refers.

17. Personnel required for escort

In a small team, one specialist can combine roles if he has the necessary competencies. For normal operation of the object, a system administrator and a CShark administrator are minimally required; developers and a quality engineer are involved in fixing and releasing new versions.

18. Version deprecation

Before support is discontinued, users are provided with information about the latest supported version, known limitations, and migration path. Before the instance is deleted, the required data is exported, backups are performed, and integration keys are revoked. Support and notification periods are determined by the contract and release policy.