S3 storage
Face Matcher keeps all image data outside the relational database, in an S3-compatible object store. The database and the APIs hold only metadata plus an imageDataId for each image; the bytes live in S3. The deployment ships SeaweedFS as the store, but any S3-compatible service works, including cloud buckets, because the services use the standard S3 API with access key and secret or an instance profile.
What is stored
| Object | Produced by | Notes |
|---|---|---|
| Face crops | Cameras and edge streams | The cropped face image behind each Face; stored according to the camera's face save strategy |
| Full frames | Cameras and edge streams | The frame a detection came from; stored according to the frame save strategy |
| Pedestrian and object crops | Cameras and edge streams | Same rule as face crops |
| Watchlist member images | REST enrollment and Station | The enrollment photos of each member, kept for as long as the member exists |
Whether crops and frames are stored at all is decided per camera by its save strategies (All, Balanced, MatchedOnly, None) and globally by the NoSqlDataStorageDisabled switch and the data storage settings in PUT /api/v1/Setup/DataStorage. Automatic cleanup removes detections and their images after a retention period (14 days by default). Both are described under Data retention.
Endpoint, bucket and credentials
| Item | Value |
|---|---|
| Endpoint from the host | http://localhost:8333 |
Endpoint inside face-matcher-network | http://seaweedfs:8333 |
| Bucket | face-matcher (S3Bucket__BucketName), objects under the prefix S3Bucket__Folder=sface |
| Credentials | S3Bucket__AccessKey / S3Bucket__SecretKey in section 2.4 of .env, admin/admin by default |
| Authentication type | S3Bucket__AuthenticationType=AccessKeyAndSecret; InstanceProfile or AssumedRole for cloud deployments, with S3Bucket__UseBucketRegion=true and S3Bucket__BucketRegion |
The shipped SeaweedFS identity has admin rights on every bucket. Change the keys before production and, if you move to a cloud bucket, give the platform a policy limited to its bucket; see Operations.
Reading images from your integration
The simplest way to get an image is the REST Image endpoint, GET /api/v1/Images/{imageDataId}, which streams the object and can resize it on the way; it needs no S3 credentials and respects API authentication. When you need bulk or direct access, for example to archive frames or to serve images from your own application, read the objects from S3 directly with the credentials above. The imageDataId you get from GraphQL or from a notification identifies the object.
Station takes the second route for the browser: it generates pre-signed URLs, valid for S3_URL_EXPIRATION=300 seconds, and the browser fetches the image from S3 itself. That is why Station has two S3 addresses in its configuration: S3_ENDPOINT=http://seaweedfs:8333 for the server side and S3_PUBLIC_ENDPOINT for the address the browser can reach. start.sh sets the public endpoint to http://<STATION_PUBLIC_HOST>:8333; if users open Station from another machine and images do not load, this value is the first thing to check, see Station configuration.
Stacks built on top
A product that runs alongside Face Matcher and needs object storage may use the same SeaweedFS instance, but must use its own bucket, never face-matcher. The platform's cleanup jobs delete objects in their bucket by their own rules, and a future release may change the key layout. Create the bucket with the S3 API on seaweedfs:8333 (the shipped identity may create buckets) and give your service its own credentials in your Compose file rather than reusing the platform's .env values.