Preview-ce backend service for Zextras Carbonio
You can preview the following type of files:
- images(png/jpeg/gif/svg)
- docx, doc, odp, odt, ppt, xls, xlsx
You will be able to:
- Get preview of files.
- Generate thumbnail of files.
Preview will always try to output the file in its original format, while thumbnail will convert it to an image. There is no difference in quality between the two, the difference in quality can be achieved only by asking for a jpeg format and changing the quality parameter. Asking for a GIF output can only be done when the input file is a GIF, otherwise it will raise and error.
The service uses Go's standard log/slog library with a TextHandler on stderr.
The log level is controlled by the PREVIEW_LOG_LEVEL environment variable. This is a per-instance,
framework-level knob (equivalent to QUARKUS_LOG_LEVEL in Quarkus services) — it is not part
of the Carbonio networking/application config chain and does not appear in configs.txt or the
registry.
| Value | Effective level | Notes |
|---|---|---|
debug |
DEBUG | All messages |
info (default) |
INFO | Default when variable is absent or empty |
warning / warn |
WARN | Python logging alias accepted |
error |
ERROR | |
critical |
ERROR | Python CRITICAL has no slog equivalent; mapped to Error |
Values are case-insensitive. An unrecognised value causes the service to fail-fast at startup.
Per-instance configuration via systemd drop-in:
systemctl edit carbonio-previewAdd:
[Service]
Environment="PREVIEW_LOG_LEVEL=debug"Automatic migration: When upgrading from the legacy Python service, if config.ini contains
a [log] level key, the --setup migration rewrites it as a systemd drop-in at
/etc/systemd/system/carbonio-preview.service.d/log-level.conf. The pending-setups script
runs systemctl daemon-reload immediately after so the level is active before the service
restarts.
Performance-related knobs are application-layer configuration keys: they are
resolved through the Carbonio config chain and can be set fleet-wide via Consul KV
or overridden per-instance via the matching APPLICATION_CONFIG_* environment variable
(the env override always wins over the KV value). See docs/configs.md
for the authoritative list of keys and defaults.
| Consul KV key | Env override | Default | Description |
|---|---|---|---|
carbonio-preview/image-document/max-concurrent-operations |
APPLICATION_CONFIG_IMAGE_DOCUMENT_MAX_CONCURRENT_OPERATIONS |
CPU count | Max concurrent render operations (image, PDF, document); does not apply to video |
carbonio-preview/document/subprocess-pool-size |
APPLICATION_CONFIG_DOCUMENT_SUBPROCESS_POOL_SIZE |
CPU count | Number of PDFium helper OS subprocesses |
carbonio-preview/cache-max-mb |
APPLICATION_CONFIG_CACHE_MAX_MB |
256 |
Size budget (MiB) of the global rendered-output cache shared by all preview types (image, PDF, document, video); 0 disables it |
carbonio-preview/video/max-concurrent-extractions |
APPLICATION_CONFIG_VIDEO_MAX_CONCURRENT_EXTRACTIONS |
CPU count | Max concurrent video first-frame extraction jobs |
carbonio-preview/image-document/fetch-timeout-seconds |
APPLICATION_CONFIG_IMAGE_DOCUMENT_FETCH_TIMEOUT_SECONDS |
30 |
Timeout (s) for fetching the source blob from carbonio-storages |
carbonio-preview/document/conversion-timeout-seconds |
APPLICATION_CONFIG_DOCUMENT_CONVERSION_TIMEOUT_SECONDS |
15 |
Timeout (s) for carbonio-docs-editor (Collabora) conversion |
Values must be positive integers >= 1 (cache-max-mb also accepts 0 to disable
the cache). An invalid value causes the service to fail-fast at startup.
A few knobs are true per-instance environment variables, set via systemd drop-in
(same mechanism as PREVIEW_LOG_LEVEL) and not part of the config chain:
| Variable | Default | Description |
|---|---|---|
PREVIEW_PDFIUM_WORKER_PATH |
next to main binary | Override path to the carbonio-preview-pdfium-worker binary |
The libvips internal-threads level is a fixed internal constant (1) — it has no env
var or KV key.
Once the service is up and running, APIs will be found here
These are the dependencies that the service has. These dependencies are required to run the service correctly but are not installed by the package. They must be installed if Mandatory otherwise user discretion is advised
| Name | Mandatory/Optional |
|---|---|
| carbonio-storages-ce | Optional |
| carbonio-docs-editor | Optional |
Install carbonio-preview-ce via apt:
sudo apt install carbonio-preview-ceor via yum:
sudo yum install carbonio-preview-ceAfter the installation you must run pending-setups in order to register the service in service-discover.
This will start the service as a daemon and allow carbonio-preview-ce to communicate with the suite using Consul.
To develop this project you will need to configure a proper enviroment.
- download the project from the repository:
git clone 'https://github.com/Zextras/carbonio-preview-ce'- Go to the project folder
virtualenv --python /usr/bin/python3 venv
source venv/bin/activate- Install python libraries
pip3 install -r "dev_requirements.txt"To start the application from command line, go to the project folder and type:
gunicorn controller:app --config gunicorn.conf.pyThere are others alternatives, you can also start the program from the main class (if you want to debug it).
Static analysis is provided by a few tools:
- Bandit: security analysis;
- Flake8: code style and indentation analysis;
- Pre-commit: runs static analysis before every commit;
- autopep8: called automatically by pre-commit to static errors.
Pre-commit needs to be activated in the root directory of the project using:
pre-commit installTo activate commit lint (mandatory) then:
pre-commit install --hook-type commit-msgTo run unit tests manually, run the following command from the project folder:
python -m pytestAll the python libraries used can be found on the "requirements.txt" file.
Official Preview-ce backend service for Zextras Carbonio.
Released under the AGPL-3.0-only license as specified here: COPYING.
See COPYING file for the project license details
See THIRDPARTIES file for other licenses details
All non-software material (such as, for example, names, images, logos, sounds) is owned by Zextras s.r.l. and is licensed under CC-BY-NC-SA.
Where not specified, all source files owned by Zextras s.r.l. are licensed under AGPL-3.0-only