Storage integration
Storage integration over WOPI
The WOPI protocol between your file store and the O3O editor server, the three addresses that must be right, and how to choose between Nextcloud, your own WOPI host or the embed layer.
On this page
O3O Office Online does not keep your files. Files stay in your storage system (Nextcloud, an internal document store, the disk of your web application). The editor server only reads a file when someone opens it and writes it back when someone saves. This page explains the protocol both sides use and helps you pick the right integration.
WOPI in one paragraph#
WOPI (Web Application Open Platform Interface) is an HTTP protocol between two roles: the WOPI host owns files and permissions, the WOPI client is the editor server. For every open, the host issues an access_token bound to one file and one user. The editor server uses that token to call the host back through three main operations: CheckFileInfo (metadata and permissions), GetFile (content) and PutFile (write a new version). The browser never downloads the file from the host itself.
Three addresses that must be right#
| Address | Who calls whom | Value on a DEV machine |
|---|---|---|
| Editor server discovery | The WOPI host calls /hosting/discovery to learn which URL opens a file | http://o3o-online:9980 (inside the o3o-net network) |
| Editor URL (urlsrc) | The browser loads the editor page in an iframe, always through the proxy | http://localhost:8080/browser/<hash>/cool.html? |
| WOPISrc | The editor server calls the host back to read and write the file | http://o3o-nextcloud/index.php/apps/richdocuments/wopi/files/<id> |
The first two addresses are decided by the O3O server through O3O_ONLINE_SERVER_NAME and O3O_ONLINE_SSL_TERMINATION. The third is decided by the WOPI host; it must be reachable from the o3o-online container and must be declared in an aliasgroupN. Most integration failures come from the third address.
Choose an integration#
| Situation | Use | Status in v1 |
|---|---|---|
| Your users already work in Nextcloud | Nextcloud + richdocuments | Available. Ships as the nextcloud compose profile. |
| Nextcloud AIO or an existing Nextcloud elsewhere | Nextcloud AIO and existing installs | Usable; not yet verified on AIO |
| Your web app has its own file store and wants full control of permissions | Build your own WOPI host | Beta: runs with the DEV image |
| You only need to open a file by URL and receive the edited copy, without writing WOPI | The O3O.Editor embed layer | Available. The gate acts as the WOPI host for you. |
| ownCloud, oCIS | ownCloud and oCIS | Coming soon |
How a document opens over WOPI#
- The WOPI host reads
/hosting/discoveryonce (cache it for a few minutes) to geturlsrcper file extension. - The user opens a file. The host checks permissions, creates an
access_tokenand itsaccess_token_ttlexpiry. - The host page submits a form POST into an iframe to
urlsrc + "WOPISrc=" + file URL, with the token in the form body. - The O3O proxy asks the gate whether a new editing session fits (see connection counting).
- The editor server calls
CheckFileInfothenGetFileon WOPISrc and shows the document. - On autosave, on manual save and when the last user leaves, the editor server calls
PutFile. The gate is not on this path, so it never blocks a save.
Quick check of the editor server#
# Editor address the browser will open (urlsrc)
curl -s http://localhost:8080/hosting/discovery | grep -o 'ext="docx" name="edit" urlsrc="[^"]*"'
# Editor server capabilities
curl -s http://localhost:8080/hosting/capabilities
# Does the gate see the editor server: "upstream": {"coolwsd": "ok", ...}
curl -s http://localhost:8080/o3o/status