Storage¶
File storage is done on a Simple Storage System (i.e. S3), with file
versioning enabled. All configurations for connecting to the
storage, including the name of the bucket used, are defined in the
file /conf/env.app.
Prefixes (directories)¶
The used prefixes (which can be conceptually considered as directories) on S3 for users files storage, are the following:
| Prefix | Contents | File names | Metadata |
|---|---|---|---|
| `/projects/ |
The files of the QFieldCloud project, uploaded by the user | Actual file name including the relative path (e.g. `foo/bar/project.qgs`) | `Sha256sum` containing the sha256 hashcode of the file |
| `/projects/ |
The deltafiles with the changes to the data, uploaded by QField | The file name is the the deltafile id's UUID code | `Sha256sum` containing the sha256 hashcode of the file, `Status` containing the status of the deltafile (e.g. `APPLIED_WITH_CONFLICTS`) |
| `/projects/ |
The files generated by QFieldSync on the server, that are to be downloaded by QField | Actual file name including the relative path (e.g. `foo/bar/project.qgs`) | `Sha256sum` containing the sha256 hashcode of the file |
APIs¶
Here is a rough description of how APIs interact with storage.
/files/ endpoints (aka QGIS API)¶
The /files/ endpoints, work directly with files saved with the
/projects/<uuid:projectid>/files/ prefix, so, by uploading a
file, the file is stored as is in the storage. The endpoints to
list, download and delete a file, work directly with the content
of the storage.
/qfield-files/ endpoints (aka QField API)¶
The /qfield-files/ endpoints, work asynchronously. The endpoint
GET /qfield-files/{projectid}/, will run a docker container with
QGIS and QFieldSync that will prepare a project export ready to be
used on QField. The generated files are saved with the prefix
/projects/<uuid:projectid>/export/ that is used by the endpoints
to list and download files for qfield.
/deltas/ endpoints¶
The /deltas/ endpoints, work asynchronously. The endpoint POST
/deltas/{projectid}/, will run a docker container with QGIS and
the apply-deltas script that will apply the deltafile to the
original datasource. Modified files (e.g. file-based datasource
contained in the QFieldCloud project) are updated into original
position (/projects/<uuid:projectid>/files/ prefix). The status
of the apply-deltas script is also stored as metadata of the
deltafile itself.