Security update: v0.4.0-beta.3 fixes a WebDAV request issue that can terminate the server process. Upgrade older instances promptly.View advisory

Online Preview and WOPI

Separate the Three Open Method Types First

Type	Best for	Key requirement
Built-in previewer	Images, PDFs, text, videos, archive listings, and other types covered by built-in capabilities	Provided by AsterDrive itself; some capabilities are also limited by system setting switches
URL template previewer	Handing a file preview link to an external web page	The external web page can access the preview link generated by AsterDrive
WOPI open method	Online preview or editing for Office files	The WOPI service can call back to AsterDrive’s WOPI API

The most common use of WOPI is opening files such as docx, xlsx, and pptx in OnlyOffice or Collabora. AsterDrive handles file access, sessions, tokens, and locks; the real Office editing interface is provided by the external WOPI service.

Recommended Integration Order

Where to Configure It

Administrator entry:

Admin -> System Settings -> Site Configuration -> Preview Apps

Related configuration:

Admin -> System Settings -> Site Configuration -> Public site URL
Admin -> System Settings -> Network Access

Reverse-proxy notes are in Reverse Proxy.

Why `Public site URL` Is the Most Important Setting

When a WOPI service opens a file, the browser does not read the local file directly. The service uses the WOPI URL given by AsterDrive to call back to AsterDrive and read file information and file content.

So Public site URL must:

Be a real HTTP(S) origin
Use HTTPS in production if possible
Be reachable from the WOPI service environment
Be added one by one for each real entry point in multi-domain deployments

For example:

https://drive.example.com
https://office-drive.example.com

Each item should include only the origin, without a path:

https://drive.example.com

Do not write:

https://drive.example.com/api

Common Docker Network Setups

If AsterDrive and OnlyOffice / Collabora both run in Docker, there are two common routes:

Route	Public site URL	Best for
Both use the public domain	`https://drive.example.com`	Reverse proxy and certificates are ready
Internal domain callback	`https://drive.internal.example.com`	The WOPI service is on the intranet and can resolve the internal domain

Do not set Public site URL directly to http://localhost:3000.
For a WOPI service, localhost usually means its own container or host, not AsterDrive.

Import Through WOPI Discovery

If your WOPI service provides a discovery address, importing is the recommended way to create open methods.

The common shape looks like:

https://office.example.com/hosting/discovery

After import, AsterDrive generates corresponding open methods from the application information returned by discovery. You still need to confirm:

The corresponding file extensions are enabled
Open method ordering is as expected
The open method is preview or edit
Dialog or new-tab opening behavior fits your site’s usage

If the WOPI service updates its discovery content, you may need to re-import or wait for the discovery cache to expire. Cache duration is in the WOPI-related system settings.

When to Use URL Template Previewers

URL template previewers are for “handing an accessible file preview link to an external web page”.

They differ from WOPI in these ways:

URL templates usually do not save back
External services usually receive only one file URL
The external service must be able to access that URL
Intranet addresses, localhost, and plain HTTP links often fail

The built-in Microsoft / Google previewers usually follow this approach. They fit publicly accessible file preview scenarios better than general editing in a private deployment.

Built-In Image Preview

When opening an image, AsterDrive chooses between two sources:

The original file, when the browser can render it directly
A backend-generated and cached medium WebP preview

Administrators change the default strategy here:

Admin -> System Settings -> File Processing -> Media Processing -> Image Preview Strategy

Original first fits sites that prefer opening the actual source file whenever possible. Medium preview first fits sites with many large photos, bandwidth-sensitive object storage, or workflows where users usually want a quick preview before explicitly opening the original. Whichever strategy is selected, formats the browser cannot render fall back to the backend preview.

The image viewer supports fullscreen, zoom, pan, rotation, and previous/next navigation inside the current list, folder, or share scope. If the backend preview is missing on first open, AsterDrive creates an image_preview_generate background task. Before it finishes, the page may show loading or fallback behavior; later opens reuse the cache.

Read-Only Archive Preview

AsterDrive includes archive preview, but it is disabled by default. Administrators need to confirm both:

Admin -> System Settings -> File Processing -> Archive Preview
Admin -> System Settings -> Site Configuration -> Preview Apps

It provides a read-only listing preview:

ZIP
Reads archive metadata and shows folders, files, sizes, and modification times
Does not extract the archive into the user’s folder
Does not provide downloads for individual files inside the archive
Does not replace “online extraction”

When opening an archive for the first time, if the listing is not cached yet, the backend creates an archive_preview_generate background task. The frontend shows generation in progress and retries later automatically; after completion, later opens use the cache directly.

If filenames inside a ZIP look garbled, switch Filename encoding in the preview toolbar. This option only affects ZIP entry name decoding. Common options include:

Auto
UTF-8
GB18030
CP437
CP850
Shift_JIS
Big5
EUC-KR
Windows-1252

Switching encoding regenerates or reads a listing cache for that encoding. This setting only affects filename display in the ZIP listing. It does not modify the archive itself and does not affect online extraction results. If the UI says the current encoding cannot parse this ZIP, switch to an encoding commonly used by the system that produced the archive, such as GB18030 for Chinese Windows environments or CP437 for older English ZIPs.

Administrators can control separately:

Whether the global archive preview switch is enabled
Whether logged-in users can preview in personal spaces and team spaces
Whether public share pages can preview
Source archive size, entry count, manifest size, and scan duration limits

If an archive cannot open, check first:

Whether the global archive preview switch is enabled
Whether the current entry is user-side or share-side, and whether the corresponding switch is enabled
Whether the file is a supported ZIP, not rar, 7z, or another format
Whether the source archive exceeds the size limit
Whether archive preview generation failed in Admin -> Tasks

Audio and Video Preview

For logged-in users, audio and video previews read files according to the current storage policy and support browser Range requests. On public share pages, audio and video first create a short-lived streaming session, then point the player to that temporary URL.

This session is valid for 3 hours by default. Administrators can adjust it here:

Admin -> System Settings -> Runtime -> Share streaming session TTL

It is not the expiration time of the share link itself. The share link’s password, expiration time, and maximum download count are still checked normally. The streaming session is only a temporary Range URL for the browser player.

Save, Version History, and Locks

When WOPI saves back to AsterDrive, it is treated as an overwrite write:

A new version is created after a successful save
Locks appear while the file is being edited; some client or protocol cases allow multiple shared locks on the same resource
Conflicting overwrite, move, or delete operations are rejected while valid locks exist
Expired locks are pruned by background cleanup, and administrators can also clean them manually
If a lock remains abnormally, an administrator can clean it from Admin -> Locks

Whether WOPI supports multi-user collaboration depends on the external service you connect. AsterDrive provides files, tokens, sessions, and locks according to the WOPI protocol. It does not implement the collaborative editing interface for the external Office service.

When CORS Needs Changes

Most WOPI callback problems are not CORS. They are usually that the WOPI service cannot access Public site URL.

Only adjust this setting when the browser console clearly reports an AsterDrive API cross-origin error:

Admin -> System Settings -> Network Access -> Allowed CORS origins

If only the OnlyOffice / Collabora backend request to AsterDrive fails, check network, domain name, certificate, and reverse proxy first.

Pre-Launch Validation

Test with real Office files:

docx opens
xlsx opens
pptx opens
After saving, the file content in AsterDrive updates
Version history shows the new version
Lock is released after closing the editor
Similar files on share pages or team spaces behave as expected

If you only plan to provide preview, not editing, also confirm the button copy and behavior in the UI match expectations so users do not think they can save.

Common Problems

Open Method Does Not Appear

Check first:

Whether the preview app is enabled
Whether the file extension is covered by this app
Whether the current user has permission to read the file
Whether another open method takes precedence in preview app ordering

Blank Screen After Opening

The most common cause is that the WOPI service cannot call back to AsterDrive. Check:

Whether Public site URL is truly reachable
Whether the WOPI service container or host can resolve the domain
Whether the TLS certificate is trusted by the WOPI service
Whether the reverse proxy passes /api/v1/wopi/

Opens but Cannot Save