VOTPort
Let’s talk
Menu

Choose and protect your storage

Understand persistent volumes, ownership checks, network filesystems, and receipt durability.

On this page

Three persistent volumes

Mount What it contains Protection
/data SQLite database, cookie secret, receipt signer, native-transfer identity and issuer keys Private directory, backed up with the matching release
/received Verified received files and tenant subdirectories File backups and capacity monitoring
/outbound Delivery library, uploads, and project directories File backups and capacity monitoring

The state directory should be mode 0700; its database and identity files are private. Received and outbound roots must be real, writable directories. The container normally uses UID 1000.

Named tenants use .vot-tenants.stage/<tenant>/ under the received and outbound roots. Include these subdirectories in backups. The default tenant uses the receive root and cannot upload a path into the reserved subtree.

Filesystem safety checks

Receiving storage must support hard links, stable file identity, namespace synchronization, and coordinated locks. Keep the state directory on local storage. A new or changed NAS remains paused until a platform administrator qualifies it in Storage > Receiving storage; administration remains available to resolve the failed checks.

For Linux SMB3 and NFSv4, qualify server-side permissions and stable acknowledgments as well as mount options. Client-displayed ownership alone is insufficient. Follow the direct receiving guide instead of weakening permissions or synchronization to pass a probe.

Local and network storage

Supported local receiving uses Balanced. Qualified Linux SMB3/CIFS and NFSv4 now also use Balanced, with the POSIX_NAS provider recording server-acknowledged durability. The operation probe does not establish physical-media readback or certify appliance power-loss behavior. Strict NAS receipts are not offered by this implementation.

Incoming files use one payload allocation on the selected destination filesystem. VOTPort verifies them in its private .vot-stage directory, then publishes each completed file by an exclusive hard link to that same inode and removes the private name. No final payload copy or separate staging volume is required. Missing or replaced qualified mounts stop receiving.

Outbound library grants still hash existing files and use Fast receipts without claiming a new durable publication. Qualifying receiving storage does not upgrade those receipts. See verification and receipts.

Capacity and consistency

Allow space for the incoming payloads, receipt and journal metadata, database operations, and any separate delivery staging. Ordinary receiving does not require a second full payload allocation. Multi-file ZIP and grouped downloads can require staging space in addition to the source files.

Keep file snapshots coordinated with a database snapshot. A database record cannot replace a missing file. Do not disable storage synchronization on the only copy while relying on receipt durability claims.

Workflow storage and private snapshots

Library media-check and malware-scanning jobs, plus S3 imports, use private snapshots. Reception jobs retain and check their original received files directly, without another payload snapshot. VOTPORT_WORKFLOW_SNAPSHOT_BYTES controls the global reservation budget; its default is four times the maximum upload size. Allow capacity for those snapshots alongside ordinary transfer staging. Ordinary governed library deliveries reuse existing files without a second full payload copy.

Private files retire seven days after job failure or cancellation, or seven days after grant expiry or revocation. Job history, recipient evidence, and signed events remain; deleting a tenant removes that tenant's records.

Configure S3 import and export

Platform administrators open Storage > Add storage, select S3 storage as the destination type, and connect Amazon S3 or an S3-compatible service.

  1. Enter the connection name, provider, bucket, and region. For a custom provider, enter its endpoint and select path-style addressing if required.
  2. Set an optional Root folder to restrict the connection to a prefix. Job import folders are relative to this root.
  3. Under Authentication, select Access key and enter the access-key ID and secret, plus a session token for temporary credentials. Alternatively, select Use server credentials or IAM role.
  4. Choose bucket-default encryption or an AWS KMS key, select the tenants allowed to use the connection, and leave Connection enabled selected when it is ready for use.
  5. Select Save connection, then Test saved connection. Unsaved edits must be saved before they can be tested.

The test checks bucket listing without writing objects. A successful result does not establish read access to every object, export write permission, or permission to use a KMS key. Check those permissions for the intended import or export.

Saved keys stay in the private server database and its backups; list and save responses never return the secrets. Edit connection defaults to Keep saved credentials when keys exist. Select Access key to replace them or Use server credentials or IAM role to remove the connection’s saved keys and use server-side authentication. Credentials and connection settings change together under the same revision.

Protect database snapshots and archives as credential-bearing backups. Rotating credentials in VOTPort does not remove older copies from existing backups. Temporary session credentials also need replacement before they expire.

With server credentials selected, storage ID media can use:

VOTPORT_STORAGE_MEDIA_ACCESS_KEY_ID=...
VOTPORT_STORAGE_MEDIA_SECRET_ACCESS_KEY=...
VOTPORT_STORAGE_MEDIA_SESSION_TOKEN=...

The session token is optional. In server-credential mode, if the connection-specific access-key pair is absent, VOTPort uses the existing AWS credential provider chain. HTTPS is required except for loopback test endpoints. An SSE-KMS key is applied to export writes; provider IAM and KMS policies still determine access.

Choose a saved connection as the source in Workflows > New delivery, or under Destinations in a project’s settings. A job's optional import selects a storage ID and prefix. VOTPort persists the source inventory before downloading and uses version or ETag conditions to refuse changed objects. Prefix boundaries, byte limits, tenant access, and configuration revisions are enforced. Retrying uses the original inventory instead of silently taking a newer package.

Select the project’s release rule to wait for every destination or release locally after checks and approval while copies run in the background. Export verifies each source against its frozen VOT identity while streaming multipart uploads. Keys include the job and manifest. A signed complete.json is written with create-only semantics after all payload objects finish. Consumers should discover completed packages through that document; a partial object listing is not proof of completion. A retry after a lost response accepts only the identical completion document.

Manage connections through the operator API

PUT /api/workflows/storage accepts a body containing storage and optional credentials, rather than a bare storage object. Use revision: 0 for a new connection or the current returned revision when editing. A stale revision is rejected; reload the connection before saving again.

Omit credentials or use null to retain saved credentials. Use {"mode":"server"} to switch to server credentials, or {"mode":"access_key","access_key_id":"…","secret_access_key":"…","session_token":null} to replace the saved keys. GET /api/workflows/storage reports credential_source as saved or server, without returning secrets.

POST /api/workflows/storage/{id}/test takes {"revision":CURRENT_REVISION} and tests the saved connection. Saving and testing require a platform administrator’s operator session and the X-Votport request header; automation tokens cannot configure storage.

S3 export does not configure Object Lock or provider retention. Apply your own bucket policy or independent archive when physically immutable storage is required. Native Azure/GCS adapters and vendor-specific MAM connectors are not included; integrations can use signed workflow events and the API.

Shared folders and other VOTPort destinations

Storage > Add storage > Destination type also supports Shared folder and Another Votport. For a shared folder, enter its absolute path in Folder on the server. Mount it before use and expose it inside the service container. Adding this destination does not qualify it as the server's direct receive root; that is the separate Receiving storage process.

For another port, save its receive-request URL and optional password. Editing defaults to keeping the saved connection; replace it explicitly when the destination changes. These credentials remain private in the server database and backups. Each destination port applies the request's own tenant, quota, and reception project.

Select up to 16 connections under a project's Destinations. Only S3 connections can be imported as a new delivery's source; shared folders and peer ports are export destinations. See reception workflows and signed trade routes for release policy, retries, custody evidence, and revocation.

For the storage operator API, storage.kind is s3, folder, or votport; directory identifies a shared-folder destination. Peer credentials use {"mode":"votport","request_url":"https://port.example/r/TOKEN","password":null}. Treat the request URL as a secret. Existing S3 credential modes and revision checks still apply.

Read as Markdown