carbonio-preview-ce

README

Carbonio-Preview-ce 🚀

Preview-ce backend service for Zextras Carbonio

You can preview the following type of files:

• images(png/jpeg/gif/svg)
• pdf
• 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.

Logging

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-preview

Add:

[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.

Runtime Tuning

The following per-instance environment variables control performance characteristics. They are set via systemd drop-in (same mechanism as PREVIEW_LOG_LEVEL) and are not part of the Carbonio networking/application config chain.

Variable	Default	Description
PREVIEW_RENDER_CONCURRENCY	CPU count	Max concurrent image-render operations
PREVIEW_PDF_WORKERS	CPU count	PDFium subprocess pool size
PREVIEW_VIPS_CONCURRENCY	1	libvips threads per operation

The two downstream timeouts are Consul KV keys (not env vars), configurable fleet-wide but intentionally omitted from the generated config docs:

Consul KV key	Default	Description
carbonio-preview/timeout-in-seconds	30	Timeout (s) for fetching the source blob from carbonio-storages
carbonio-preview/docs-timeout-in-seconds	15	Timeout (s) for carbonio-docs-editor (Collabora) conversion

Values must be positive integers >= 1. An invalid value causes the service to fail-fast at startup.

APIs Documentation 📚

Once the service is up and running, APIs will be found here

Dependencies 🔗

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

Service installation 🏁

Install carbonio-preview-ce via apt:

sudo apt install carbonio-preview-ce

or via yum:

sudo yum install carbonio-preview-ce

Daemon setup 📈

After 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.

Project setup ⚙️🔧

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"

Debug and run 🔎

To start the application from command line, go to the project folder and type:

gunicorn controller:app --config gunicorn.conf.py

There are others alternatives, you can also start the program from the main class (if you want to debug it).

CI and Tests 🤖

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 install

To activate commit lint (mandatory) then:

pre-commit install --hook-type commit-msg

To run unit tests manually, run the following command from the project folder:

python -m pytest

Tech Stack 💾

All the python libraries used can be found on the "requirements.txt" file.

License

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

Copyright notice

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