System deployment

This page covers first-time deployment on a new environment. For an existing installation, use Upgrade an existing installation; for recovery after an incident, use Rollback after an incident. Confirm the release, host, and network address in the controlled handover record. Keep real passwords, personnel data, and device parameters out of public documentation.

Deployment scope

For a first deployment, prepare the specified image package, host access, and network details. This page follows the sequence “prepare the host → load images → initialize an empty data volume → configure the first session → accept the site.”

Components and ports

The server side uses three containers. Install the enrollment and display applications on their Android terminals.

Component	Responsibility	Default entry
vittor_web	Serves the management site and forwards business requests	Host HTTP 80, configurable with WEB_PORT
vittor_server	Business APIs, person synchronization, recognition events, and node discovery	Container HTTP 8000; host UDP 20785
vittor_mysql	Stores people, spaces, devices, recognition events, and runtime data	Container 3306; host mapping defaults to 127.0.0.1:3306
Enrollment terminal	Reads identity documents, captures photos, and submits people	Terminal management HTTP 8182; UDP 20785
Display terminal	Receives recognition results and shows on-site status	Terminal management HTTP 8181; local or cloud receiver port by mode

Restrict database, terminal management, and discovery access to the maintenance network that needs it. Person synchronization and node discovery must keep running in the central service.

Prepare the host

1. Install Docker Engine, Docker Compose v2, Bash, and curl.
2. Check that the Web port, loopback database port, and UDP 20785 are free. Terminals must reach the central host on the LAN.
3. Prepare the organization, administrator, space structure, enrollment terminal, and recognition-device setup data.
4. Confirm where the database, personnel photos, and other file resources will be stored and who owns them. Do not clear data volumes to repair a login or business-data issue.
5. Keep database credentials, administrator credentials, device keys, and personnel photos in a controlled location. Redact screenshots, logs, and exported packages before sharing them.

Deployment parameters

The deployment scripts read these values from the current shell. Do not put real passwords in Compose files, scripts, or public documentation.

Parameter	Default	Purpose
MYSQL_ROOT_PASSWORD	required	Required on first start; must match the existing data when a volume is reused
MYSQL_DATABASE	face_tp	Database name
WEB_PORT	80	Web host port
MYSQL_PORT	3306	Database host port, bound to 127.0.0.1
DISCOVERY_HOST	detected	Central host address reachable by terminals
DISCOVERY_HTTP_BASE_URL	derived	Full central URL advertised to terminals
DISCOVERY_PORT	20785	LAN discovery UDP port
DISCOVERY_TIMEOUT	45 seconds	Offline threshold after the last broadcast
VITTOR_PUSH_WORKER	1	Start the person synchronization worker
VITTOR_PUSH_INTERVAL	5 seconds	Synchronization interval
VITTOR_DISCOVERY_WORKER	1	Start the discovery worker
HUIYAN_URL	empty	Default Huiyan or display address
HEARTBEAT_TIMEOUT	60 seconds	Heartbeat offline threshold

On multi-interface, virtual-machine, or container hosts, explicitly set DISCOVERY_HOST and DISCOVERY_HTTP_BASE_URL. Never advertise a container-only or loopback address to terminals.

Use the image package

Copy the package specified in the handover record to the host and enter its directory. The example below uses Bash:

cd /path/to/deployment-package
export MYSQL_ROOT_PASSWORD='provide this through a controlled method'
export DISCOVERY_HOST='192.168.1.20'
export DISCOVERY_HTTP_BASE_URL="http://${DISCOVERY_HOST}:${WEB_PORT:-80}"

# Load images, create volumes, and start the services
bash deploy/load-and-start.sh

When the images are already loaded, run:

bash deploy/start.sh

The scripts check Compose, create external data volumes, wait for database health, and attempt a heartbeat request. load-and-start.sh reads vittor-images.tar.gz from the package by default; set IMAGE_ARCHIVE when the image file is elsewhere.

First start and initialization

On a new empty data volume, the system creates its base data structures and initial configuration for the delivered release. An existing volume is not initialized again when images, environment variables, or containers change.

Use the seeded administrator only for first access. Change the password immediately, then confirm the organization, administrator permissions, spaces, and device configuration. Initialization alone does not create all business relationships; continue with the first-session setup and acceptance steps.

Configure the first session

1. Run bash deploy/status.sh and confirm that vittor_mysql, vittor_server, and vittor_web are stable without repeated restarts.
2. Sign in to the Web management interface and confirm the organization, administrator permissions, and initial spaces.
3. Put enrollment and display terminals on the same LAN and check that they appear in System Configuration through UDP 20785.
4. Push the central address from System Configuration. The enrollment management endpoint is http://device-address:8182/api/config; the display endpoint is http://device-address:8181/api/config. Confirm the saved result on each terminal.
5. Configure the Huiyan or display address for the operating mode, save it, and check connectivity again.

Acceptance before handover

Verify from infrastructure to the physical site:

Layer	Check	Passing result
Services	docker compose ps and logs	All three services are stable; the database is healthy
Web	Open the management site	The operator computer reaches the home and login pages
Central service	GET /api/heartbeat	Returns state=1 with normal service information
Data	Query a known organization, space, and person after login	Data is correct and photos or resources are readable
Discovery	GET /api/discovery/nodes	Enrollment and display nodes appear with reachable addresses
Terminal configuration	Push the central address	Both terminal types save it and reconnect
Synchronization	Create or update a test person	Central record, target device, and task result agree
Recognition loop	Perform one real test recognition	Receiver and display show the same person, device, and time

With the default Web port, run these read-only host checks; replace the address when the port differs:

bash deploy/status.sh
curl --fail http://127.0.0.1/api/heartbeat
curl --fail http://127.0.0.1/api/device/online-count
curl --fail http://127.0.0.1/api/discovery/nodes

An open homepage, healthy database, and successful heartbeat each validate one layer. They do not replace login, data, synchronization, or recognition acceptance. Discovery-node count is also different from online recognition-device count.

Related APIs

API	Purpose	Notes
GET/POST /api/heartbeat	Central-service heartbeat	Does not read or write business data
GET /api/discovery/nodes	List recently discovered system nodes	Controlled by DISCOVERY_TIMEOUT
POST /api/discovery/configure	Push the central address to discovered terminals	Trusted LAN and administrator operation only
GET/POST /api/huiyan/route	Read or change the Huiyan address	Requires an administrator session
GET /api/device/online-count	Count enabled, online recognition devices	For display statistics, not node discovery

See Troubleshooting for business-flow and failure-layer checks.