Installation and operations

Prepare application dependencies, environment settings and administration commands.

Last updated: 10 November 2026

On this page

Required components Environment variables Optional import components Initial preparation Administration commands Checking the installation Define backup coverage Verify restoration Updates and logs

Required components

The application runs on Python with FastAPI and Uvicorn; data is stored in PostgreSQL/PostGIS. The browser interface and API must share an HTTPS origin. The session cookie has the Secure attribute. Starting the API process alone does not configure the static interface or HTTPS service.

Component	Packages and purpose
HTTP and validation	`fastapi`, `uvicorn`, `pydantic`, `python-multipart`
Database	`psycopg`, `psycopg-pool`
Geometry and coordinates	`ezdxf`, `pyproj`, `numpy`, `shapely`, `pyshp`, `pyogrio`
Tables and outputs	`openpyxl`, `XlsxWriter`, `reportlab`, `pillow`, `charset-normalizer`
Licence file verification	`cryptography`

Install the package versions specified in the application's requirements.txt. The PostgreSQL database must be ready; the account applying the schema needs permission to create PostGIS and the required tables. Cable splitting also checks the necessary PostGIS geography functions; it returns 503 if they are unavailable.

Environment variables

Administration commands and the API service must use the same database and installation mode. Supply values through the service environment configuration.

Variable	Meaning
`GIS_DSN`	PostgreSQL connection settings for the installation's database and account.
`GIS_DATA`	Data directory for temporary import files, persistent optical measurement files and field attachments. The application account needs write access.
`GIS_MOD`	`dedicated` for an on-premises installation; `saas` for the central service. Defaults to `dedicated`.
`GIS_LISANS_ANAHTARLARI`	Trusted licence verification configuration file.
`GIS_KONTROL_URL`	Central receiver URL for usage submission; if unset, the installation record's value is used.
`GIS_OPTIK_DOSYA_TUTMA_MB`	Physical optical-measurement file retention ceiling per organisation. Set during installation; invalid values use the application default and produce a log entry.
`GIS_WEBHOOK`	`kapali` disables webhook management and delivery; enabled by default.
`GIS_WEBHOOK_HTTP`	`1` permits HTTP targets only in on-premises installations; HTTPS is the default.
`GIS_OGC`	`kapali` disables all OGC service endpoints; enabled by default.
`GIS_OGC_SORGU_ANAHTAR`	`1` enables URL query keys for OGC only; disabled by default.
`GIS_SOR`	`kapali` disables SOR parsing; storing and parsing a file are separate operations.

GIS_DATA is more than temporary storage. Include it alongside the database in your operations plan to retain measurement files and field photo/document attachments. Project bundles do not include measurement-file contents. The smaller of the organisation storage limit and GIS_OPTIK_DOSYA_TUTMA_MB applies to retained files; old measurement files retained for undo are counted too.

Optional import components

FileGDB requires the OpenFileGDB driver in pyogrio; DGN requires the DGN read driver. Only DGN V7 is supported. Driver availability depends on the environment when the process starts; check formats in GET /api/meta. A listed format does not guarantee complete interpretation of every source file.

Initial preparation

Run these commands from the directory containing the application's Python files and within the selected Python environment. Uppercase words are placeholders to fill during installation.

Install dependencies:

bash python3 -m pip install -r requirements.txt

Prepare environment variables, explicitly setting GIS_MOD in particular.
Apply the database schema and prepare the installation identity:

bash python3 manage.py schema python3 manage.py kurulum-kimligi

Create the first super administrator account:

bash python3 manage.py superadmin KULLANICI 'GÖRÜNEN AD'

The password is read from the first line of standard input, not a command-line argument. This command requires at least 10 characters. An existing username is updated, so the command does more than create new accounts. 5. For dedicated installations, complete the licence file workflow. Check its status:

bash python3 manage.py lisans-kontrol

Run the API process through your service manager using ASGI target app:app. Serve the static interface and API routing on the same HTTPS origin. GET /api/auth/check can control access to static application files and returns 204 for a valid session.

Administration commands

Command	Function
`python3 manage.py schema`	Applies the supplied schema file.
`python3 manage.py org KISA_AD 'KURUM ADI'`	Creates an organisation; updates its name if the slug already exists.
`python3 manage.py user KISA_AD KULLANICI 'GÖRÜNEN AD' ROL`	Writes an organisation user; roles are `admin`, `editor` or `viewer`. The password is read from standard input and requires at least 8 characters. Updates an existing username.
`python3 manage.py kullanim-kaydet`	Records the first local usage measurement of the day; does not backfill missed days.
`python3 manage.py talep-uret talep.sosotalep`	Generates the installation's licence request file.
`python3 manage.py rapor-uret AAAA-AA rapor.sosorapor`	Generates a usage report from recorded days in the selected month.
`python3 manage.py telemetri-gonder`	Submits usage according to active settings; does not install a scheduler.

Organisation and user commands are administration tools that write directly to the database. For ordinary user operations, use the application interface or API with permission and quota checks. SaaS organisation management uses the Control Centre. Central administration service authentication is not a general project API key.

Checking the installation

GET /api/health accesses the database and returns ok, projects and kablo_bolme. kablo_bolme indicates that the required PostGIS functionality exists. This response does not prove that the licence permits writes or that every workflow is usable; check licence, session and project permissions separately.

Define backup coverage

Plan the database and GIS_DATA together. The database contains records, relationships, users and transactional data; optical measurement and field photo/document contents are in the data directory. A project bundle is not an installation backup.

Where the supplied operations scripts are installed, soso-gis-backup captures a database dump and a content manifest from the same snapshot, then checks restoration in a separate temporary database. The script's presence does not prove that file storage or an off-server copy is backed up. Hosting location and backup terms are defined in the agreement.

Record the database connection, application role, backup directory and file storage location; do not place secrets in ordinary logs.
Run the backup tool with an authorised administrator account.
Review its exit code and restore verification.
Check that file storage is included in the same recovery plan.
Test recovery in a separate environment; file creation alone does not establish a usable backup.

soso-gis-backup
systemctl status soso-gis-backup
journalctl -u soso-gis-backup

These commands apply to installations prepared with the product's operations scripts and service names. Adapt them if your installation uses other directories or service names. This document does not claim that the commands have been run in your environment.

Verify restoration

YEDEK.dump is a placeholder for your backup file. The operations tool first restores into a new database and verifies the manifest and application role:

soso-gis-restore YEDEK.dump

Activation is a separate administration step that makes changes. The --etkinlestir option stops the service, activates the verified database and retains the previous database under a different name. Follow your organisation's approved recovery plan. Decide beforehand how to preserve records written after the backup and which data-directory copy matches it.

Note: Restoring the database does not also restore the files in the data directory. A health response alone does not establish that every file, permission and workflow is correct.

Updates and logs

Before updating, check database and file backups, a rollback copy of the current application files, and licence status. Apply dependencies and schema from the same release. The schema command is python3 manage.py schema; it uses the same database and installation mode as the API service.

After restart, separately check GET /api/health, sign-in, project reading and a basic edit in an authorised working area. Read the server version from X-GIS-Surum. If an older browser tab shows a refresh notice, refresh the interface; starting the server process alone is not acceptance.

Do not assume restoring old code will always be compatible with new data. Before rolling back, assess how records, files and schema written by the new release behave under the previous version.

journalctl -u soso-gis-api
journalctl -u soso-gis-webhook

Review service start-up, connection and delivery errors in logs; do not add passwords, access keys, webhook secrets or sensitive raw bodies to logs. Check TLS, same-origin routing and secure session-cookie transport at the reverse proxy. Webhook delivery and OGC connections require their own acceptance steps.