This chapter explains how deployment conformance demonstrates what was deployed, how it was built, whether its dependencies are ready, whether the business functions are available, and how failure is handled through rollback. The node services, website backend, and frontend static resources of OpenAgenet (OAN) should separately record the source commit, build artifacts, configuration version, and acceptance evidence. The official deployment describes a runnable instance, while the protocol requirements apply to every implementation that claims conformance to the specification.

20.1 Reference Deployment Topology

The reference topology consists of the Root platform, Registrar nodes, Discovery nodes, the content distribution platform, the off-chain trust indexer, databases, and the official website. Only necessary endpoints protected by TLS and a reverse proxy are exposed externally. Nodes communicate using configured service addresses and authorization materials. Third-party nodes may be deployed independently, but they must pass conformance checks for node identity, authorization, interfaces, and synchronization before joining.

The deployment topology should separately identify public entry points, internal services, databases, and governance data sources. Public addresses, ports, and node counts are environment configuration and should not be fixed in the diagram as protocol requirements.

During deployment, checks can be organized around four boundaries: public entry points, business services, state storage, and governance and synchronization. The official website and reverse proxy belong to the access boundary; node services carry registration, publication, distribution, or discovery workflows; databases store the runtime state of their respective services; and the off-chain trust indexer reads governance events and builds a read model. The specific hosts and ports at each boundary may change between environments, but every cross-boundary connection should identify its initiator, target, purpose, authentication materials, and the impact of failure.

20.2 Configuration and Secret Management

Configuration is injected per environment. The code package must not carry production private keys, database credentials, or external service tokens. The node DID private key, Root platform authorization materials, database connection information, on-chain package or object configuration, and discovery and distribution endpoints should have restricted file permissions and separate backups. Required fields should be checked before startup; during rotation, the audit record for the old and new configurations should be retained. A failed pre-start check should prevent the service from entering the ready state. Configuration rotation should record the expiration time of the old configuration, the activation time of the new configuration, and the verification result.

The following minimal record can be used as release evidence for configuration checks. The values indicate only whether a value exists and whether it passed validation; secrets must not be written into the report:

profile=production
service=oan-homepage-backend
OAN_HOMEPAGE_LISTEN_ADDR=present:valid
OAN_OFFICIAL_ROOT_ENDPOINT=present:https
OAN_OFFICIAL_REGISTRAR_ENDPOINT=present:https
OAN_OFFICIAL_DISCOVERY_ENDPOINT=present:https
database=present:connected
node_identity=present:did-public-key-match
secrets=not-printed

If a required endpoint, database, node identity, or governance configuration cannot be validated, the deployment should remain in the configuration stage. A successful process start or accessible page must not be used to conceal a missing item.

20.3 Build and Release Artifacts

A release record should include the source code version, lockfile, Rust and frontend build environments, build steps, artifact hashes, configuration version, and release time. Deployment may synchronize a versioned source archive or an equivalent package containing the confirmed version, then generate the Rust backend and frontend static resources in the target build environment. The source archive, binaries, static resources, and configuration should be mutually traceable. Before release, a traceable chain of “source version → build → artifact → deployment” should be established. Temporary source changes or unrecorded build directories in the target environment must not serve as the official source.

A release record can describe the correspondence between artifacts with a summary that contains no secrets:

{
  "sourceCommit": "<git-commit>",
  "lockfile": "<lockfile-sha256>",
  "backendArtifact": "<backend-sha256>",
  "frontendArtifact": "<frontend-sha256>",
  "configFingerprint": "<config-fingerprint>",
  "builtAt": "<utc-time>",
  "environment": "<profile>"
}

The values enclosed in angle brackets are record templates, not fixed official OAN values. During an actual release, they should be replaced with real digests, and the source archive, build log, artifact hashes, and server deployment record should be kept in the same acceptance record.

20.4 Database and Storage Requirements

Before deployment, confirm the database version, connection, migration, and index status. Migrations must be idempotent, traceable, and preceded by a backup. Storage should cover resource registration, versions, credential associations, publication tasks, synchronization cursors, governance events, and the data required for statistics. After recovery, check key records, sequence continuity, queue status, and index consistency; checking only whether the process starts is insufficient.

Database acceptance should separately record that the database can be connected to, migrations are complete, data is available, and consistency remains after recovery. Important checks include the uniqueness of the resource DID and version, idempotency keys for publication tasks, records required by the discovery index, and the continuity of governance events and synchronization cursors. If migrations are complete but a required index is missing, the service should not enter a writable ready state. Database checks must not return internal table structures through public website interfaces. Reports should retain only the necessary version, count, digest, and verification results.

20.5 TLS, Domains, Reverse Proxy, and Network Exposure

The domain and TLS termination point should match the actual service entry point. The reverse proxy should forward only necessary paths while preserving the correct Host, protocol, and client association information. Public ports, cross-origin sources, firewalls, and node-to-node access rules should be configured per environment. Databases, management interfaces, and internal queues must not become exposed to ordinary Internet users because of website proxy configuration. During acceptance, check from both the public network and the internal network the allowed paths, certificate hostname, HTTP-to-HTTPS redirect, CORS scope, and rejection results for non-public paths.

20.6 Deployment Order and Dependency Checks

The recommended order is to record the baseline, back up and synchronize the code, build the artifacts, prepare the database, start the Root platform and its dependent services, then start the Registrar nodes, distribution, Discovery nodes, and indexer, and finally deploy the official website and perform business smoke tests. If any required dependency, migration, health check, or critical smoke test fails, stop at the current step, retain the evidence, and enter repair or rollback. The pass condition for each step should be defined by the dependency actually required by the next step; a started process alone is not a release gate.

20.6.1 Code Synchronization and Build

Generate an archive or equivalent release package from an explicit source code version. After transferring it to the target build environment, verify the files and version information. Compile the node services using the Rust dependencies locked by the project, and generate static resources and backend artifacts using the frontend build script. Do not release from temporary workspace files or unrecorded local build directories.

20.6.2 Database Preparation

Confirm that the backup can be restored, the database is reachable, the migration version is correct, and required indexes are present before running an idempotent migration or startup check. A failed migration must not be followed by starting a service that writes new data. If manual handling is required, retain the failure log, database version, and recovery point.

20.6.3 Node Startup Order

Start the Root platform and its database and publication dependencies first, followed by the Registrar nodes, content distribution platform, Discovery nodes, and off-chain trust indexer. The actual order may be adjusted according to the deployment topology, but before a downstream service starts, confirm that the upstream address, identity, authorization, and interfaces are ready. The existence of a process must not be treated as a substitute for dependency availability.

20.6.4 Service Health Checks

Check process liveness, readiness interfaces, critical dependencies, and configuration loading results one by one, and record the response code, latency, version, and time. A passing health check does not mean that the business path has passed. In particular, separately verify Root platform publication, registration acceptance, discovery queries, distribution, and index synchronization.

20.6.5 Post-deployment Functional Verification

Post-deployment functional verification should cover at least:

1. Health and readiness interfaces.
2. Valid requests and expected failure requests for the Registrar nodes.
3. Root platform publication, content distribution, and synchronization to the Discovery nodes.
4. Exact DID queries and semantic queries.
5. Database migration status, cursors, logs, and alerts.

When any critical item fails, retain the submission, artifact, configuration, and response evidence, and stop the release completion confirmation.

Interface verification should record the request method, actual URL, HTTP status, response type, key business fields, and correlation identifiers. For dynamic JSON interfaces, checking only for a 2xx response is insufficient. Also check that the registration response contains the resource DID and registration status, that the Root platform response is resource-verified-and-queued, that the content distribution response contains a publication cursor, that the discovery response can be deserialized as ResourceDiscoveryResponse, and that the indexer status identifies the current synchronization position. When accessed through the official website proxy, additionally verify that the proxy-path mapping to the original node path has not changed the request body or error semantics.

20.7 Registrar Node Functional Smoke Tests

Use an isolated test identity and controlled resource to verify form or request validation, control signatures, Registrar node acceptance, duplicate submission, and error responses. If the interface returns a registration VC, check its association with the resource DID, version, or digest. Subsequent publication and cleanup of the test resource must not pollute normal resource statistics. Successful registration proves only that the Registrar node accepted the request; it does not automatically prove that the Root platform has published it or that the Discovery nodes have indexed it.

20.8 Discovery Node Functional Smoke Tests

Perform exact DID queries and semantic queries against an isolated test resource that has been published. Check the DID, resource type, version, status, source, Root proof status, and index time. If a query returns no result, an old version, or an interface failure, use the cursor and publication record to determine whether the condition is propagation delay or a functional fault. The pass condition for a semantic query is an explainable candidate and source, not a fixed ranking or an undefined relevance score.

20.9 Root Platform, Distribution, and Indexer Verification

Independently check the publication status of the Root platform, resource or cursor records of the content distribution platform, synchronization status of the off-chain trust indexer, and index results of the Discovery nodes. Each check must state its source, time, and normal criterion. Observing success at the Root platform does not prove that downstream services are already discoverable. The same isolated resource version should be used throughout the verification, and the Root platform publication sequence, distribution digest, index version, and query result should be recorded. Equality of total counts across interfaces must not substitute for a content-consistency check.

20.10 Governance Synchronization Verification

Select a governance event that can be confirmed, and check its on-chain position, event type, trust indexer cursor, node-state read model, and update time. Across two or more consecutive checks, the relationship between the cursor and latest_sequence should match the synchronization state of the deployment environment. The absence of new events must be distinguished from a stopped synchronization process. If governance events have been read but the projection has not been updated, classify the synchronization path as incomplete rather than allowing it to pass solely because the indexer interface responded successfully.

20.11 Upgrade, Rollback, and Compatibility Checks

Before and after an upgrade, check database migrations, protocol versions, resource schemas, historical versions, node interoperability, and rollback paths. Continue an upgrade only when compatibility and backup conditions are satisfied. If the new artifact fails health or business verification, roll back according to the recorded version and configuration, then rerun the key acceptance checks. Upgrade verification should use representative resource DIDs, resource packages, registration requests, and discovery queries rather than checking only whether the service starts.

20.11.1 Pre-upgrade Checks

Record the current software version, binary hash, configuration, database state, and cursor state. Confirm that the backup is readable, the target version can be built, the migration can be rolled back or recovered, and the old version remains available.

20.11.2 Data and Configuration Compatibility

Check newly added fields, resource package and credential structures, protocol routes, environment variables, node authorization materials, and frontend interface expectations. Compatible conversions should be repeatable. Historical data that cannot be converted must stop the release before deployment rather than be silently discarded during runtime.

20.11.3 Rollback Conditions

Evaluate rollback when a database migration fails, a critical health check fails, registration or discovery smoke tests fail, the publication queue becomes abnormal, indexing remains stalled, or a security configuration is incorrect. For irreversible data migrations, first pause writes and process the recovery plan; replacing only the binary is insufficient.

20.11.4 Post-rollback Verification

After rollback, check the service version, configuration, database records, node identity, publication sequence, and synchronization cursor again. Then perform health, registration, discovery, Root platform, distribution, and index verification. Rollback may be closed only when the old version has returned to a demonstrable working state.

20.12 Third-party Node Onboarding and Conformance Testing

Third-party nodes should submit node identity, authorization materials, public endpoints, supported interfaces, and environment information, and pass tests for signature verification, authorization, protocol responses, resource publication, synchronization, querying, security boundaries, and failure recovery. Passing the tests grants onboarding eligibility only within the explicitly defined scope; it does not replace subsequent operational monitoring and governance management. The admission report should specify the node role, authorization domain, interface version, test environment, and validity period. A role, domain, or interface that was not tested must not be inferred to be compliant from another passing item.

The minimum acceptance evidence for a third-party node can be organized in the following order:

node identity -> authorization -> protocol response
              -> controlled registration/publication
              -> synchronization/discovery
              -> failure recovery and evidence review

Testing should first be completed in an independent database and isolated endpoints. A node’s ability to call an interface does not mean that it has authorization, and its ability to synchronize data does not mean that it may publish resources. Every conclusion should be bound to the actual test scope and evidence.

20.13 Reproducible Builds and Release Provenance

Build records should trace artifacts back to the commit and lockfile, and should retain at least the build environment, commands, dependency versions, artifact hashes, and operator. The running binaries, frontend static resources, and source archive on the server should be mutually verifiable. Configuration and secrets are not included in public artifact hashes, but their version or fingerprint should be recorded. For the Rust backend and the official website frontend, build results should be retained separately, and the deployment record should explain how they are combined into the same release batch.

20.14 Environment-specific Configuration Files

Development, test, staging, and production environments should use separate profiles, endpoints, databases, and keys. Test authorization materials and production private keys must not be reused across environments. Configuration changes should have a commit, approval, or operation record. Differences between environments running the same code should be concentrated in configuration rather than implemented through unrecorded manual source edits. During acceptance, verify that the current profile matches the endpoints, database, node identity, and governance objects, so that a passing result in a test environment is not mistakenly recorded as a production pass.

20.15 Post-deployment Functional and Security Verification

The acceptance record summarizes versions, environment, configuration, health interfaces, business smoke tests, database, governance synchronization, permissions, TLS, public ports, and log checks. It should also confirm that private keys have not entered logs or public interfaces, management data is not exposed to ordinary users, and error responses do not disclose secrets. Retain reproducible command output or response summaries. The final conclusion should state the scope, evidence time, uncovered items, and whether the service is permitted to provide services externally. If any critical item is FAIL or uncertain, the overall result must not be written as passed.

References